Skip to content
Klutch.sh Docs

Deploying a Syncthing App

Introduction

Syncthing is an open-source, peer-to-peer file synchronization service with a web admin UI and TCP listeners for node connections. Deploying Syncthing with Dockerfiles on Klutch.sh provides reproducible builds, managed secrets, and persistent storage—all configured from klutch.sh/app. Because Klutch.sh supports one port per app, this guide uses two apps: one for the TCP sync listener and one for the HTTP admin UI.

Prerequisites

  • Klutch.sh account (sign up)
  • Two GitHub repos or branches (or one repo reused twice) with the Syncthing Dockerfile
  • Optional: reverse proxy config if you want custom domains for both endpoints

Architecture and ports

  • Sync listener: TCP traffic on internal port 22000 (default Syncthing sync). External peers connect to example-sync.klutch.sh:8000 mapped to internal 22000.
  • Admin UI: HTTP traffic on internal port 8384 (web GUI). External admins access https://example-admin.klutch.sh.
  • Discovery (UDP) is not available; rely on direct addresses or global discovery via HTTPS if allowed by your config.

Repository layout

syncthing/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Build and run locally:

Terminal window
docker build -t syncthing-local .
docker run -p 22000:22000 -p 8384:8384 \
  -v $(pwd)/config:/var/syncthing/config \
  -v $(pwd)/data:/var/syncthing/data \
  syncthing-local

Open the admin UI at http://localhost:8384 to pair devices.

Dockerfile for Syncthing (production-ready)

Place this at the repo root; Klutch.sh auto-detects Dockerfiles.

FROM syncthing/syncthing:latest


ENV STGUIADDRESS=0.0.0.0:8384
ENV STNODEFAULTFOLDER=1


EXPOSE 22000 8384
CMD ["/bin/syncthing", "-home", "/var/syncthing/config", "-gui-address", "0.0.0.0:8384"]

Notes:

  • Pin to a specific tag (e.g., syncthing/syncthing:1.27.5) for stability.
  • STNODEFAULTFOLDER=1 prevents auto-creating the default share; add folders manually in the UI.

Environment variables (Klutch.sh)

Shared:

  • STGUIADDRESS=0.0.0.0:8384
  • STNODEFAULTFOLDER=1

If deploying without the Dockerfile and relying on Nixpacks:

  • NIXPACKS_START_CMD=/bin/syncthing -home /var/syncthing/config -gui-address 0.0.0.0:8384

Attach persistent volumes

Add storage in Klutch.sh (path and size only):

  • /var/syncthing/config — device keys, settings.
  • /var/syncthing/data — synced files (required if you want persistence).

Ensure paths are writable inside the container.

Deploy Syncthing on Klutch.sh (split-port workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Create the sync app: choose TCP traffic, set the internal port to 22000, set env vars above, and attach volumes at /var/syncthing/config and /var/syncthing/data.
  3. Deploy the sync app. Peers connect to example-sync.klutch.sh on external port 8000 (Klutch TCP) mapped to internal 22000.
  4. Create the admin app: choose HTTP traffic, set the internal port to 8384, reuse the same env vars and volumes.
  5. Deploy the admin app. Access the UI at https://example-admin.klutch.sh to add devices and folders.

Sample checks

Admin UI reachability:

Terminal window
curl -I https://example-admin.klutch.sh

Sync port check (TCP):

Terminal window
nc -vz example-sync.klutch.sh 8000

Health checks and production tips

  • Use a TCP readiness probe for the sync app (port 22000) and an HTTP probe to / for the admin app.
  • Keep device keys in the config volume; back it up regularly along with /var/syncthing/data if needed.
  • Pin image versions and test upgrades in staging before production.
  • If you disable global discovery, configure static device addresses pointing to your sync endpoint.

Syncthing on Klutch.sh uses two apps to align with single-port routing: one for TCP sync and one for the HTTP admin. Configure ports, env vars, and volumes, then pair devices through the admin UI and start syncing files.