Deploy a server

This page installs Courier on a server that is ready: a Linux machine with 80 and 8443 open and an address clients can reach.

Deploy Courier

Two ways to do the same job. The desktop app drives it over SSH and needs nothing installed on the server; the command line runs the same steps by hand. Pick one — they end at the same address.

Desktop app

1. Open Courier and go to Connect to server, then fill in four fields:
   • Server name: any label, e.g. vps-fra1
   • Server address: the server’s public IP, or a domain that points at it
   • SSH user: root, the default user on most cloud servers
   • Server password: the server’s login password, not the vault password
2. Click Sign in to server.
3. Once connected, open Service status on the left and click Deploy service.
4. In the dialog, two fields:
   • Port: the port you opened (8443). Port 80 stays free for the certificate check.
   • Server program: keep the default, Download from the official address.
5. Click Start deploy. It runs four steps: prepare the server → install Courier → configure HTTPS → start and check.
6. Wait until it shows Running. The first deployment takes one to three minutes; do not close the window.

Command line

Sign in to the server first — every command below runs on it, not on your computer:

ssh root@YOUR_IP

1. Put the program in place

mkdir -p ~/courier && cd ~/courier
BASE=https://cnb.cool/ah-yu/courier/-/releases/download/latest
curl -fL -O "$BASE/courier-server-linux-x64"
mv courier-server-linux-x64 courier
chmod +x courier

2. Let it answer on port 80, then create its database

sudo setcap cap_net_bind_service=+ep ~/courier/courier
cd ~/courier && ./courier migrate

The first line is the only privileged thing on the whole server: it lets this one file listen on port 80 for the certificate check. Replacing the file later means running it again. If the machine has no setcap, install it with sudo apt install -y libcap2-bin.

3. Run it as a service

Write this to ~/.config/systemd/user/courier.service, with your own address and port in it:

[Unit]
Description=Courier Sync Server
After=network.target

[Service]
Type=simple
WorkingDirectory=%h/courier
Environment=PORT=8443
Environment=TLS_NAME=YOUR_IP
ExecStart=%h/courier/courier start --port 8443
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

• TLS_NAME — the address clients will use: the public IP, or the domain pointing at it. It must be the same string every device will be told.
• PORT and --port — the free high port you opened (8443 here).

Then start it, and let it keep running after you close the SSH window:

mkdir -p ~/.config/systemd/user
systemctl --user daemon-reload
systemctl --user enable --now courier
sudo loginctl enable-linger $USER

4. Watch it come up

journalctl --user -u courier -f

Within a minute it prints Server running at https://YOUR_IP:8443. The certificate arrives a few seconds to a minute after that; until it does, HTTPS requests are refused, and that is normal.

5. Create the keys

The host key (ak_...) is the administrator credential. It is created on the server and printed once:

cd ~/courier && ./courier apikey create admin

Write the ak_ key down — the command-line path on the next page uses it again to create a user key.

With it, create one user key (ck_...) per person. This one is the key that goes into Obsidian:

curl -sS -X POST https://YOUR_IP:8443/api/users \
  -H "Authorization: Bearer ak_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice"}'

The answer carries the full key in "key". Copy it — it is shown here only.

Updating later

Download the new build over the old file, grant it the capability again (the grant belongs to the file), and restart:

cd ~/courier
BASE=https://cnb.cool/ah-yu/courier/-/releases/download/latest
curl -fL -O "$BASE/courier-server-linux-x64"
mv -f courier-server-linux-x64 courier
chmod +x courier && sudo setcap cap_net_bind_service=+ep ~/courier/courier
./courier migrate && systemctl --user restart courier

Next chapter: Connect Obsidian.