Jannis Braun
531b496618
Make Backspace self-hostable in any homelab environment, not just a clean host
that owns ports 80/443.
install.sh is now mode-aware and auto-detects which fits:
- allinone (default): bundled Caddy + auto-HTTPS — unchanged behavior
- proxy: behind your own reverse proxy (nginx / Traefik / Caddy / Nginx Proxy
Manager / SWAG) — app published on 127.0.0.1:APP_PORT, no bundled Caddy,
prints paste-ready proxy snippets
- tunnel: behind a tunnel (Cloudflare / Tailscale) — same, plus a 90MB upload
cap (under Cloudflare's 100MB body limit) and voice force-disabled (WebRTC
over UDP can't traverse a tunnel)
Port detection is Docker-aware (consults `docker ps` published ports, not just
`ss`), so a host whose proxy already owns 80/443 via iptables DNAT — with no
listening socket for `ss` to see — is correctly detected as "taken" instead of
dead-ending.
docker-compose.proxy.yml is a small overlay, layered via COMPOSE_FILE (written
into .env so no `-f` flags are ever needed), that publishes the loopback port and
parks Caddy in an inert profile. The base compose file is untouched, so All-in-One
behaves exactly as before.
Prebuilt image: .github/workflows/docker-publish.yml builds and pushes a
multi-arch (linux/amd64 + linux/arm64) image to ghcr.io/thezwiss/backspace on
release tags (and manual dispatch), so weak/ARM hosts skip the ~1.6GB local build
(the Vite build OOMs small ARM boxes). install.sh and docker-compose.yml default
to pulling it, fall back to an image already present on the host, and finally to a
from-source build — AGPL §13 commit stamping preserved on every path. Kept
deliberately separate from the desktop-installer workflow (release.yml).
Docs: README gains a "Deployment modes" section (all three modes, nginx / Caddy /
Traefik snippets, GUI-proxy field-by-field, cloudflared ingress, the update path,
and voice-per-mode caveats); docs/systems/deployment.md updated to match.
Verified live on a throwaway VM: proxy + all-in-one end-to-end through install.sh
(with a real Let's Encrypt cert), tunnel config generation, loopback-only binding,
and the local-image fallback path.
106 lines
5.7 KiB
Bash
106 lines
5.7 KiB
Bash
# ─── Backspace Configuration ────────────────────────────────
|
|
# Copy to .env and configure, or run ./install.sh to generate automatically.
|
|
|
|
# Your server's public domain name (required)
|
|
DOMAIN=example.com
|
|
|
|
# ─── Deployment mode ───────────────────────────────────────
|
|
# How this instance is exposed to the internet. ./install.sh sets these for you;
|
|
# only touch them for a fully manual setup.
|
|
#
|
|
# allinone (default) — the bundled Caddy owns ports 80/443 and does automatic
|
|
# HTTPS for DOMAIN. Requires 80/443 free on this host.
|
|
# proxy — you run your OWN reverse proxy (nginx, Traefik, Caddy,
|
|
# Nginx Proxy Manager, SWAG …). No bundled Caddy; the app
|
|
# is published on 127.0.0.1:APP_PORT for your proxy to
|
|
# forward to. Use with:
|
|
# docker compose -f docker-compose.yml \
|
|
# -f docker-compose.proxy.yml up -d
|
|
# tunnel — same as proxy, but fronted by a tunnel (Cloudflare
|
|
# Tunnel, Tailscale …). Point the tunnel's ingress at
|
|
# http://127.0.0.1:APP_PORT. NOTE: voice/WebRTC does NOT
|
|
# traverse a tunnel, and Cloudflare caps request bodies
|
|
# at 100 MB — set MAX_UPLOAD_SIZE below that (see below).
|
|
DEPLOY_MODE=allinone
|
|
|
|
# Host loopback port the app is published on in `proxy`/`tunnel` mode (ignored in
|
|
# `allinone` mode). Your reverse proxy / tunnel forwards to 127.0.0.1:APP_PORT.
|
|
# APP_PORT=8080
|
|
|
|
# ─── Server ─────────────────────────────────────────────────
|
|
# Production/Docker listen port (Caddy reverse-proxies to it). Local development
|
|
# ignores this and uses 3005 — the Vite dev proxy target — set by `pnpm dev`.
|
|
PORT=3000
|
|
HOST=0.0.0.0
|
|
|
|
# ─── Authentication (REQUIRED) ──────────────────────────────
|
|
# Secret that signs login tokens. This MUST be set to a strong random value.
|
|
# Leaving it empty is intentional — `docker compose up` then fails immediately
|
|
# with a clear message instead of the server boot-looping. Generate one with:
|
|
#
|
|
# openssl rand -hex 32
|
|
#
|
|
# (./install.sh fills this in for you automatically — you only touch this when
|
|
# configuring by hand.) Must be at least 32 characters.
|
|
JWT_SECRET=
|
|
|
|
# Registration — set to false to close signups after initial setup
|
|
REGISTRATION_OPEN=true
|
|
|
|
# Max file upload size in bytes (default: 100MB)
|
|
# TUNNEL USERS: Cloudflare (free/pro) hard-caps request bodies at 100 MB, so the
|
|
# 100 MB default lets uploads fail at the edge. Set this below the cap, e.g.
|
|
# 94371840 (90 MB), leaving headroom for multipart overhead. install.sh does
|
|
# this automatically when you pick `tunnel` mode.
|
|
MAX_UPLOAD_SIZE=104857600
|
|
|
|
# ─── AGPL-3.0 § 13 Source Offer ────────────────────────────
|
|
# Backspace is AGPL-3.0. Network users can obtain the source of the running
|
|
# version via GET /api/instance/info and in-app "Source code (AGPL)" links.
|
|
# If you MODIFY Backspace and self-host it, you MUST point this at YOUR fork's
|
|
# source so the offer stays accurate. Defaults to the upstream repository.
|
|
# BACKSPACE_SOURCE_URL=https://github.com/TheZwiss/backspace
|
|
#
|
|
# Short git commit/tag of the running build. Injected automatically at Docker
|
|
# build time by deploy.sh (--build-arg BACKSPACE_COMMIT). Leave unset for local
|
|
# dev — the app reports commit=null. Set manually only for custom build pipelines.
|
|
# BACKSPACE_COMMIT=
|
|
|
|
# ─── Prebuilt image (GHCR) ─────────────────────────────────
|
|
# By default the stack pulls the prebuilt multi-arch image
|
|
# ghcr.io/thezwiss/backspace:latest (published from tagged releases). Pin a
|
|
# specific version for reproducibility, or point at your own fork's registry.
|
|
# BACKSPACE_IMAGE=ghcr.io/thezwiss/backspace
|
|
# BACKSPACE_IMAGE_TAG=latest
|
|
|
|
# ─── LiveKit Voice/Video ───────────────────────────────────
|
|
# To enable voice/video, fill in all three values below and add:
|
|
# COMPOSE_PROFILES=voice
|
|
# Leave empty to run Backspace without voice features.
|
|
LIVEKIT_URL=
|
|
LIVEKIT_API_KEY=
|
|
LIVEKIT_API_SECRET=
|
|
|
|
# ─── Desktop App (Electron) ───────────────────────────────
|
|
# Override the URL that the desktop app loads (auto-detects in dev/prod)
|
|
# BACKSPACE_URL=https://my-instance.com
|
|
|
|
# Auto-update server URL for electron-updater (optional)
|
|
# BACKSPACE_UPDATE_URL=https://releases.example.com
|
|
|
|
# ─── Docker Compose ────────────────────────────────────────
|
|
# Uncomment to enable the LiveKit service:
|
|
# COMPOSE_PROFILES=voice
|
|
|
|
# ─── Database Backups ──────────────────────────────────────
|
|
# Automatic SQLite snapshots: pre-migration (always, when a migration is pending),
|
|
# scheduled (every BACKUP_INTERVAL_HOURS), and manual (./backup.sh). Rotated per type.
|
|
# BACKUP_DIR=./data/backups # default: <data>/backups
|
|
# BACKUP_INTERVAL_HOURS=24
|
|
# BACKUP_KEEP_SCHEDULED=7
|
|
# BACKUP_KEEP_PREMIGRATION=5
|
|
# BACKUP_KEEP_MANUAL=10
|
|
# Off-box replication hook — receives the new snapshot path as $1 (e.g. rclone/rsync/aws s3 cp):
|
|
# BACKUP_OFFSITE_CMD=
|
|
# BACKUP_DISABLED=false
|