docs: deployment templates for Cloudflare Tunnel, Caddy, Fly.io, Render

examples/compose/cloudflared-paired.yml pairs RefBoard with a cloudflared
sidecar reading a TUNNEL_TOKEN env var — no inbound ports needed, suitable
for home / studio servers.

examples/compose/behind-caddy.yml + Caddyfile fronts RefBoard with Caddy
for automatic Let's Encrypt TLS on a public hostname. Caddy 2's
reverse_proxy transparently upgrades Socket.IO WebSockets.

examples/fly.toml deploys to Fly.io using the GHCR image and a persistent
volume mounted at /app/data. STORAGE_BACKEND=fs so the whole stack is one
machine with one disk.

examples/render.yaml is a Render.com Blueprint targeting the same shape
(GHCR image + attached disk + FS storage).

examples/README.md indexes everything and adds notes for Coolify /
Dokploy / CapRover / Railway, which consume the existing compose file
directly without a dedicated template.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

examples/README.md

@@ -0,0 +1,33 @@
+# Deployment examples
+
+Ready-to-use configs for the common ways people host RefBoard. All of these
+use the pre-built image at `ghcr.io/metalfinger/refboard:latest` so you
+don't have to build locally.
+
+| File | What it gives you |
+|---|---|
+| [`compose/minimal-fs.yml`](compose/minimal-fs.yml) | Single container, local filesystem storage, no MinIO. Smallest possible footprint — good for home servers / NAS. |
+| [`compose/cloudflared-paired.yml`](compose/cloudflared-paired.yml) | RefBoard + a Cloudflare Tunnel sidecar. No open inbound ports. Pair with a Cloudflare-managed hostname. |
+| [`compose/behind-caddy.yml`](compose/behind-caddy.yml) | RefBoard + Caddy reverse proxy with automatic Let's Encrypt TLS. For public VPS-style hosts. |
+| [`compose/Caddyfile`](compose/Caddyfile) | Caddyfile consumed by `behind-caddy.yml`. |
+| [`fly.toml`](fly.toml) | Fly.io deployment manifest. FS storage + persistent volume. |
+| [`render.yaml`](render.yaml) | Render.com Blueprint with attached disk. Copy to repo root before importing. |
+
+The default [`docker-compose.yml`](../docker-compose.yml) at the repo root still spins up RefBoard + MinIO for S3-compatible storage. Use that if you want the MinIO console at :9001 or plan to swap in an external S3 bucket later. The variants here use the FS adapter (`STORAGE_BACKEND=fs`) to drop MinIO and keep everything in one container.
+
+## Coolify / Dokploy / CapRover
+
+These PaaS-style self-hosted platforms consume the repo's `docker-compose.yml` (or any of the variants above) directly. Point them at the repo, pick the compose file, set environment variables in the platform's UI, and you're done. Persistent state is the `./.docker-data/` volume — make sure your platform retains it across redeploys.
+
+## Railway
+
+Railway can deploy directly from a Dockerfile or container image. Use:
+
+- Source: container image `ghcr.io/metalfinger/refboard:latest`
+- Port: `8000`
+- Persistent volume: `/app/data` (10+ GB)
+- Env: `STORAGE_BACKEND=fs`, `NODE_ENV=production`, plus optionally `JWT_SECRET`, `CORS_ORIGIN`, `ALLOW_SELF_REGISTRATION`
+
+## Going public from a personal install
+
+The README's [going-public checklist](../README.md#checklist-when-going-public) applies to all of these — set `JWT_SECRET`, lock `CORS_ORIGIN`, confirm self-registration is off, back up `./.docker-data/`.

examples/compose/Caddyfile

@@ -0,0 +1,14 @@
+{$REFBOARD_DOMAIN} {
+    encode zstd gzip
+
+    # Raise upload cap to match RefBoard's MAX_FILE_SIZE_MB. Caddy's default
+    # is 10MB; the value below permits up to 250MB request bodies.
+    request_body {
+        max_size 250MB
+    }
+
+    reverse_proxy refboard:8000 {
+        # WebSocket upgrade is automatic in Caddy 2; nothing extra needed.
+        flush_interval -1
+    }
+}

examples/compose/behind-caddy.yml

