Getting started¶
This page takes you from nothing to a first folder synced between a server and one device, in the shortest way that is still safe to keep. For a server reachable from the internet, read Installation afterwards; it adds TLS, backups and updates.
You need
- a server that is on all the time: Linux with Docker or Podman (a NAS, a mini PC, a VPS);
- one or more devices to sync: Linux, Windows or macOS;
- the devices must be able to reach the server on two ports: the web port (8080, or 443 behind a proxy) and the hub's sync port (22001).
1. Start the Zentrale¶
On the server, create compose.yaml in a new directory. Replace nas.local with the name or IP address under which
your devices reach the server:
services:
stellwerk:
image: tristanteu/stellwerk
restart: unless-stopped
ports:
- "8080:8080" # web UI and agents
- "22001:22001" # sync port of the hub
environment:
STELLWERK_HUB_ADDRESS: tcp://nas.local:22001
volumes:
- stellwerk:/data
volumes:
stellwerk:
Open http://nas.local:8080 and log in with that password. The overview is empty: no devices,
no folders yet.
Warning
Port 8080 without TLS is fine for a first try in your own network. Before you open it to the internet, put a reverse proxy with HTTPS in front of it: the password and the devices' sign-in go over this port. See Reverse proxy.
2. Create a folder¶
New folder, give it a name such as Documents. The server now holds an empty folder with
versions; no device has it yet. Once a device is paired, New folder can also pick an existing
folder on it right away (see Picking a folder on a
device).
3. Pair a device¶
In the UI click Pair device, pick the device's operating system and copy the command. It looks like this, with a one-time code valid for 15 minutes:
curl -fsSL https://github.com/Speicherstadt/stellwerk/releases/download/vX.Y.Z/install.sh | sh -s -- http://nas.local:8080 K7Q2-MX9P-41TZ
Run it in a terminal on the device, as your normal user (no sudo, no administrator); on
Windows the dialog shows a command for PowerShell. It
downloads the agent of the Zentrale's version, runs stellwerk-agent join, which stores the
server and a new key for the device, and stellwerk-agent service install, which starts the
agent now and on every login. With an agent you built yourself, run those two directly:
stellwerk-agent join --server http://nas.local:8080 K7Q2-MX9P-41TZ && stellwerk-agent service install.
On the first start the agent downloads its own Syncthing (about 15 MB), which takes a moment.
The dialog in the UI notices the new device by itself and asks which folders it should get. Tick Documents and click Set up device.
Pairing in the LAN without a code
In the same network you can skip the code: run the command without the code at the end. The
agent prints a fingerprint such as 3F2A-91BC-04DE-77A1, and the device appears under
Devices → Waiting devices; approve it there if the fingerprint matches.
4. Watch it sync¶
Back in the Overview, the row Documents has a cell for the new device in mode Both.
The folder is at ~/Stellwerk/Documents on the device (%USERPROFILE%\Stellwerk\Documents on
Windows). Put a file into it: within seconds the activity feed says that the device changed a
file in Documents, and the file is on the server too.
Pair a second device the same way and give it the folder as well: files now flow device → server → device, even if the two devices are never on at the same time.
Next steps¶
- Change a folder's path or mode per device: open the folder, tab Devices (user guide).
- Keep build output and caches out of a folder with ignore patterns (user guide).
- Make the server reachable from outside with TLS and set up backups (installation).