// Termax Self-Host · Guide

Set up the Termax Sync Server in 10 minutes.

Step by step: Docker, a domain with HTTPS, the licence, first accounts. After that the server keeps running by itself, renews its certificates and its licence.

Linux server, NAS or Raspberry Pi 4/5 · 64-bit · Docker with Compose


// Before you start

What you need

A machine with Docker and Docker Compose, 64-bit (x86 or ARM), with about 256 MB of free memory. On Debian/Ubuntu install Docker with curl -fsSL https://get.docker.com | sh.

A domain or subdomain, e.g. sync.example.com, whose DNS record (A or AAAA) points to this machine, and open ports 80 and 443. The apps only connect over HTTPS; Caddy gets the certificate automatically.

A licence. In Termax under Account → Own server: get Self-Host Personal (up to 3 accounts) for free or buy Self-Host Team. It is always available there with "Copy licence"; a bought one also arrives by e-mail.


// Step 1

Get the files

In an empty folder on the server:

mkdir termax-sync && cd termax-sync
curl -fsSLO https://termax.app/self-host/dateien/docker-compose.yml
curl -fsSLO https://termax.app/self-host/dateien/Caddyfile
curl -fsSL -o .env https://termax.app/self-host/dateien/env.example

These are the compose file (Termax Sync Server with Caddy in front), the Caddy configuration and the settings.


// Step 2

Fill in the settings

Open .env in an editor (e.g. nano .env) and fill in at least these four lines:

TERMAX_DOMAIN=sync.example.com
TERMAX_PUBLIC_URL=https://sync.example.com
TERMAX_LICENSE=TMXL1.eyJ2Ijox...   (the whole line from the app)
TERMAX_SIGNUP_ALLOW=@example.com

TERMAX_SIGNUP_ALLOW decides who may create an account on your server: single addresses (anna@example.com,ben@example.com) and/or whole domains (@example.com). Empty means nobody. The server never accepts more accounts than the licence allows.

Without e-mail the server confirms new accounts by itself, and "Forgot password" is off. With the SMTP lines in .env it sends confirmation codes, password resets and team invitations.


// Step 3

Start and check

docker compose up -d
docker compose logs -f termax-sync

The logs show Lizenz erkannt (licence recognised) and then PocketBase with "Server started". Then open https://your-domain/api/termax/server-info in a browser: it must say "licensed":true.

Without a valid licence the server does not start at all; it waits and says why in the logs. It picks up a new licence in .env after docker compose up -d.


// Step 4

Connect the apps

In Termax 0.9.3 or later (Windows, Linux, macOS, Android and iPhone): Sign in → at the top "Change server" → https://your-domain → Connect. The app checks the licence and shows it. Then Create account with an address from the allow list.

If you are signed in to a Termax account, sign out first; your connections stay on the device and are uploaded to your server with the first sync.

Keep the recovery key the app shows at sign-up: without e-mail there is no "Forgot password", and the operator cannot decrypt a vault either.


// Operation

Updates, backups, administration

Updates: docker compose pull && docker compose up -d. Before the first start of a new version the server backs up its database to backups/ in the data folder (the last five).

Backups, the easy way: in the admin interface (see below) under Settings → Backups. PocketBase makes complete backups there while running, also on a schedule (e.g. daily) and optionally to S3 storage, and restores one with Restore. Download the backups from there or let them go to S3: a backup that sits only on the same machine does not help when its disk fails.

Backup as a file from the command line (server briefly stopped, only then is it complete):

docker compose stop termax-sync
docker compose run --rm --no-deps -T --entrypoint sh termax-sync -c 'cd /pb_data && tar czf - .' > termax-backup-$(date +%F).tgz
docker compose start termax-sync

The vaults inside are end-to-end encrypted, but the backup contains accounts and e-mail addresses, so keep it safe.


// Administration

Accounts, seats, moving

Admin interface (optional): create a PocketBase admin like this; the interface is then at https://your-domain/_/. It lists all accounts (collection users) and lets you delete them. Admins see contents only encrypted. Create the admin right after the first start: until then the log contains a link with which anyone who can read the logs can become admin. The interface is reachable from the internet through your domain; use a long, unique password, or allow it only from your own network (a ready block, commented out, is in the Caddyfile).

docker compose exec termax-sync pocketbase superuser upsert admin@company.com 'a-long-password' --dir /pb_data

