File Storage guide
Syncthing Docker Compose: Keep Device Identity and Files Recoverable
Run Syncthing in Docker with persistent device identity, deliberate folder directions, private administration, and an isolated restore drill.
Published and reviewed by OpenAlt · October 4, 2026
Run Syncthing in Docker when you want a persistent synchronization endpoint on a server you already maintain. Save its identity and configuration outside the container, choose folder direction before copying valuable files, and test recovery before treating a second device as protection.
Our recommendation is simple: make the first deployment boring. Pair two devices, share one disposable folder, and prove what happens after an edit, a deletion, and a restart. Importing your entire document archive before those checks creates a much harder problem to untangle.
Table of contents
- Is Docker the right operating model?
- What must survive container replacement?
- How should networking and administration work?
- Which folder direction should you choose?
- How do you verify a working setup?
- How do you back up and restore safely?
- What should you troubleshoot first?
- FAQ
Is Docker the right operating model?
Docker fits an always-on Linux server whose operator already handles updates, storage and remote access. A desktop installation may be simpler when only two personal computers need to exchange files. Neither arrangement supplies a help desk or an independent backup by itself.
Syncthing authenticates peers using device identities and encrypts device traffic. The security documentation explains that knowing a device ID does not authorize a new peer; accepted-device configuration still matters. Protect the configuration as carefully as the synchronized files because its private keys represent that identity.
Before installation, write down who owns these jobs:
| Responsibility | A useful acceptance check |
|---|---|
| Storage | The operator can explain every host-to-container mount |
| Updates | A previous working image and recovery copy are available |
| Device removal | A lost laptop can be removed from remaining peers |
| Recovery | A deleted document can be recovered independently of sync |
Use the OpenAlt Syncthing profile to check the product fit first. If you actually need browser-based document collaboration and shared accounts, consider the different operating model described in our Nextcloud guide.
What must survive container replacement?
Persist the Syncthing working directory before pairing devices. The official Docker instructions use /var/syncthing and default to UID and GID 1000. Replacing a container should replace the executable environment, not your server's identity or synchronized archive.
For a new Linux test deployment, create a dedicated working directory, then save this as compose.yaml:
services:
syncthing:
image: syncthing/syncthing:latest
hostname: sync-node
network_mode: host
environment:
PUID: "1000"
PGID: "1000"
STGUIADDRESS: "127.0.0.1:8384"
volumes:
- ./state:/var/syncthing
restart: unless-stopped
Run mkdir -p state, then check the intended account with id. Adjust the two numeric IDs to match an account allowed to write this new directory. Do not recursively change ownership across an existing shared archive to silence a permissions error.
The floating image tag is convenient for the initial trial. Before routine use, record the resolved image digest and pin the version you have validated. Keep the Compose file alongside a private record of the selected version. Configuration backup and a reproducible image choice solve different recovery problems.
How should networking and administration work?
On Linux, host networking avoids common local-discovery problems, while a loopback-only GUI keeps administration off the LAN. The official container guide recommends host networking because a bridge can advertise container addresses that other devices cannot reach.
Start the service with docker compose up -d and inspect docker compose logs --tail=100. On the server itself, open http://127.0.0.1:8384. From another computer, use your existing SSH access to forward local port 8384 to the server's loopback port. This does not require publishing the management interface.
The security guide identifies 22000 as the default synchronization port. Sync traffic and the administrative GUI serve different purposes; making the latter public does not fix peer connectivity. Set a GUI password even for a private deployment, and use authenticated TLS if you later expose that interface beyond loopback.
This example targets Linux. Docker Desktop networking behaves differently, so verify platform support rather than assuming host mode reproduces a Linux server. If bridge networking is required, configure reachable peer addresses deliberately and test the actual connection type.
Which folder direction should you choose?
Choose the folder mode according to who is allowed to change the authoritative copy. Two-way editing and a one-way distribution workflow should not share the same accidental defaults.
The folder-type documentation distinguishes send-and-receive, send-only and receive-only behavior. A send-only publishing device can distribute a reference collection; a receive-only endpoint can retain incoming changes without treating its own edits as updates for everyone else. Read the documented override and revert behavior before pressing those controls.
Start with a directory called sync-trial inside the persistent working area. Pair the second device by checking its identity through a trusted channel, then accept the folder explicitly. Keep the folder ID consistent across peers even when local directory paths differ.
Do not use synchronization as a live database replication mechanism. An application may update several files as one logical operation, while file synchronization sees separate changes. Use the application's backup or replication method for active databases, mail stores and similarly coordinated state.
How do you verify a working setup?
Verify data behavior, not merely a green device indicator. A connection can succeed while a mount points to the wrong directory or changes are blocked by ownership.
Use a small acceptance sequence:
- Create a disposable text file on the first device and confirm its contents on the second.
- Edit it remotely and check that the chosen folder mode behaves as intended.
- Delete another disposable file and observe the destination behavior.
- Restart the container, then confirm the same device identity and folder configuration remain.
- Disconnect one peer, make a controlled edit, and check convergence after reconnecting.
Enable versioning on a receiving device before testing recovery. Syncthing versioning is disabled by default and preserves older copies for changes received from peers; it does not archive every edit made locally. That distinction is why a successful two-device test still does not establish a complete backup strategy.
How do you back up and restore safely?
Back up configuration, identity material and the files you care about to storage outside the active synchronization set. Keep a recovery copy that an accidental synchronized deletion cannot immediately remove.
Estimate originals, retained versions and independent copies with our backup storage calculator. Use your measured archive size and retention policy; do not count two synchronized devices as two independent historical backups.
For a recovery rehearsal, stop the test instance and copy its persistent directory consistently. Restore that copy into an isolated environment with peer connectivity disabled. Confirm the expected identity and directory mappings before permitting any synchronization. Do not run two live devices simultaneously with cloned private identity material.
The security documentation explains why the configuration's private keys matter: access to them can allow device impersonation. Encrypt backup storage where appropriate and restrict who can retrieve it. A restore procedure that exposes those keys creates a new problem while solving the old one.
What should you troubleshoot first?
Check mounts and permissions before changing discovery settings. An empty folder is often a path problem; a connected but out-of-sync device is often a file-access or folder-configuration problem.
Compare the host path, the container path and the path shown in Syncthing. Inspect logs for the first concrete error. If a directory suddenly appears empty after a restart, pause synchronization before experimenting so an unintended state does not spread.
The official container guide separates discovery behavior from GUI security. Follow that separation during diagnosis. Do not solve every failure by exposing more ports or running everything as root.
FAQ
Is Syncthing a backup service?
It synchronizes files. Add independent historical backups and test restoration; synchronized deletions can reach other devices.
Why is my Docker folder empty?
Check the bind mount and Syncthing's configured directory. The host path and the path inside the container are different namespaces.
Can I use bridge networking?
Yes, with deliberate port and peer-address configuration. Linux host networking is often simpler for local discovery.
Will recreating the container change its device ID?
It should retain the identity when the correct persistent state is reused. Missing configuration can produce a new identity that peers do not recognize.