Skip to main content

Syncthing

Syncthing is a peer-to-peer continuous file synchroniser. In this homelab it's the engine that keeps the Maresa Synology hot-storage tier in step with the primary datasets — media, reading, audio, gaming, images, an "archive" pool, and a misc "stash". Whenever a file lands on any one peer, every other peer with that folder converges on the same state.

Why Syncthing (and not rsync / Restic / a cron job)​

The hot tier is continuous by design — see Topics → Three-tier backups. The other two tiers (Restic to Hetzner S3, encrypted cold drives) are scheduled snapshots; the hot tier exists specifically to cover what changed in the last few minutes with minimal RPO.

  • No RPO planning. Files land within seconds, not on a schedule. The "last 5 minutes" of work is on the NAS within a minute or two.
  • Bidirectional. A correction made on the Synology propagates back to the source. Useful for the "archive" pool where occasional NAS-side curation happens.
  • Versioning per folder. The "Staggered" file-versioning policy gives an hour-by-hour, then daily, then weekly history of each file — so a delete doesn't immediately destroy the previous state.
  • No central server. Each peer holds its own credentials; if one box dies the rest keep syncing.

Restic, rsync, and rclone are all viable alternatives for the cold and warm tiers respectively; Syncthing's continuous bidirectional model is the differentiator for the hot tier.

Why on Maresa​

Because Maresa is the hot tier — the Synology DS723+ behind the off-site uplink. Running the Syncthing daemon on the same box that owns the disks avoids one hop and means replication keeps working even if every other system in the homelab is down.

The mirror copy of Syncthing inside the cluster (against k8s/apps/syncthing/talos if it ever exists) would be redundant for the hot-tier purpose — the cluster's persistent state is already covered by k8up snapshots.

Operational notes​

  • The Syncthing peer is not publicly exposed. It's reachable on the home LAN and over the NetBird mesh via the agent on Maresa.
  • The local Traefik fronts the admin UI at syncthing.maresa.int.kueber.eu for in-browser administration on the home LAN.
  • The mounted volumes on /volume1/backup/{archive,audio,gaming,images,reading,stash,videos} are the canonical hot copies. The Restic snapshots that feed Hetzner S3 are taken from upstream peers, not from these directories.
  • A new dataset → add a Syncthing folder on every peer, set "Send & Receive" on the source and "Receive Only" on Maresa, point at /volume1/backup/<dataset>.

Cluster Deployment​

Syncthing — Maresa Docker host

Layout​

  • Image pinned by tag and digest, bumped by Renovate.
  • Joined to the shared web Docker network so the admin UI is reachable behind Traefik.
  • Admin UI fronted by Traefik at syncthing.maresa.int.kueber.eu (TLS via acmedns, backend https://syncthing:8384).
  • File-transfer ports published on the host:
    • 22000/tcp and 22000/udp for TCP + QUIC transfers.
    • 21027/udp for local-discovery broadcasts.
  • PUID=1026 / PGID=100 — the Synology user that owns /volume1/backup.
  • Mounted volumes:
    • /volume1/docker/syncthing-config → /var/syncthing/config
    • /volume1/backup/{archive,audio,gaming,images,reading,stash,videos} → matching paths in-container.

Deviations from defaults​

  • HTTPS Traefik backend (server.scheme=https). Syncthing's admin UI auto-redirects HTTP→HTTPS on the same port; sending Traefik at the HTTPS listener avoids the redirect loop.
Compose Metadata
  • Image: syncthing/syncthing:2.1.6@sha256:4d0281bdcb4ed9baf503d251d0544ddd856f49fce3f114056257ae172b7fb670