Merge branch 'tvarohohlavy-examples-directory'

README.md

@@ -98,6 +98,10 @@ services:
 
 If you need remote mount capabilities, keep the original configuration with `cap_add: SYS_ADMIN` and `devices: /dev/fuse:/dev/fuse`.
 
+## Examples
+
+See [examples/README.md](examples/README.md) for runnable, copy/paste-friendly examples.
+
 ## Adding your first volume
 
 Zerobyte supports multiple volume backends including NFS, SMB, WebDAV, and local directories. A volume represents the source data you want to back up and monitor.
@@ -158,22 +162,27 @@ Zerobyte can use [rclone](https://rclone.org/) to support 40+ cloud storage prov
 **Setup instructions:**
 
 1. **Install rclone on your host system** (if not already installed):
+
    ```bash
    curl https://rclone.org/install.sh | sudo bash
    ```
 
 2. **Configure your cloud storage remote** using rclone's interactive config:
+
    ```bash
    rclone config
    ```
+
    Follow the prompts to set up your cloud storage provider. For OAuth providers (Google Drive, Dropbox, etc.), rclone will guide you through the authentication flow.
 
 3. **Verify your remote is configured**:
+
    ```bash
    rclone listremotes
    ```
 
 4. **Mount the rclone config into the Zerobyte container** by updating your `docker-compose.yml`:
+
    ```diff
    services:
      zerobyte:
@@ -195,6 +204,7 @@ Zerobyte can use [rclone](https://rclone.org/) to support 40+ cloud storage prov
    ```
 
 5. **Restart the Zerobyte container**:
+
    ```bash
    docker compose down
    docker compose up -d
@@ -212,6 +222,7 @@ For a complete list of supported providers, see the [rclone documentation](https
 Once you have added a volume and created a repository, you can create your first backup job. A backup job defines the schedule and parameters for backing up a specific volume to a designated repository.
 
 When creating a backup job, you can specify the following settings:
+
 - **Schedule**: Define how often the backup should run (e.g., daily, weekly)
 - **Retention Policy**: Set rules for how long backups should be retained (e.g., keep daily backups for 7 days, weekly backups for 4 weeks)
 - **Paths**: Specify which files or directories to include in the backup

docker-compose.yml

@@ -12,15 +12,11 @@ services:
       - SYS_ADMIN
     environment:
       - NODE_ENV=development
-      # - SMB_PASSWORD=secret
     ports:
       - "4096:4096"
-    # secrets:
-    #   - smb-password
     volumes:
       - /etc/localtime:/etc/localtime:ro
       - /var/lib/zerobyte:/var/lib/zerobyte
-
       - ./app:/app/app
       - ~/.config/rclone:/root/.config/rclone
 
@@ -41,7 +37,3 @@ services:
       - /etc/localtime:/etc/localtime:ro
       - /var/lib/zerobyte:/var/lib/zerobyte
       - ~/.config/rclone:/root/.config/rclone
-
-# secrets:
-#   smb-password:
-#     file: ./smb-password.txt

examples/README.md

@@ -0,0 +1,17 @@
+# Examples
+
+This folder contains runnable, copy/paste-friendly examples for running Zerobyte in different setups.
+
+## Table of contents
+
+### Basic usage
+
+- [Basic Docker Compose](basic-docker-compose/README.md) — standard deployment with remote mount support (includes `SYS_ADMIN` + `/dev/fuse`).
+- [Simplified Docker Compose (no remote mounts)](simplified-docker-compose/README.md) — reduced-privilege deployment (no `SYS_ADMIN`, no `/dev/fuse`).
+- [Bind-mount a local directory](directory-bind-mount/README.md) — back up a host folder by mounting it into the container.
+- [Mount an rclone config](rclone-config-mount/README.md) — use rclone-based repository backends by mounting your rclone config.
+- [Secret placeholders + Docker secrets](secrets-placeholders/README.md) — keep secrets out of the DB using `env://...` and `file://...` references.
+
+### Advanced setups
+
+- [Tailscale sidecar](tailscale-sidecar/README.md) — run Zerobyte behind a Tailscale sidecar using shared networking.

examples/basic-docker-compose/.env.example

@@ -0,0 +1,2 @@
+# Timezone used by the container
+TZ=UTC

examples/basic-docker-compose/README.md

@@ -0,0 +1,25 @@
+# Basic Docker Compose
+
+Minimal "standard" deployment for Zerobyte.
+
+This setup enables remote mount backends (NFS/SMB/WebDAV) from inside the container by granting the required capability and FUSE device.
+
+## Prerequisites
+
+- Docker + Docker Compose
+
+## Setup
+
+```bash
+cp .env.example .env
+docker compose up -d
+```
+
+## Access
+
+- UI/API: `http://<host>:4096`
+
+## Notes
+
+- This example uses `cap_add: SYS_ADMIN` and `/dev/fuse` to support mounting remote volumes.
+- Do not place `/var/lib/zerobyte` on a network share.

examples/basic-docker-compose/docker-compose.yml

@@ -0,0 +1,16 @@
+services:
+  zerobyte:
+    image: ghcr.io/nicotsx/zerobyte:latest
+    container_name: zerobyte
+    restart: unless-stopped
+    cap_add:
+      - SYS_ADMIN
+    devices:
+      - /dev/fuse:/dev/fuse
+    ports:
+      - "4096:4096"
+    environment:
+      - TZ=${TZ:-UTC}
+    volumes:
+      - /etc/localtime:/etc/localtime:ro
+      - /var/lib/zerobyte:/var/lib/zerobyte

examples/directory-bind-mount/.env.example

@@ -0,0 +1,8 @@
+# Timezone used by the container
+TZ=UTC
+
+# Absolute path on the Docker host to back up.
+# Examples:
+# - /srv/data
+# - /mnt/storage/photos
+HOST_DATA_DIR=/path/to/your/directory

examples/directory-bind-mount/README.md

@@ -0,0 +1,34 @@
+# Bind-mount a local directory
+
+This example shows how to back up a host directory by bind-mounting it into the Zerobyte container.
+
+It uses the simplified setup (no remote mounts).
+
+## Prerequisites
+
+- Docker + Docker Compose
+
+## Setup
+
+1. Copy the env file:
+
+```bash
+cp .env.example .env
+```
+
+2. Edit `.env` and set `HOST_DATA_DIR` to the directory you want to back up.
+
+3. Start the stack:
+
+```bash
+docker compose up -d
+```
+
+## Use in Zerobyte
+
+- Create a new volume of type **Directory**
+- Select the mounted path shown in the compose file: `/mydata`
+
+## Access
+
+- UI/API: `http://<host>:4096`

examples/directory-bind-mount/docker-compose.yml

@@ -0,0 +1,13 @@
+services:
+  zerobyte:
+    image: ghcr.io/nicotsx/zerobyte:latest
+    container_name: zerobyte
+    restart: unless-stopped
+    ports:
+      - "4096:4096"
+    environment:
+      - TZ=${TZ:-UTC}
+    volumes:
+      - /etc/localtime:/etc/localtime:ro
+      - /var/lib/zerobyte:/var/lib/zerobyte
+      - ${HOST_DATA_DIR:?HOST_DATA_DIR must be set}:/mydata

examples/rclone-config-mount/.env.example

@@ -0,0 +1,8 @@
+# Timezone used by the container
+TZ=UTC
+
+# Absolute path on the Docker host to your rclone config directory.
+# Common locations:
+# - Linux: /home/<user>/.config/rclone
+# - Linux (root): /root/.config/rclone
+RCLONE_CONFIG_DIR=/path/to/rclone/config

examples/rclone-config-mount/README.md

@@ -0,0 +1,41 @@
+# Mount an rclone config (for rclone repositories)
+
+This example shows how to make an existing rclone configuration available inside the Zerobyte container.
+
+Use this if you want to use **rclone** as a repository backend (Dropbox/Google Drive/OneDrive/etc.).
+
+## Prerequisites
+
+- Docker + Docker Compose
+- An existing rclone config directory on the Docker host
+
+If you don't have one yet:
+
+```bash
+rclone config
+```
+
+## Setup
+
+1. Copy the env file:
+
+```bash
+cp .env.example .env
+```
+
+2. Edit `.env` and set `RCLONE_CONFIG_DIR` to the absolute path of your host rclone config directory.
+
+3. Start the stack:
+
+```bash
+docker compose up -d
+```
+
+## Access
+
+- UI/API: `http://<host>:4096`
+
+## Notes
+
+- This setup does not require `SYS_ADMIN` or `/dev/fuse`.
+- The rclone config is mounted read-only into `/root/.config/rclone`.

examples/rclone-config-mount/docker-compose.yml

@@ -0,0 +1,13 @@
+services:
+  zerobyte:
+    image: ghcr.io/nicotsx/zerobyte:latest
+    container_name: zerobyte
+    restart: unless-stopped
+    ports:
+      - "4096:4096"
+    environment:
+      - TZ=${TZ:-UTC}
+    volumes:
+      - /etc/localtime:/etc/localtime:ro
+      - /var/lib/zerobyte:/var/lib/zerobyte
+      - ${RCLONE_CONFIG_DIR}:/root/.config/rclone:ro

examples/secrets-placeholders/.env.example

@@ -0,0 +1,6 @@
+# Timezone used by the container
+TZ=UTC
+
+# Optional example secret injected via environment variable.
+# Use it in Zerobyte config fields as: env://ZEROBYTE_SMB_PASSWORD
+ZEROBYTE_SMB_PASSWORD=

examples/secrets-placeholders/.gitignore

@@ -0,0 +1,5 @@
+# Secret files - do not commit
+smb-password.txt
+*-password.txt
+*.secret
+*.key

examples/secrets-placeholders/README.md

@@ -0,0 +1,61 @@
+# Secret placeholders (env:// and file://) + Docker secrets
+
+Zerobyte supports **secret placeholders** in many configuration fields (repositories, volumes, notifications).
+Instead of storing raw secrets in the database, you can store a reference that gets resolved at runtime.
+
+Supported formats:
+
+- `env://VAR_NAME` → reads `process.env.VAR_NAME`
+- `file://name` → reads `/run/secrets/name` (Docker Compose / Docker secrets)
+
+This example shows how to run Zerobyte with:
+
+- an environment variable you can reference via `env://...`
+- a Docker secret you can reference via `file://...`
+
+## Prerequisites
+
+- Docker + Docker Compose
+
+This example includes `SYS_ADMIN` and `/dev/fuse` because it’s intended for SMB volumes (remote mounts).
+
+## Setup
+
+1. Copy the env file:
+
+```bash
+cp .env.example .env
+```
+
+2. Create a Docker secret file.
+
+	⚠️ **Important**: never commit real credentials. This folder includes a `.gitignore` to help prevent accidentally committing secret files.
+
+```bash
+printf "your-smb-password" > smb-password.txt
+```
+
+3. Start Zerobyte:
+
+```bash
+docker compose up -d
+```
+
+## Using placeholders in Zerobyte
+
+You can now use the placeholders for example in these Zerobyte configuration fields:
+
+| UI section | Type | Field | Example value |
+| --- | --- | --- | --- |
+| Volumes → Create volume | SMB | Password | `file://smb_password` or `env://ZEROBYTE_SMB_PASSWORD` |
+| Volumes → Create volume | WebDAV | Password | `file://webdav_password` or `env://ZEROBYTE_WEBDAV_PASSWORD` |
+| Repositories → Create repository | S3 | Secret access key | `file://aws_secret_access_key` or `env://AWS_SECRET_ACCESS_KEY` |
+| Repositories → Create repository | SFTP | SSH Private key | `file://sftp_private_key` or `env://SFTP_PRIVATE_KEY` |
+| Notifications → Create notification | Telegram | Bot token | `file://telegram_bot_token` or `env://TELEGRAM_BOT_TOKEN` |
+
+Notes:
+
+- Placeholder names used in these examples are arbitrary; you can choose any valid name.
+- Placeholder names are case-sensitive.
+- With `file://...`, the secret name must be a single path segment (no `/` or `\\`).
+- You can still paste a raw secret, but placeholders can be considered safer and easier to rotate.

examples/secrets-placeholders/docker-compose.yml

@@ -0,0 +1,26 @@
+services:
+  zerobyte:
+    image: ghcr.io/nicotsx/zerobyte:latest
+    container_name: zerobyte
+    restart: unless-stopped
+    # Required for mounting remote volumes (SMB/NFS/WebDAV) from inside the container
+    cap_add:
+      - SYS_ADMIN
+    devices:
+      - /dev/fuse:/dev/fuse
+    ports:
+      - "4096:4096"
+    environment:
+      - TZ=${TZ:-UTC}
+      # Example env-backed secret (refer to it in Zerobyte as env://ZEROBYTE_SMB_PASSWORD)
+      - ZEROBYTE_SMB_PASSWORD=${ZEROBYTE_SMB_PASSWORD:-}
+    secrets:
+      # Example file-backed secret (refer to it in Zerobyte as file://smb_password)
+      - smb_password
+    volumes:
+      - /etc/localtime:/etc/localtime:ro
+      - /var/lib/zerobyte:/var/lib/zerobyte
+
+secrets:
+  smb_password:
+    file: ./smb-password.txt

examples/simplified-docker-compose/.env.example

@@ -0,0 +1,2 @@
+# Timezone used by the container
+TZ=UTC

examples/simplified-docker-compose/README.md

@@ -0,0 +1,25 @@
+# Simplified Docker Compose (no remote mounts)
+
+A reduced-privilege setup for Zerobyte when you do **not** need to mount NFS/SMB/WebDAV from inside the container.
+
+## Prerequisites
+
+- Docker + Docker Compose
+
+## Setup
+
+```bash
+cp .env.example .env
+docker compose up -d
+```
+
+## Access
+
+- UI/API: `http://<host>:4096`
+
+## Trade-offs
+
+- ✅ No `SYS_ADMIN`
+- ✅ No `/dev/fuse`
+- ✅ Still supports all repository backends (local, S3, GCS, Azure, rclone)
+- ❌ Cannot mount remote shares from inside Zerobyte

examples/simplified-docker-compose/docker-compose.yml

@@ -0,0 +1,12 @@
+services:
+  zerobyte:
+    image: ghcr.io/nicotsx/zerobyte:latest
+    container_name: zerobyte
+    restart: unless-stopped
+    ports:
+      - "4096:4096"
+    environment:
+      - TZ=${TZ:-UTC}
+    volumes:
+      - /etc/localtime:/etc/localtime:ro
+      - /var/lib/zerobyte:/var/lib/zerobyte

examples/tailscale-sidecar/.env.example

@@ -0,0 +1,22 @@
+# --- Zerobyte ---
+TZ=UTC
+
+# --- Tailscale ---
+# Create an auth key in the Tailscale admin console.
+# Recommended: ephemeral + pre-approved (or tagged) key.
+TS_AUTHKEY=tskey-auth-xxxxxxxxxxxxxxxxxxxx
+
+# How this node should appear in your tailnet.
+TS_HOSTNAME=zerobyte
+
+# Kernel-mode (false) vs userspace-mode (true).
+# - false: requires /dev/net/tun on the host
+# - true: works on Docker Desktop / hosts without TUN, but you must also remove
+#   the /dev/net/tun device mapping from docker-compose.yml
+TS_USERSPACE=false
+
+# Optional extra args passed to `tailscale up`.
+# Examples:
+# TS_EXTRA_ARGS=--accept-dns=true
+# TS_EXTRA_ARGS=--advertise-tags=tag:backup --accept-routes
+TS_EXTRA_ARGS=

examples/tailscale-sidecar/README.md

@@ -0,0 +1,93 @@
+# Zerobyte + Tailscale sidecar (Docker Compose)
+
+This example runs Zerobyte behind a Tailscale sidecar container so the Zerobyte web UI/API can be reached over your tailnet and Zerobyte can access other devices on your tailnet (based on the ACLs/tags you configure in Tailscale).
+
+It uses a common “sidecar networking” pattern:
+
+- The `tailscale` container brings up a Tailscale node
+- The `zerobyte` container shares the `tailscale` network namespace (`network_mode: service:tailscale`)
+
+## About Tailscale
+
+Tailscale is a mesh VPN built on WireGuard. It connects devices and containers into a private network (“tailnet”) without opening inbound ports on your router or exposing services directly to the public internet.
+
+In this example, Tailscale acts as a secure access layer in front of Zerobyte:
+
+- You reach Zerobyte using the node’s tailnet IP/DNS name.
+- Access can be restricted using Tailscale ACLs/tags.
+
+## Prerequisites
+
+- Docker + Docker Compose
+- A Tailscale account and an auth key
+
+This example supports two Tailscale modes:
+
+- **Kernel mode** (`TS_USERSPACE=false`, default):
+  - requires `/dev/net/tun` on the host
+  - requires `NET_ADMIN`
+  - may require `SYS_MODULE` on some hosts (kept commented out in the compose file)
+
+- **Userspace mode** (`TS_USERSPACE=true`):
+  - does **not** require `/dev/net/tun`
+  - works better on Docker Desktop / restricted hosts
+  - requires a small edit in the compose file (see Troubleshooting)
+
+## Setup
+
+1. Copy the env file and fill in your auth key:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Start the stack:
+
+   ```bash
+   docker compose up -d
+   ```
+
+3. In the Tailscale admin console, confirm the node is present (and approved if your policy requires it).
+
+## Access
+
+- Over Tailscale: `http://<tailscale-ip>:4096` or `http://<tailscale-name>:4096` (if MagicDNS is enabled)
+- Locally (optional): the example publishes `4096:4096` on the host
+
+If you want Zerobyte to be reachable only via Tailscale, remove the `ports:` section from the `tailscale` service in [docker-compose.yml](docker-compose.yml). Zerobyte will still be able to access the internet and other resources outside the tailnet, but UI will only be accessible over Tailscale with possibility to further restrict access to it with ACLs/tags.
+
+## Notes
+
+- `network_mode: service:tailscale` makes Zerobyte share the Tailscale container’s *entire* network namespace (interfaces + routing table).
+- Traffic to tailnet IPs (typically `100.x.y.z`) goes over `tailscale0` and is governed by Tailscale ACLs; traffic to your LAN/Internet may still go over the normal network interface depending on routes and host firewall.
+- If `--accept-routes` is used, the Tailscale container may add routes to your routing table that Zerobyte will also use and be able to access remote networks.
+- If `--accept-dns` is used, Zerobyte will also use Tailscale’s DNS servers.
+- Zerobyte still needs `SYS_ADMIN` and `/dev/fuse` if you intend to mount NFS/SMB/WebDAV volumes from inside the container.
+
+The example uses these environment variables (see [.env.example](.env.example)):
+
+- `TS_AUTHKEY` (required)
+- `TS_HOSTNAME` (optional)
+- `TS_EXTRA_ARGS` (optional; passed to `tailscale up`)
+- `TS_USERSPACE` (optional; set to `true` to use userspace mode)
+- `TZ` (optional)
+
+## Troubleshooting
+
+- If the `tailscale` container can’t start due to missing TUN support, ensure your host has `/dev/net/tun` available and that Docker is allowed to use it.
+- If your tailnet uses ACLs/tags, set `TS_EXTRA_ARGS` accordingly (for example `--advertise-tags=tag:backup`).
+- If the `tailscale` container fails due to Docker Desktop / missing TUN support: set `TS_USERSPACE=true` in your `.env`, remove the `/dev/net/tun:/dev/net/tun` device mapping in [docker-compose.yml](docker-compose.yml), and keep `SYS_MODULE` disabled (commented out).
+
+To confirm the tailnet address of the container:
+
+```bash
+docker exec zerobyte-tailscale tailscale status
+docker exec zerobyte-tailscale tailscale ip -4
+```
+
+To confirm received routes when `--accept-routes` is used in kernel mode:
+(Missing routes could be due to ACLs or because `--accept-routes` is not set or not supported in userspace mode)
+```bash
+docker exec zerobyte-tailscale ip route
+docker exec zerobyte-tailscale ip route show table 52
+```

examples/tailscale-sidecar/docker-compose.yml

@@ -0,0 +1,51 @@
+services:
+  tailscale:
+    image: tailscale/tailscale:stable
+    container_name: zerobyte-tailscale
+    hostname: ${TS_HOSTNAME:-zerobyte}
+    restart: unless-stopped
+    cap_add:
+      - NET_ADMIN
+      # Optional: Some hosts require this for kernel-mode Tailscale.
+      # If it causes issues (common on Docker Desktop), keep it commented out (disabled as shown here).
+      # - SYS_MODULE
+    # Kernel-mode Tailscale (TS_USERSPACE=false) requires /dev/net/tun.
+    # If you switch to userspace mode (TS_USERSPACE=true), you MUST remove this
+    # devices section (or at least this mapping), otherwise the container may
+    # fail to start or hit runtime errors on some hosts.
+    devices:
+      - /dev/net/tun:/dev/net/tun
+    environment:
+      - TS_AUTHKEY=${TS_AUTHKEY}
+      - TS_STATE_DIR=/var/lib/tailscale
+      # Kernel-mode (false) vs userspace-mode (true).
+      - TS_USERSPACE=${TS_USERSPACE:-false}
+      # Optional flags passed to `tailscale up`.
+      # Examples:
+      # - --advertise-tags=tag:zerobyte
+      # - --accept-dns=true --accept-routes
+      - TS_EXTRA_ARGS=${TS_EXTRA_ARGS:-}
+    volumes:
+      - /var/lib/tailscale:/var/lib/tailscale
+    # If you only want access over Tailscale (not from the local network), remove this.
+    ports:
+      - "4096:4096"
+
+  zerobyte:
+    image: ghcr.io/nicotsx/zerobyte:latest
+    container_name: zerobyte
+    restart: unless-stopped
+    # Uncomment if you need to mount NFS/SMB/WebDAV volumes:
+    # cap_add:
+    #   - SYS_ADMIN
+    # devices:
+    #   - /dev/fuse:/dev/fuse
+    # Share the Tailscale network namespace (sidecar pattern)
+    network_mode: service:tailscale
+    depends_on:
+      - tailscale
+    environment:
+      - TZ=${TZ:-UTC}
+    volumes:
+      - /etc/localtime:/etc/localtime:ro
+      - /var/lib/zerobyte:/var/lib/zerobyte