docs: clarify Docker-first deployment guidance and gateway share target mapping

Author: error311

README.md

@@ -46,7 +46,7 @@ Quick links: [Website](https://filerise.net) • [Docs](https://filerise.net/doc
 
 ## Highlights
 
-- 💾 **Self-hosted “cloud drive”** – Runs anywhere with PHP (or via Docker). No external database required.
+- 💾 **Self-hosted “cloud drive”** – Runs on Docker (recommended) or on a standard PHP web server. No external database required.
 - 🔐 **Granular per-folder ACLs** – Manage View (all/own), Upload, Create, Edit, Rename, Move, Copy, Delete, Extract, Share, and more — all enforced consistently across the UI, API, and WebDAV.
 - 🔗 **Link File (authenticated deep links)** – Generate internal links to specific files, require login + ACL checks, and open directly to the target in the app.
 - 🤝 **Folder and file sharing** – Share folders for browsing or upload-only file requests, protect links with passwords/expiration, and share individual files with generated links.
@@ -284,6 +284,8 @@ export PERSISTENT_TOKENS_KEY="$(openssl rand -hex 32)"
 
 Short version: FileRise expects data at `/var/www/{uploads,users,metadata}` and your web server must point to the **public/** folder (for example `DocumentRoot /var/www/filerise/public`).
 
+Docker is the recommended deployment path. Manual installs on a standard PHP web server are supported, but more restrictive shared-hosting environments are best-effort and may not support every feature or background-worker workflow.
+
 Full guide + troubleshooting:  
 [Installation & setup](https://github.com/error311/FileRise/wiki/Installation-Setup) • [Upgrade & migration](https://github.com/error311/FileRise/wiki/Upgrade-and-Migration) • [Reverse proxy & subpath](https://github.com/error311/FileRise/wiki/Reverse-Proxy-and-Subpath)
 

docs/wiki/Home.md

@@ -1,6 +1,6 @@
 # FileRise Wiki
 
-FileRise is a self-hosted web file manager with WebDAV, sharing, and per-folder ACLs. It runs without a database and supports Docker or manual installs.
+FileRise is a self-hosted web file manager with WebDAV, sharing, and per-folder ACLs. It runs without a database and supports Docker or standard PHP web-server installs. Docker is the recommended deployment path; restrictive shared-hosting environments are best-effort.
 
 ## Project philosophy
 

docs/wiki/Pro-Gateway-Shares.md

@@ -17,6 +17,91 @@ In the **Shares** tab, you can:
 
 Gateway records remain reusable across both managed and manual mode.
 
+## Share fields: what they mean
+
+The main fields on a gateway share are:
+
+- `gatewayType`
+  - Managed mode currently supports `sftp` and `s3`.
+- `sourceId`
+  - The FileRise source the share is associated with.
+  - Use `local` for the default local storage root, or another configured source id such as an SMB source.
+- `rootPath`
+  - The FileRise logical scope inside that source.
+  - Use `root` to represent the whole source.
+  - Use a subfolder path such as `projects/acme` to scope the share to that folder inside the source.
+- `managedTarget` (optional, but important)
+  - The actual filesystem path that the managed `rclone serve ...` runtime will expose.
+  - If set, managed mode uses this value directly.
+  - If blank, managed mode tries to derive the target path automatically from the source/root settings.
+- `mode`
+  - `ro` = read only
+  - `rw` = read/write
+- `listenAddr` / `port`
+  - The bind address and port for the managed runtime.
+
+## `rootPath` vs `managedTarget`
+
+These two fields do different jobs:
+
+- `rootPath`
+  - FileRise logical scope/path inside the selected source.
+  - This is how the share is scoped from the FileRise side.
+- `managedTarget`
+  - Actual mounted path that the managed runtime serves on disk.
+  - This is what `rclone serve sftp ... <target>` or `rclone serve s3 ... <target>` will use.
+
+### Local sources
+
+For `local` sources, managed mode can usually derive the target path automatically:
+
+- `sourceId = local`
+- `rootPath = root`
+  - serves the local source root
+- `rootPath = Documentation`
+  - serves the `Documentation` subfolder under that local source root
+
+In those normal local-source cases, `managedTarget` can usually be left blank.
+
+### Non-local sources such as SMB / CIFS
+
+For non-local sources, managed mode requires `managedTarget`.
+
+Current behavior in managed mode is:
+
+- if `managedTarget` is set, it is used directly
+- if `managedTarget` is blank and the source is not `local`, managed mode errors
+
+That means SMB/CIFS, SFTP-source, FTP-source, WebDAV-source, and similar non-local source ids need an explicit mounted target path for managed mode.
+
+### SMB example
+
+If your SMB share is mounted on the host/container at:
+
+`/mnt/client-share`
+
+and you want the gateway to expose:
+
+`/mnt/client-share/projects`
+
+then use:
+
+- `sourceId = <your SMB source id>`
+- `rootPath = projects`
+- `managedTarget = /mnt/client-share/projects`
+
+If you want the whole mounted SMB share, use:
+
+- `sourceId = <your SMB source id>`
+- `rootPath = root`
+- `managedTarget = /mnt/client-share`
+
+Important:
+
+- `managedTarget` does not mount SMB by itself
+- it only tells the managed runtime which already-mounted path to serve
+- the path must exist and be visible from the FileRise / managed-runtime environment
+
 ## rclone runtime in Managed Mode
 
 Managed mode resolves a runtime `rclone` binary in this order:
@@ -34,6 +119,8 @@ From the admin panel you can:
 
 If the bundled file is a placeholder wrapper, Managed status reports that clearly and asks you to install/upload a real binary.
 
+When a managed share starts successfully, the runtime command ends with the resolved target path described above.
+
 ## Docker / container networking notes
 
 - Publish each gateway port on the host (example: `-p 2022:2022`).

docs/wiki/install setup.md

@@ -60,6 +60,8 @@ Bind `/var/www/uploads` to a **dedicated folder** (not the root of a massive sha
 
 ## 2) Manual install (PHP web server)
 
+Docker is the recommended deployment path. Manual installs on a standard PHP web server are supported, but more restrictive shared-hosting environments are best-effort and may not support every feature or background-worker workflow.
+
 ### Requirements
 
 - PHP **8.3+**