Quick start with Docker

Self-hosters run the same server as syncbins.com — one Node/Fastify process serving the React app, REST API, and WebSocket relay. The web UI is identical; only who runs the box and where blobs live differs.

What you'll have when this is done

A SyncBins instance you control. Metadata in SQLite on disk; encrypted blobs on local disk by default (no cloud account required). Optional: point blobs at Cloudflare R2 or Azure via env vars.

Pick your path

Try it locally

Best for development or testing on your machine. No .env file required.

From the App repo root:

npm run dev:compose

Open http://localhost:5173. The UI proxies /api and /ws to the server container. Data persists under App/server/data/ (SQLite + blobs/).

Stop with Ctrl+C or npm run dev:compose:down.

Note

This uses docker/docker-compose.dev.yml with STORAGE_KIND=local implicitly (server default) and TENANT_MODE=single.

Phone on Wi‑Fi?

http://192.168.x.x is not a secure context on iOS — send/crypto can fail. Use homelab HTTPS (mkcert + docker-compose.dev-tls.yml).

Production (your domain)

One compose stack: SyncBins + Caddy for Let’s Encrypt TLS.

Prerequisites

• A VPS, homelab PC, or Raspberry Pi 4/5 (64-bit OS) with Docker
• A domain (e.g. box.yourdomain.com) pointing at the box — or homelab HTTPS on a LAN
• Ports 80/443 open for ACME (public domain) or mkcert (LAN)

Steps

1. Get the compose bundle — either download syncbins-deploy-*.zip from GitHub Releases (recommended on a Pi), or clone the App repo:

   git clone https://github.com/SyncBins/App.git
   cd App/docker
   cp .env.example .env

   Release zips include docker-compose.yml, Caddyfile, and .env.example ready to run.

2. Set two required values in .env:

   docker/.env

   DOMAIN=box.yourdomain.com
   BLOB_URL_SECRET=…   # openssl rand -hex 32

   Leave STORAGE_KIND=local unless you want cloud blobs.

3. Start the stack:

   docker compose up -d
   docker compose logs -f syncbins

4. Open your URL and complete onboarding — same wizard as hosted syncbins.com. The first device to finish setup becomes the bootstrap device (generates the recovery phrase and master key).

   Bootstrap immediately

   Until bootstrap completes, anyone who can reach the URL could claim the server. Run onboarding yourself right after first startup.

5. Verify health:

   • curl -s https://box.yourdomain.com/api/health → {"ok":true,"version":"0.0.0"}
   • Settings → Server: green status, latency shown
   • ./data/syncbins.db and ./data/blobs/ exist on the host

Compose files live in App/docker/ (docker-compose.yml, Caddyfile, .env.example). See the App docker README for bind-mount layout.

What you don’t need to configure

For a standard single-user self-hosted box:

Topic	Default	Action
Storage	Local disk (./data/blobs)	Nothing — works out of the box
Tenancy	Single tenant	Keep TENANT_MODE=single
Stripe / billing	Off	Ignore Stripe env vars
R2 / Azure	Off	Only if you opt into cloud blobs

You are not expected to paste a wall of env vars into a Settings screen. Production needs domain + secret; cloud storage is an optional appendix.

Optional: cloud blob storage

If local disk isn’t enough, set STORAGE_KIND=r2 or STORAGE_KIND=azure and the credentials from Choosing storage. Restart the container. No UI change required.

What’s next

Raspberry Pi Pi 4/5 with 64-bit OS — arm64 images, no special tag.

Choosing storage Local vs R2 vs Azure — when to upgrade.

Configuration reference Every env var, every default.

TLS & domains Caddy, certificates, wildcards.

Backups & restore Snapshot SQLite + blobs.