From 33d31091367d06532117a5d2b4cbaf18a6d1e097 Mon Sep 17 00:00:00 2001 From: Hiren Kangad Date: Thu, 21 May 2026 09:51:52 +0530 Subject: [PATCH] docs: deployment templates for Cloudflare Tunnel, Caddy, Fly.io, Render MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- examples/README.md | 33 +++++++++++++++ examples/compose/Caddyfile | 14 +++++++ examples/compose/behind-caddy.yml | 55 +++++++++++++++++++++++++ examples/compose/cloudflared-paired.yml | 46 +++++++++++++++++++++ examples/fly.toml | 53 ++++++++++++++++++++++++ examples/render.yaml | 43 +++++++++++++++++++ 6 files changed, 244 insertions(+) create mode 100644 examples/README.md create mode 100644 examples/compose/Caddyfile create mode 100644 examples/compose/behind-caddy.yml create mode 100644 examples/compose/cloudflared-paired.yml create mode 100644 examples/fly.toml create mode 100644 examples/render.yaml diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..577448a --- /dev/null +++ b/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/`. diff --git a/examples/compose/Caddyfile b/examples/compose/Caddyfile new file mode 100644 index 0000000..6eff344 --- /dev/null +++ b/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 + } +} diff --git a/examples/compose/behind-caddy.yml b/examples/compose/behind-caddy.yml new file mode 100644 index 0000000..3c667f1 --- /dev/null +++ b/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: diff --git a/examples/compose/cloudflared-paired.yml b/examples/compose/cloudflared-paired.yml new file mode 100644 index 0000000..436bba4 --- /dev/null +++ b/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 diff --git a/examples/fly.toml b/examples/fly.toml new file mode 100644 index 0000000..899a7f2 --- /dev/null +++ b/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 +# 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://.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 diff --git a/examples/render.yaml b/examples/render.yaml new file mode 100644 index 0000000..a185b25 --- /dev/null +++ b/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