@@ -0,0 +1,55 @@
+# RefBoard + Caddy reverse proxy with automatic TLS.
+#
+# Use this on a publicly-reachable host (cloud VPS, dedicated box on a public
+# IP, port 443 open). Caddy provisions and renews a Let's Encrypt cert for
+# the hostname you set in REFBOARD_DOMAIN, and transparently upgrades the
+# Socket.IO WebSocket connection.
+#
+# Setup:
+#   1. Point an A / AAAA record for your hostname at this server's public IP.
+#   2. In .env set:
+#        REFBOARD_DOMAIN=refboard.example.com
+#        CORS_ORIGIN=https://refboard.example.com
+#        JWT_SECRET=$(openssl rand -base64 64)
+#        ALLOW_SELF_REGISTRATION=false
+#   3. docker compose -f examples/compose/behind-caddy.yml up -d
+
+services:
+  refboard:
+    image: ${REFBOARD_IMAGE:-ghcr.io/metalfinger/refboard:latest}
+    container_name: refboard
+    environment:
+      PORT: 8000
+      NODE_ENV: production
+      JWT_SECRET: ${JWT_SECRET:?set JWT_SECRET in .env for public deploys}
+      STORAGE_BACKEND: fs
+      STORAGE_DATA_DIR: /app/data/storage
+      DB_PATH: /app/data/refboard.db
+      CORS_ORIGIN: ${CORS_ORIGIN:?set CORS_ORIGIN to your public URL}
+      MAX_FILE_SIZE_MB: ${MAX_FILE_SIZE_MB:-200}
+      SEED_ADMIN_EMAIL: ${SEED_ADMIN_EMAIL:-}
+      SEED_ADMIN_PASSWORD: ${SEED_ADMIN_PASSWORD:-}
+      ALLOW_SELF_REGISTRATION: ${ALLOW_SELF_REGISTRATION:-false}
+    volumes:
+      - ./.docker-data/refboard:/app/data
+    restart: unless-stopped
+
+  caddy:
+    image: caddy:2-alpine
+    container_name: refboard-caddy
+    depends_on:
+      - refboard
+    ports:
+      - "80:80"
+      - "443:443"
+    environment:
+      REFBOARD_DOMAIN: ${REFBOARD_DOMAIN:?set REFBOARD_DOMAIN in .env}
+    volumes:
+      - ./examples/compose/Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    restart: unless-stopped
+
+volumes:
+  caddy_data:
+  caddy_config:

examples/compose/cloudflared-paired.yml

@@ -0,0 +1,46 @@
+# RefBoard + Cloudflare Tunnel sidecar.
+#
+# Publishes RefBoard at a hostname routed through Cloudflare without opening
+# any inbound ports. Recommended for home / studio servers.
+#
+# Setup:
+#   1. Create a tunnel + DNS record in the Cloudflare Zero Trust dashboard.
+#      Point its public hostname (e.g. refboard.example.com) at
+#      http://refboard:8000  (the in-network service name below).
+#   2. Copy the tunnel token from the dashboard and put it in your .env:
+#        TUNNEL_TOKEN=eyJhIjoi...
+#   3. docker compose -f examples/compose/cloudflared-paired.yml up -d
+#
+# Heads-up: Cloudflare's free plan caps proxied request bodies at 100 MB.
+# If you upload large videos / PDFs regularly, set MAX_FILE_SIZE_MB in .env
+# accordingly or upgrade your Cloudflare plan.
+
+services:
+  refboard:
+    image: ${REFBOARD_IMAGE:-ghcr.io/metalfinger/refboard:latest}
+    container_name: refboard
+    environment:
+      PORT: 8000
+      NODE_ENV: production
+      JWT_SECRET: ${JWT_SECRET:-}
+      STORAGE_BACKEND: fs
+      STORAGE_DATA_DIR: /app/data/storage
+      DB_PATH: /app/data/refboard.db
+      CORS_ORIGIN: ${CORS_ORIGIN:-*}
+      MAX_FILE_SIZE_MB: ${MAX_FILE_SIZE_MB:-90}
+      SEED_ADMIN_EMAIL: ${SEED_ADMIN_EMAIL:-}
+      SEED_ADMIN_PASSWORD: ${SEED_ADMIN_PASSWORD:-}
+      ALLOW_SELF_REGISTRATION: ${ALLOW_SELF_REGISTRATION:-false}
+    volumes:
+      - ./.docker-data/refboard:/app/data
+    restart: unless-stopped
+
+  cloudflared:
+    image: cloudflare/cloudflared:latest
+    container_name: refboard-cloudflared
+    depends_on:
+      - refboard
+    command: tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}
+    environment:
+      TUNNEL_TOKEN: ${TUNNEL_TOKEN:?TUNNEL_TOKEN must be set in .env}
+    restart: unless-stopped