Adding someone: add the address (or the whole domain) to TERMAX_SIGNUP_ALLOW, run docker compose up -d, and the person creates their account in the app. For shared folders a team admin then invites them in the app under Team.

Removing someone: remove them from all teams in the app under Team (the app then re-encrypts the team folders), delete the account in the admin interface and take the address out of TERMAX_SIGNUP_ALLOW. The seat is free immediately.

Forgotten password: with SMTP, people reset it themselves in the app. Without SMTP there is no reset through the server. If they have lost their recovery key as well, delete the account in the admin interface and let them sign up again: their connections are still on their devices and are uploaded at the first sync; teams have to invite them again. An admin cannot set a password, because the vault is encrypted with it.

Changing seats (Team): change the quantity in the customer portal under Account → Own server. Your server fetches the new licence within six hours, immediately after docker compose restart termax-sync. With TERMAX_RENEW=0, copy the licence from the app into .env again.

Licence, seats, monitoring: https://your-domain/api/termax/server-info shows whether the licence is valid, the tier, seats, accounts in use and expiry. The address also works as a health check for Uptime Kuma or similar (status 200 and "licensed":true).

New versions: are listed in the release notes. The tag 1 in the compose file gets all compatible updates; docker compose pull fetches them.

Moving from the Termax cloud: the app takes your own connections, folders and snippets along. Team folders from the Termax cloud stay behind: create the team again on your server and move the entries there while you still have them on a device.

Restoring a backup: in the admin interface under Settings → Backups → Restore, or a file from the command line (replaces all data on the server):

docker compose stop termax-sync
docker compose run --rm --no-deps -T --entrypoint sh termax-sync -c 'cd /pb_data && find . -mindepth 1 -delete && tar xzf -' < termax-backup-DATE.tgz
docker compose start termax-sync

Moving to another machine: make a backup; on the new machine do steps 1 and 2 with the same .env, run docker compose up -d once and then stop termax-sync, restore the backup, switch the DNS record. The licence belongs to the subscription, not to a machine.

New domain: change TERMAX_DOMAIN and TERMAX_PUBLIC_URL, run docker compose up -d. In every app sign out, "Change server", enter the new address, sign in with the same account.


// Already running a reverse proxy?

Nginx Proxy Manager, Traefik, Synology, Unraid

If a reverse proxy already holds ports 80 and 443 on your machine, leave out the Caddy service and publish only the Termax port. In docker-compose.yml: delete the whole caddy: block (and caddy-data, caddy-config at the bottom), you then don't need the Caddyfile, and for termax-sync use instead of expose:

    ports:
      - "127.0.0.1:8090:8090"   # proxy on the same machine
      # - "192.168.1.10:8090:8090"  # proxy on another machine: this machine's LAN address

In the proxy, add a host for your domain pointing to http://127.0.0.1:8090 (or the LAN address), with a Let's Encrypt certificate. Important: the proxy must pass the client address in the X-Forwarded-For header (Nginx Proxy Manager, Traefik and Synology do this by default) and allow requests up to 32 MB (Nginx: client_max_body_size 32m; under "Advanced"). Never publish the port on 0.0.0.0 to the internet: anyone could then bypass the rate limits with a forged header.

Without Caddy, TERMAX_DOMAIN is not needed, TERMAX_PUBLIC_URL is.


// Without a public address

Only on your own network or over Tailscale

The apps need a valid HTTPS certificate, also on your own network (Android allows nothing else). The easiest way is Tailscale: on the server run tailscale serve --bg 8090 instead of Caddy, and in the app use https://name.tailnet-name.ts.net. In docker-compose.yml publish the port of termax-sync (ports: ["127.0.0.1:8090:8090"]) and drop the Caddy service.

Without internet access set TERMAX_RENEW=0 and paste the licence again by hand after every renewal (once a year).


// Help

When something does not work

"The server cannot be reached": check the DNS record, ports 80/443 and docker compose logs caddy (it says whether the certificate was obtained).

"This server has no valid Termax licence": docker compose logs termax-sync names the reason; usually part of the licence line is missing.

"Registrierung … nicht freigegeben" (sign-up not allowed): add the address or domain to TERMAX_SIGNUP_ALLOW and run docker compose up -d.

"Server read-only": the licence has expired. Check the subscription in the customer portal; once it runs, the server fetches the new licence within six hours (or right away after docker compose restart termax-sync).

Still stuck? Support is by e-mail at support@termax.app. We do not offer assisted setup or access to your server.