+
+{{% alert context="info" %}}
+Mount a host directory on `/home/filebrowser/data` if you want config, database, and cache to persist across container restarts (see {{< doclink path="getting-started/docker/" text="Docker setup" />}}).
+{{% /alert %}}
+
+```yaml
+services:
+ filebrowser:
+ volumes:
+ - '/path/to/folder:/folder'
+ - './data:/home/filebrowser/data'
+ ports:
+ - '80:80'
+ image: gtstef/filebrowser:stable
+ restart: unless-stopped
+```
+
+
+
+## Basic Configuration Example
+
+Here's a minimal config file to get you started:
+
+```yaml
+server:
+ sources:
+ - path: "/path/to/your/files" # or '/folder' in above example (do not load the full os filesystem, must be sub path)
+ config:
+ defaultEnabled: true # Give access to all users by default
+
+auth:
+ adminUsername: admin
+ adminPassword: admin
+```
+
+## Configuration Options
+
+FileBrowser supports extensive configuration options. You can view the complete configuration reference at:
+
+- **Full config example**: {{< doclink path="reference/fullConfig/" text="Full Config Example" />}}
+- **Current config**: In the web UI, Admins can go to Settings > System & Admin > Load Config
+
+### Key Configuration Sections
+
+- **Server Settings**: Port, database, sources, caching
+- **Authentication**: Password, OIDC, proxy authentication
+- **UsersDefaults**: New user defaults
+- **Frontend**: UI customization, themes, branding
+- **Integrations**: Media (FFmpeg) and office (OnlyOffice) support
+
+## Best Practices
+
+### 1. Keep It Simple
+Only configure the settings you need. A minimal config is easier to read and maintain:
+
+```yaml
+server:
+ sources:
+ - path: "/data"
+ config:
+ defaultEnabled: true
+
+auth:
+ adminUsername: admin
+```
+
+### 2. Use Environment Variables for Secrets
+Instead of putting secrets in your config file, use {{< doclink path="reference/environment-variables" text="environment variables" />}}:
+
+```yaml
+auth:
+ methods:
+ oidc:
+ enabled: true
+```
+
+And set environment variables:
+```bash
+FILEBROWSER_ADMIN_PASSWORD="mysecurePassword"
+FILEBROWSER_OIDC_CLIENT_ID=exampleID
+FILEBROWSER_OIDC_CLIENT_SECRET=exampleSecret
+```
+
+### 3. Restart After Changes
+Configuration changes require a restart to take effect:
+
+```bash
+# Stop FileBrowser
+# Edit your config.yaml
+# Start FileBrowser again
+./filebrowser -c config.yaml
+```
+
+## Next Steps
+
+- {{< doclink path="configuration/configuration-overview/" text="Configuration Overview" />}} - Complete configuration guide
+- {{< doclink path="reference/fullconfig/" text="Full Configuration Reference" />}} - All available options
+- {{< doclink path="configuration/sources/" text="Source Configuration" />}} - Configure file sources
+- {{< doclink path="configuration/authentication/" text="Authentication Setup" />}} - Set up authentication methods
diff --git a/content/en/docs/getting-started/config.md b/content/en/docs/getting-started/config.md
index 92ecf3c..586fd60 100644
--- a/content/en/docs/getting-started/config.md
+++ b/content/en/docs/getting-started/config.md
@@ -1,14 +1,20 @@
---
-title: "Configuration Files"
-description: "Understanding and using configuration files in FileBrowser Quantum"
+title: "Configuration Files (v2.0.0)"
+description: "Understanding and using configuration files in FileBrowser v2.0.0 (beta)"
icon: "settings"
date: "2025-10-23T00:50:09Z"
-lastmod: "2026-07-24T01:02:28Z"
+lastmod: "2026-08-10T00:00:00Z"
order: 6
---
+{{% alert context="info" %}}
+**This guide is for v2.0.0 (beta).** It uses the **database** (`filebrowser.sqlite`) and the `server.database.path` config format.
+
+Using **v1.5.x or older**? See the {{< doclink path="getting-started/config-v1.5.x" text="v1.5.x configuration guide" />}} instead.
+{{% /alert %}}
+
{{% alert context="warning" %}}
-**Upgrading to v2.0.0?**
+**Upgrading from v1.x?**
v2.0.0 removes deprecated flat config formats and moves HTTP settings from `server` to `http`. Use the config migration tool and follow the {{< doclink path="getting-started/v2/migration/" text="v2 migration guide" />}} before upgrading.
{{% /alert %}}
@@ -58,7 +64,7 @@ The database path is configured under `server.database.path`. See {{< doclink pa
3. Default location based on deployment type
{{% alert context="info" %}}
-**Upgrading from v1.x?** v2.0.0 uses SQLite instead of BoltDB (`database.db`). Rename your old database, set `migrateFrom`, and follow the {{< doclink path="getting-started/v2/migration/" text="migration guide" />}}. The `FILEBROWSER_DATABASE` env var is removed — use `FILEBROWSER_DATABASE_PATH` instead.
+**Upgrading from v1.x?** v2.0.0 uses a new database instead of the legacy database (`database.db`). Rename your old database file, set `migrateFrom`, and follow the {{< doclink path="getting-started/v2/migration/" text="migration guide" />}}. The `FILEBROWSER_DATABASE` env var is removed — use `FILEBROWSER_DATABASE_PATH` instead.
{{% /alert %}}
## Docker Configuration
@@ -70,7 +76,7 @@ docker run -d \
-v /path/to/your/config.yaml:/home/filebrowser/data/config.yaml \
-v /path/to/your/folder:/folder \
-p 80:80 \
- gtstef/filebrowser:stable
+ gtstef/filebrowser:beta
```
### Using Docker Compose
@@ -89,7 +95,7 @@ services:
- './data:/home/filebrowser/data'
ports:
- '80:80'
- image: gtstef/filebrowser:stable
+ image: gtstef/filebrowser:beta
restart: unless-stopped
```
diff --git a/content/en/docs/getting-started/docker-v1.5.x.md b/content/en/docs/getting-started/docker-v1.5.x.md
new file mode 100644
index 0000000..193e3f1
--- /dev/null
+++ b/content/en/docs/getting-started/docker-v1.5.x.md
@@ -0,0 +1,243 @@
+---
+title: "Docker (v1.5.x)"
+description: "Get started with FileBrowser v1.5.x (stable) using Docker"
+icon: "deployed_code"
+date: "2025-10-08T14:59:30Z"
+lastmod: "2026-08-10T00:00:00Z"
+order: 101
+---
+
+{{% alert context="info" %}}
+**This guide is for v1.5.x and older (stable).** It uses the `stable` Docker image and the **legacy database** (`database.db`).
+
+Looking for **v2.0.0 (beta)**? See the {{< doclink path="getting-started/docker" text="v2.0.0 Docker guide" />}} instead.
+{{% /alert %}}
+
+{{% alert context="warning" %}}
+**Planning to upgrade to v2.0.0?**
+
+v2.0.0 replaces the legacy database with a new database format and requires a one-time migration. Follow the {{< doclink path="getting-started/v2/migration/" text="v2 migration guide" />}} before changing your image tag.
+{{% /alert %}}
+
+The fastest way to get started with FileBrowser Quantum **v1.5.x (stable)**.
+
+## Available Images
+
+Images from Docker Hub (`gtstef/filebrowser`) and GitHub Container Registry (`ghcr.io/gtsteffaniak/filebrowser`):
+
+| Tag | Size | Features | Architectures |
+| ------------------ | ----- | ----------------------------------- | ------------------- |
+| `latest`, `stable` | 60 MB | FFmpeg + document preview | arm64, amd64 |
+| `stable-slim` | 15 MB | Core service only (no media/office) | arm64, arm32, amd64 |
+| `beta` | 60 MB | FFmpeg + document preview | arm64, amd64 |
+| `beta-slim` | 15 MB | Core service only (no media/office) | arm64, arm32, amd64 |
+
+Learn more about the versions and tags {{< doclink path="getting-started/version#docker-version-tags" text="here." />}}
+
+{{% alert context="info" %}}
+To pin a specific v1 release instead of tracking the latest stable, use a version tag such as `1.5-stable` or `1.5.5-stable`.
+{{% /alert %}}
+
+## Quick Try
+
+Test without persistence (changes not saved). In this example we run it mounting the local path:
+
+```bash
+docker run -d \
+ -v $(pwd):/srv \
+ -p 80:80 \
+ gtstef/filebrowser:stable
+```
+
+Access at `http://localhost` with `admin` / `admin`
+
+## Basic Setup with Docker Compose
+
+{{% alert context="warning" %}}
+This set up is just to get the feel of FileBrowser before you get into customization, defining access control, etc. For regular use, check out the slightly upgraded guide {{< doclink path="user-guides/other/standalone-v1.5.x" text="here." />}}
+{{% /alert %}}
+
+
+### Step 1: Create a base folder for FileBrowser
+
+```bash
+mkdir -p filebrowser/data && cd filebrowser
+```
+
+{{% alert context="info" %}}
+**Default Config Location**: In Docker, the default config location is `/home/filebrowser/data/config.yaml`. So we create a `data` directory so we can mount the config, database files, and cacheDir in the same volume. If you don't want to follow this process, you can use {{< doclink path="reference/environment-variables" text="environment variables" />}} to set the config path and database path manually.
+{{% /alert %}}
+
+### Step 2: Create Config
+
+Add a `config.yaml` file inside the `data` directory:
+
+```bash
+touch ./data/config.yaml
+```
+
+Then fill out your config as needed, for example:
+
+```yaml
+server:
+ cacheDir: /home/filebrowser/data/tmp # using the data volume so it can persist across restarts
+ sources:
+ - path: /folder # Do not use a root "/" directory or include the "/var" folder
+ config:
+ defaultEnabled: true
+```
+
+{{% alert context="info" %}}
+**Important**: Source path specified in the `config.yaml` are in terms of container point of view. ({{< doclink path="getting-started/config" text="Check this page for more information on configurations." />}})
+{{% /alert %}}
+
+### Step 3: Create Docker Compose
+
+Create `docker-compose.yaml` in the directory.
+
+```bash
+touch docker-compose.yaml
+```
+
+Then type in the below docker configuration.
+
+```yaml
+services:
+ filebrowser:
+ image: gtstef/filebrowser:stable
+ volumes:
+ - /path/to/your/folder:/folder # Do not use a root "/" directory or include the "/var" folder
+ - ./data:/home/filebrowser/data
+ ports:
+ - 80:80 # exposes port 80 to host, the left-side number can be changed without config.yaml changes.
+ restart: unless-stopped
+```
+
+### Step 4: Start
+
+```bash
+docker compose up -d
+```
+
+### Healthcheck Configuration
+
+{{% alert context="warning" %}}
+This is only needed if you change the `server.port` in the `config.yaml` -- this is not needed for the above guide where the port remains `80` in the `config.yaml`
+{{% /alert %}}
+
+The FileBrowser Docker image includes a default healthcheck that uses port 80:
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+ CMD curl -f http://localhost:80/health || exit 1
+```
+
+If you configure FileBrowser to use a different port in your `config.yaml`, you must override the healthcheck in your `docker-compose.yaml` to match:
+
+```yaml
+services:
+ filebrowser:
+ image: gtstef/filebrowser:stable
+ volumes:
+ - /path/to/your/folder:/folder
+ - ./data:/home/filebrowser/data
+ ports:
+ - 80:8080 # Filebrowser listens on 8080 inside docker, but here we are exposing the host port as 80 still.
+ healthcheck:
+ test: ["CMD", "curl", "-f", "http://localhost:8080/health"] # port should match the internal port 8080
+ interval: 30s
+ timeout: 3s
+ start_period: 10s
+ retries: 3
+ restart: unless-stopped
+```
+
+**Healthcheck options:**
+- `test` - Command to run (must match your configured port)
+- `interval` - Time between health checks (default: 30s)
+- `timeout` - Time to wait for response (default: 3s)
+- `start_period` - Grace period on startup (default: 10s)
+- `retries` - Number of failures before marking unhealthy (default: 3)
+
+## Database Location
+
+{{% alert context="info" %}}
+**Default Database Location**: In Docker, the default database location is `/home/filebrowser/data/database.db`. This is different from the standalone default of `./database.db` in the current directory.
+
+To persist your database, mount a volume to `/home/filebrowser/data`:
+
+```yaml
+services:
+ filebrowser:
+ image: gtstef/filebrowser:stable
+ volumes:
+ - /path/to/files:/folder
+ - ./data:/home/filebrowser/data # Database and config stored here
+```
+
+See {{< doclink path="configuration/server/#database" text="Server configuration" />}} and {{< doclink path="getting-started/config/#how-to-specify-a-config-file" text="configuration file priority" />}} for more information on database paths.
+{{% /alert %}}
+
+## Running container with a different user
+
+{{% alert context="info" %}}
+On `v1.2.x` and earlier, the default user is `root`.
+On `v1.3.x` and later, the default user is `filebrowser` (1000:1000).
+{{% /alert %}}
+
+FileBrowser Quantum docker images have a non-default `filebrowser` user built-in. This user has UID:GID of 1000:1000. In `v1.2.x` and earlier you need to specify this user manually:
+
+Add to docker-compose.yaml:
+```yaml
+services:
+ filebrowser:
+ image: gtstef/filebrowser:stable
+ user: filebrowser
+ volumes:
+ - /path/to/files:/folder
+ - ./data:/home/filebrowser/data
+ ports:
+ - 80:80
+ restart: unless-stopped
+```
+
+You can also specify any user UID:GID, but if you choose a UID other than 1000, you will need to make sure the mounted `data` directory has the same permissions ({{< doclink path="configuration/server#cachedir" text="See cacheDir config" />}})
+
+for example if you wanted to use `1001:1001` user for Unraid installs.
+```bash
+chown -R 1001:1001 ./data
+```
+
+## Privileged ports and container capabilities
+
+### In-container listen (Linux containers)
+
+Linux treats **ports below 1024** as *privileged*: a non-root user needs the **`NET_BIND_SERVICE`** capability (or a lowered `net.ipv4.ip_unprivileged_port_start`) to bind there.
+
+On **rootful** Docker Engine or Docker Desktop, the container still usually gets **`NET_BIND_SERVICE`** in the default capability set, so that user **can** listen on `80` or `443` without extra flags. **`bind: permission denied` on a low `server.port` shows up more often when:**
+
+- you use a **rootless** container engine (**Docker rootless**, **Podman rootless**), or
+- the runtime uses a **stricter** capability profile (some **Podman** installs, explicit `--cap-drop`, hardened policies),
+So the v1.3 switch to a non-root default **pairs with** those environments: the process is no longer UID 0, and if `NET_BIND_SERVICE` is not effective, the kernel rejects the bind. It is **not** “non-root in Docker always breaks port 443 on every machine.”
+
+### non-root runtimes can use `NET_BIND_SERVICE`
+
+Allow binding to ports below 1024 inside the container:
+
+```yaml
+services:
+ filebrowser:
+ cap_add:
+ - NET_BIND_SERVICE
+```
+
+For `docker run`, use `--cap-add=NET_BIND_SERVICE`. **Podman** supports the same flag (or the equivalent in your compose file). Prefer this over `--privileged` unless you need broader host access.
+
+Further reading: [Docker: Runtime privilege and Linux capabilities](https://docs.docker.com/engine/containers/run/#runtime-privilege-and-linux-capabilities).
+
+## Next Steps
+
+- {{< doclink path="configuration/sources/" text="Configure sources" />}}
+- {{< doclink path="configuration/users/" text="Set up users" />}}
+- {{< doclink path="integrations/" text="Enable integrations" />}}
+
diff --git a/content/en/docs/getting-started/docker.md b/content/en/docs/getting-started/docker.md
index 27af178..77ba57b 100644
--- a/content/en/docs/getting-started/docker.md
+++ b/content/en/docs/getting-started/docker.md
@@ -1,19 +1,25 @@
---
-title: "Docker"
-description: "Get started with FileBrowser using Docker"
+title: "Docker (v2.0.0)"
+description: "Get started with FileBrowser v2.0.0 (beta) using Docker"
icon: "deployed_code"
date: "2025-10-08T14:59:30Z"
-lastmod: "2026-07-24T01:02:28Z"
+lastmod: "2026-08-10T00:00:00Z"
order: 1
---
+{{% alert context="info" %}}
+**This guide is for v2.0.0 (beta).** It uses the `beta` Docker image and the **database** (`filebrowser.sqlite`).
+
+Using **v1.5.x or older**? See the {{< doclink path="getting-started/docker-v1.5.x" text="v1.5.x Docker guide" />}} instead.
+{{% /alert %}}
+
{{% alert context="warning" %}}
-**Upgrading to v2.0.0?**
+**Upgrading from v1.x?**
-v2.0.0 uses **SQLite** instead of BoltDB and requires a one-time migration. Use a **directory mount** (`./data:/home/filebrowser/data`) rather than a single database file mount. Replace `FILEBROWSER_DATABASE` with `FILEBROWSER_DATABASE_PATH`. See the {{< doclink path="getting-started/v2/migration/" text="v2 migration guide" />}} before changing your image tag.
+v2.0.0 uses a **new database format** and requires a one-time migration. Use a **directory mount** (`./data:/home/filebrowser/data`) rather than a single database file mount. Replace `FILEBROWSER_DATABASE` with `FILEBROWSER_DATABASE_PATH`. See the {{< doclink path="getting-started/v2/migration/" text="v2 migration guide" />}} before changing your image tag to `beta`.
{{% /alert %}}
-The fastest way to get started with FileBrowser Quantum.
+The fastest way to get started with FileBrowser Quantum **v2.0.0 (beta)**.
## Available Images
@@ -28,6 +34,10 @@ Images from Docker Hub (`gtstef/filebrowser`) and GitHub Container Registry (`gh
Learn more about the versions and tags {{< doclink path="getting-started/version#docker-version-tags" text="here." />}}
+{{% alert context="info" %}}
+To pin a specific v2 release instead of tracking the latest beta, use a version tag such as `2.0-beta` or `2.0.0-beta`.
+{{% /alert %}}
+
## Quick Try
Test without persistence (changes not saved). In this example we run it mounting the local path:
@@ -36,7 +46,7 @@ Test without persistence (changes not saved). In this example we run it mounting
docker run -d \
-v $(pwd):/srv \
-p 80:80 \
- gtstef/filebrowser:stable
+ gtstef/filebrowser:beta
```
Access at `http://localhost` with `admin` / `admin`
@@ -94,7 +104,7 @@ Then type in the below docker configuration.
```yaml
services:
filebrowser:
- image: gtstef/filebrowser:stable
+ image: gtstef/filebrowser:beta
volumes:
- /path/to/your/folder:/folder # Do not use a root "/" directory or include the "/var" folder
- ./data:/home/filebrowser/data
@@ -127,7 +137,7 @@ If you configure FileBrowser to use a different port in your `config.yaml`, you
```yaml
services:
filebrowser:
- image: gtstef/filebrowser:stable
+ image: gtstef/filebrowser:beta
volumes:
- /path/to/your/folder:/folder
- ./data:/home/filebrowser/data
@@ -154,7 +164,7 @@ services:
{{% alert context="warning" %}}
**v2.0.0 change**
-v2.0.0 uses **SQLite** (default: `filebrowser.sqlite`), not BoltDB (`database.db`). Set `server.database.path` in config or use `FILEBROWSER_DATABASE_PATH`. Upgrading from v1.x? See {{< doclink path="getting-started/v2/migration/" text="v2 migration guide" />}}.
+v2.0.0 uses the **database** (default: `filebrowser.sqlite`), not the legacy database (`database.db`). Set `server.database.path` in config or use `FILEBROWSER_DATABASE_PATH`. Upgrading from v1.x? See {{< doclink path="getting-started/v2/migration/" text="v2 migration guide" />}}.
{{% /alert %}}
{{% alert context="info" %}}
@@ -165,7 +175,7 @@ To persist your database, mount a volume to `/home/filebrowser/data`:
```yaml
services:
filebrowser:
- image: gtstef/filebrowser:stable
+ image: gtstef/filebrowser:beta
volumes:
- /path/to/files:/folder
- ./data:/home/filebrowser/data # Database and config stored here
@@ -180,7 +190,7 @@ Docker images run as the built-in `filebrowser` user (UID:GID **1000:1000**) by
```yaml
services:
filebrowser:
- image: gtstef/filebrowser:stable
+ image: gtstef/filebrowser:beta
user: filebrowser
volumes:
- /path/to/files:/folder
diff --git a/content/en/docs/getting-started/linux-v1.5.x.md b/content/en/docs/getting-started/linux-v1.5.x.md
new file mode 100644
index 0000000..c613a0d
--- /dev/null
+++ b/content/en/docs/getting-started/linux-v1.5.x.md
@@ -0,0 +1,144 @@
+---
+title: "Linux (v1.5.x)"
+description: "Install FileBrowser v1.5.x (stable) on Linux"
+icon: "terminal"
+date: "2025-10-08T14:59:30Z"
+lastmod: "2026-08-10T00:00:00Z"
+order: 102
+---
+
+{{% alert context="info" %}}
+**This guide is for v1.5.x and older (stable).** Download a **stable** release from GitHub.
+
+Looking for **v2.0.0 (beta)**? See the {{< doclink path="getting-started/linux" text="v2.0.0 Linux guide" />}} instead.
+{{% /alert %}}
+
+{{% alert context="warning" %}}
+**Planning to upgrade to v2.0.0?**
+
+v2.0.0 requires a config update and one-time database migration. Follow the {{< doclink path="getting-started/v2/migration/" text="v2 migration guide" />}} before upgrading.
+{{% /alert %}}
+
+Run FileBrowser Quantum **v1.5.x (stable)** natively on Linux using the binary releases.
+
+## Download
+
+1. Go to [releases page](https://github.com/gtsteffaniak/filebrowser/releases)
+2. Download the appropriate **stable** binary:
+ - `linux-amd64-filebrowser` (64-bit)
+ - `linux-arm64-filebrowser` (64-bit)
+ - `linux-armv6-filebrowser` (32-bit)
+ - `linux-armv7-filebrowser` (32-bit)
+
+## Make Executable
+
+```bash
+chmod +x filebrowser-linux-amd64
+```
+
+## Optional: Install FFmpeg
+
+```bash
+# Debian/Ubuntu
+sudo apt install ffmpeg
+
+# RHEL/CentOS/Fedora
+sudo dnf install ffmpeg
+
+# Arch Linux
+sudo pacman -S ffmpeg
+```
+
+## Create Configuration
+
+Interactive setup:
+
+```bash
+./filebrowser-linux-amd64 setup
+```
+
+Or create `config.yaml`:
+
+```yaml
+server:
+ port: 80
+ sources:
+ - path: "/home/user/files" # Do not use a root "/" directory or include the "/var" folder
+ config:
+ defaultEnabled: true
+auth:
+ adminUsername: admin
+```
+
+## Run FileBrowser
+
+```bash
+./filebrowser-linux-amd64 -c config.yaml
+```
+
+Access at `http://localhost:80`
+
+## Run as Systemd Service
+
+### Step 1: Move Binary
+
+```bash
+sudo mv filebrowser-linux-amd64 /usr/local/bin/filebrowser
+sudo chmod +x /usr/local/bin/filebrowser
+```
+
+### Step 2: Create Service File
+
+Create `/etc/systemd/system/filebrowser.service`:
+
+```ini
+[Unit]
+Description=FileBrowser Quantum
+After=network.target
+
+[Service]
+Type=simple
+User=filebrowser
+WorkingDirectory=/opt/filebrowser
+ExecStart=/usr/local/bin/filebrowser -c /opt/filebrowser/config.yaml
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### Step 3: Create User and Directory
+
+```bash
+sudo useradd -r -s /bin/false filebrowser
+sudo mkdir -p /opt/filebrowser
+sudo chown filebrowser:filebrowser /opt/filebrowser
+```
+
+### Step 4: Move Config
+
+```bash
+sudo mv config.yaml /opt/filebrowser/
+sudo chown filebrowser:filebrowser /opt/filebrowser/config.yaml
+```
+
+### Step 5: Enable and Start
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable filebrowser
+sudo systemctl start filebrowser
+```
+
+### Check Status
+
+```bash
+sudo systemctl status filebrowser
+```
+
+## Next Steps
+
+- {{< doclink path="configuration/sources/" text="Configure sources" />}}
+- {{< doclink path="configuration/users/" text="Set up users" />}}
+- {{< doclink path="integrations/" text="Enable integrations" />}}
+
diff --git a/content/en/docs/getting-started/linux.md b/content/en/docs/getting-started/linux.md
index 96f9de0..009c178 100644
--- a/content/en/docs/getting-started/linux.md
+++ b/content/en/docs/getting-started/linux.md
@@ -1,24 +1,30 @@
---
-title: "Linux"
-description: "Install FileBrowser on Linux"
+title: "Linux (v2.0.0)"
+description: "Install FileBrowser v2.0.0 (beta) on Linux"
icon: "terminal"
date: "2025-10-08T14:59:30Z"
-lastmod: "2026-07-24T01:02:28Z"
+lastmod: "2026-08-10T00:00:00Z"
order: 2
---
+{{% alert context="info" %}}
+**This guide is for v2.0.0 (beta).** Download a **beta** release from GitHub.
+
+Using **v1.5.x or older**? See the {{< doclink path="getting-started/linux-v1.5.x" text="v1.5.x Linux guide" />}} instead.
+{{% /alert %}}
+
{{% alert context="warning" %}}
-**Upgrading to v2.0.0?**
+**Upgrading from v1.x?**
-v2.0.0 requires a config update and one-time database migration. See the {{< doclink path="getting-started/v2/migration/" text="v2 migration guide" />}} before upgrading from v1.x.
+v2.0.0 requires a config update and one-time database migration. See the {{< doclink path="getting-started/v2/migration/" text="v2 migration guide" />}} before upgrading.
{{% /alert %}}
-Run FileBrowser Quantum natively on Linux using the binary releases.
+Run FileBrowser Quantum **v2.0.0 (beta)** natively on Linux using the binary releases.
## Download
1. Go to [releases page](https://github.com/gtsteffaniak/filebrowser/releases)
-2. Download the appropriate binary (stable or beta):
+2. Download the appropriate **beta** binary:
- `linux-amd64-filebrowser` (64-bit)
- `linux-arm64-filebrowser` (64-bit)
- `linux-armv6-filebrowser` (32-bit)
diff --git a/content/en/docs/getting-started/macos-v1.5.x.md b/content/en/docs/getting-started/macos-v1.5.x.md
new file mode 100644
index 0000000..e8f171e
--- /dev/null
+++ b/content/en/docs/getting-started/macos-v1.5.x.md
@@ -0,0 +1,115 @@
+---
+title: "macOS (v1.5.x)"
+description: "Install FileBrowser v1.5.x (stable) on macOS"
+icon: "laptop_mac"
+date: "2025-10-08T14:59:30Z"
+lastmod: "2026-08-10T00:00:00Z"
+order: 103
+---
+
+{{% alert context="info" %}}
+**This guide is for v1.5.x and older (stable).** Download a **stable** release from GitHub.
+
+Looking for **v2.0.0 (beta)**? See the {{< doclink path="getting-started/macos" text="v2.0.0 macOS guide" />}} instead.
+{{% /alert %}}
+
+{{% alert context="warning" %}}
+**Planning to upgrade to v2.0.0?**
+
+v2.0.0 requires a config update and one-time database migration. Follow the {{< doclink path="getting-started/v2/migration/" text="v2 migration guide" />}} before upgrading.
+{{% /alert %}}
+
+Run FileBrowser Quantum **v1.5.x (stable)** natively on macOS.
+
+## Download
+
+1. Go to [releases page](https://github.com/gtsteffaniak/filebrowser/releases)
+2. Download the **stable** `filebrowser-darwin-amd64` (Intel) or `filebrowser-darwin-arm64` (Apple Silicon) release
+3. Save to a folder
+
+## Enable Permissions
+
+### Step 1: Make Executable
+
+```bash
+chmod +x filebrowser-darwin-arm64
+```
+
+### Step 2: Allow in Security Settings
+
+On first run, macOS will block the app:
+
+1. Try to run: `./filebrowser-darwin-arm64`
+2. Go to **System Preferences** → **Security & Privacy**
+3. Click **Allow** for FileBrowser
+
+## Optional: Install FFmpeg
+
+```bash
+brew install ffmpeg
+```
+
+## Create Configuration
+
+```bash
+./filebrowser-darwin-arm64 setup
+```
+
+Or create `config.yaml`:
+
+```yaml
+server:
+ port: 80
+ sources:
+ - path: "/Users/yourname/Documents"
+ config:
+ defaultEnabled: true
+auth:
+ adminUsername: admin
+```
+
+## Run FileBrowser
+
+```bash
+./filebrowser-darwin-arm64 -c config.yaml
+```
+
+Access at `http://localhost:80`
+
+## Run as Service (launchd)
+
+Create `/Library/LaunchDaemons/com.filebrowser.plist`:
+
+```xml
+
+
+`) will work even if you require authentication for other routes. The share itself may still require a password or user restrictions as configured in FileBrowser.
+{{% /alert %}}
+
+### With Authentication Proxy
+
+For environments using external authentication:
+
+```nginx
+server {
+ listen 80;
+ server_name files.example.com;
+
+ # Authentication endpoint
+ location = /auth/authorize {
+ internal;
+ proxy_pass http://auth.example.com:8080/authorize;
+ proxy_pass_request_body off;
+ proxy_set_header Content-Length "";
+ }
+
+ # Public endpoints (no auth)
+ location /files/public/ {
+ proxy_pass http://filebrowser:8080/files/public/;
+ proxy_set_header Host $host;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_buffering off;
+ }
+
+ # Private endpoints (with auth)
+ location /files/ {
+ auth_request /auth/authorize;
+ auth_request_set $user $upstream_http_x_forwarded_user;
+
+ proxy_pass http://filebrowser:8080/files/;
+ proxy_set_header Host $host;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_set_header X-Forwarded-User $user;
+ proxy_buffering off;
+ client_max_body_size 10G;
+ }
+}
+```
+
+{{% alert context="warning" %}}
+When using external authentication, ensure your auth service sets the `X-Forwarded-User` header with the username. FileBrowser will use this for {{< doclink path="configuration/authentication/proxy/" text="proxy authentication" />}}.
+{{% /alert %}}
+
+## Traefik Configuration
+
+Basic Traefik labels for FileBrowser Quantum:
+
+```yaml
+# Basic routing
+- "traefik.enable=true"
+- "traefik.http.routers.filebrowser.rule=Host(`files.example.com`)"
+- "traefik.http.services.filebrowser.loadbalancer.server.port=80"
+
+# Public endpoints (no auth)
+- "traefik.http.routers.filebrowser-public.rule=Host(`files.example.com`) && PathPrefix(`/public`)"
+- "traefik.http.services.filebrowser-public.loadbalancer.server.port=80"
+```
+
+## Caddy Configuration
+
+Minimal Caddy configuration:
+
+```caddy
+files.example.com {
+ # Public endpoints (no authentication)
+ handle_path /public/* {
+ reverse_proxy filebrowser:80 {
+ header_up Host {host}
+ header_up X-Forwarded-For {remote_host}
+ header_up X-Forwarded-Proto {scheme}
+ }
+ }
+
+ # Private endpoints (with authentication)
+ handle /* {
+ reverse_proxy filebrowser:80 {
+ header_up Host {host}
+ header_up X-Forwarded-For {remote_host}
+ header_up X-Forwarded-Proto {scheme}
+ }
+ }
+}
+```
+
+## Upload Configuration
+
+Essential settings for file uploads:
+
+
+
Nginx
+
client_max_body_size 10G;
+proxy_buffering off;
+
+
Traefik
+
- "traefik.http.middlewares.filebrowser-buffering.buffering.maxRequestBodyBytes=0"
+
+
Caddy
+
reverse_proxy filebrowser:80 {
+ header_up Connection {>Connection}
+ header_up Transfer-Encoding {>Transfer-Encoding}
+}
+
+
Authentication Failures
+
Symptoms: Users can't log in, cookies not working.
+
Solution: Ensure Host header is properly forwarded:
+
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="NGINX" >}}
+```nginx
+proxy_set_header Host $host;
+```
+{{< /tab >}}
+
+{{< tab tabName="Traefik" >}}
+```yaml
+- "traefik.http.services.filebrowser.loadbalancer.passhostheader=true"
+```
+
+{{< /tab >}}
+{{< /tabs >}}
+
+
Upload Failures
+
Symptoms: Large file uploads fail
+
Solution: Increase file size limit and disable buffering:
+
+{{< tabs tabTotal="2" >}}
+{{< tab tabName="NGINX" >}}
+```nginx
+client_max_body_size 10G;
+proxy_buffering off;
+```
+{{< /tab >}}
+{{< tab tabName="Traefik" >}}
+In traefik can be configured via middlewares
+```yaml
+http:
+ middlewares:
+ limit:
+ buffering:
+ maxRequestBodyBytes: 0
+ maxResponseBodyBytes: 0
+ memRequestBodyBytes: 0
+ memResponseBodyBytes: 0
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+
SSE Not Working
+
Symptoms: Real-time features not updating
+
Solution: Disable buffering
+{{< tabs tabTotal="2" >}}
+{{< tab tabName="NGINX" >}}
+```nginx
+proxy_buffering off;
+```
+{{< /tab >}}
+{{< tab tabName="Traefik" >}}
+
+Via traefik middlewares:
+
+```yaml
+http:
+ middlewares:
+ limit:
+ buffering:
+ maxRequestBodyBytes: 0
+ maxResponseBodyBytes: 0
+ memRequestBodyBytes: 0
+ memResponseBodyBytes: 0
+```
+{{< /tab >}}
+{{< /tabs >}}
+