examples/fly.toml

@@ -0,0 +1,53 @@
+# Fly.io deployment manifest for RefBoard.
+#
+# Quick start:
+#   fly auth signup                                  # if you don't have an account
+#   fly launch --copy-config --no-deploy             # creates the app
+#   fly secrets set JWT_SECRET=$(openssl rand -base64 64)
+#   fly volumes create refboard_data --size 10 --region <your-region>
+#   fly deploy
+#
+# Notes:
+# - This uses the pre-built GHCR image and the FS storage adapter so no MinIO
+#   is needed. All state (SQLite + media bytes + JWT secret) lives on the
+#   attached volume.
+# - The first user you sign up in the browser becomes admin. After that, turn
+#   self-registration off in /admin and set ALLOW_SELF_REGISTRATION=false as
+#   a fly secret to lock it in across rebuilds.
+
+app = "refboard"           # change to your unique Fly app name
+primary_region = "iad"     # change to your closest region (fly platform regions)
+
+[build]
+  image = "ghcr.io/metalfinger/refboard:latest"
+
+[env]
+  NODE_ENV = "production"
+  PORT = "8000"
+  STORAGE_BACKEND = "fs"
+  STORAGE_DATA_DIR = "/app/data/storage"
+  DB_PATH = "/app/data/refboard.db"
+  MAX_FILE_SIZE_MB = "200"
+  ALLOW_SELF_REGISTRATION = "false"
+  # Set CORS_ORIGIN via `fly secrets set CORS_ORIGIN=https://<app>.fly.dev`
+
+[http_service]
+  internal_port = 8000
+  force_https = true
+  auto_stop_machines = false
+  auto_start_machines = true
+  min_machines_running = 1
+
+  [http_service.concurrency]
+    type = "requests"
+    soft_limit = 100
+    hard_limit = 200
+
+[[mounts]]
+  source = "refboard_data"
+  destination = "/app/data"
+
+[[vm]]
+  cpu_kind = "shared"
+  cpus = 1
+  memory_mb = 1024

examples/render.yaml

@@ -0,0 +1,43 @@
+# Render.com Blueprint for RefBoard.
+#
+# Quick start:
+#   1. Push this file to a Git repo (it lives at refboard/examples/render.yaml
+#      already, but Render's "New Blueprint" expects render.yaml at the repo
+#      root — copy or symlink it).
+#   2. On Render: New > Blueprint > pick your repo. Render parses this file,
+#      provisions the disk, and starts the service.
+#   3. After first deploy: set JWT_SECRET in the service's Environment tab
+#      (`openssl rand -base64 64`) and re-deploy. Optional but recommended for
+#      production — without it, RefBoard auto-generates one in SQLite.
+#
+# State (SQLite + media bytes + JWT secret) lives on the attached 10 GB disk.
+
+services:
+  - type: web
+    name: refboard
+    runtime: image
+    image:
+      url: ghcr.io/metalfinger/refboard:latest
+    plan: starter         # bump to standard if you want more RAM / CPU
+    healthCheckPath: /health
+    envVars:
+      - key: NODE_ENV
+        value: production
+      - key: PORT
+        value: "8000"
+      - key: STORAGE_BACKEND
+        value: fs
+      - key: STORAGE_DATA_DIR
+        value: /app/data/storage
+      - key: DB_PATH
+        value: /app/data/refboard.db
+      - key: MAX_FILE_SIZE_MB
+        value: "200"
+      - key: ALLOW_SELF_REGISTRATION
+        value: "false"
+      - key: JWT_SECRET
+        sync: false       # set manually in the dashboard
+    disk:
+      name: refboard-data
+      mountPath: /app/data
+      sizeGB: 10