Syncthing on AWS User Guide

Overview

This image runs Syncthing, the open source, continuous file synchronization program - it synchronizes files between two or more devices peer-to-peer over an encrypted, authenticated connection, with no central server. A privacy-respecting alternative to hosted file sync, run here as an always-on sync node you control.

The Syncthing GUI and REST API are served by a single Go binary behind nginx as a reverse proxy. The sync protocol listens on port 22000. The GUI listens on 127.0.0.1:8384 and is reached through nginx on port 80 (and 443 once you add TLS).

On the first boot of every deployed instance, a one-shot service regenerates the device certificate (a fresh Device ID), the API key and the administrator GUI password - all unique to that instance. The login and API key are written to /root/syncthing-credentials.txt with mode 0600.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network, inbound ports 80 and 443 from the networks you reach the GUI on, and inbound TCP 22000 from the devices you want to sync with
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Syncthing. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network, ports 80 and 443 from the networks you use, and TCP 22000 for the sync protocol. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes under a minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Syncthing Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, 443, and 22000 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=syncthing-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve the Login

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

The first boot service runs before the SSH daemon becomes ready, so the credentials file is always in place when you log in for the first time.

ssh <login-user>@<public-ip>
sudo cat /root/syncthing-credentials.txt

You will see a plain text file containing the GUI URL, the username (admin), the password, the API key and this node's Device ID. From the same SSH session you can confirm the deployment is healthy - the health endpoint is open:

curl -fsS http://127.0.0.1/rest/noauth/health

{"status":"OK"}

A "status":"OK" response confirms the full stack - nginx and the Syncthing server - is serving.

Step 4: First Sign-in

Open a web browser and navigate to http://<public-ip>/. Syncthing presents an Authentication Required page. Enter the username admin and the password from /root/syncthing-credentials.txt, then select Log In.

The Syncthing GUI sign-in, protected by a per-instance administrator password.

Step 5: The Dashboard

After signing in you see the dashboard: This Device (transfer rates, listeners, discovery, uptime, the version and this node's Device ID), your Folders on the left, and Remote Devices on the right.

The Syncthing dashboard - this device, folders, remote devices and transfer rates.

Step 6: Add a Folder and Pair a Device

Syncthing syncs a folder between devices that have added each other by Device ID. To sync this node with your laptop or another server:

1. Select Add Folder, give it a label and a path (for example a directory on the /var/lib/syncthing volume), and save.
2. On your other machine, install Syncthing and copy its Device ID.
3. Here, select Add Remote Device, paste that Device ID, and share the folder with it. Accept the reciprocal request on the other machine.

Pair another device by its Device ID to start syncing folders.

Syncthing then keeps the folder in sync automatically, in both directions, over an encrypted connection.

Step 7: The REST API

Every action is available through the REST API, authenticated with the API key from the credentials file:

curl -fsS -H "X-API-Key: <api-key>" http://<public-ip>/rest/system/status

The interactive API and configuration are documented at https://docs.syncthing.net/dev/rest.html.

Step 8: Enable HTTPS with Let's Encrypt

For any production deployment serve the GUI over HTTPS so the login and API key cannot be intercepted. The image ships with nginx, which certbot can configure automatically.

The following assumes you have a DNS record pointing your fully qualified domain name at the instance's public IP address.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d sync.your-domain.example \
  --non-interactive --agree-tos -m you@your-domain.example \
  --redirect

Step 9: Backups and Maintenance

Syncthing keeps its configuration, device certificate, index database and the synced folders under /var/lib/syncthing. Back it up regularly:

sudo systemctl stop syncthing
sudo tar czf <backup-dir>/syncthing-data-$(date +%F).tgz -C /var/lib/syncthing .
sudo systemctl start syncthing

Ship the archive to an Amazon S3 bucket or another object store. Because the data directory is on its own EBS volume, you can also take coordinated EBS snapshots. Keep the device certificate (cert.pem/key.pem) - it is this node's identity; restoring it preserves the Device ID your peers trust. To upgrade Syncthing, replace /usr/local/bin/syncthing with a newer release and restart. See https://docs.syncthing.net/.

Step 10: Scaling and Operations

• Attach a larger or additional EBS volume for /var/lib/syncthing as your synced data grows
• Use the REST API to automate folder and device management
• Restrict the GUI to your network and expose only port 22000 publicly for the sync protocol

Each of these is documented in the official Syncthing documentation at https://docs.syncthing.net/.

Support

cloudimg provides 24/7/365 expert technical support for this image. Guaranteed response within 24 hours, one hour average for critical issues. Contact support@cloudimg.co.uk.

For general Syncthing questions consult the documentation at https://docs.syncthing.net/. Syncthing is a trademark of its respective owner; use here is nominative and does not imply affiliation or endorsement.