Off-site Backups with TS Pro Backup

The Backup & Restore guide protects you against accidents — a bad import, a fat-fingered delete — by keeping copies of your ./data directory on the same machine. But if that machine itself dies (a disk failure, a deleted droplet, a ransomware event, a provider closing your account), local snapshots die with it. For real disaster recovery you need your backups to live somewhere else entirely.

TS Pro Backup is a small companion server you run off-site — on a different host, ideally a different provider or even a different continent. Your portal connects to it over HTTPS and pushes backup archives to it on a schedule. The backup server stores them, enforces a retention policy, and gives you a clean web console (styled to match TS Pro) to browse and download what's there.

TSP portal  ──HTTPS──▶  TS Pro Backup server  ──▶  ./data/storage/
(your site)             (off-site companion)        (encrypted archives)

The headline feature is end-to-end encryption. Every TS Pro Backup site gets its own keypair. Your portal encrypts each archive to that site's public key before it leaves your server, and only the matching private key — which you hold, and the backup server never sees — can decrypt it. The backup server stores nothing but ciphertext. Even if it is fully compromised, your backups stay private.

This guide has four parts:

1. Stand up the backup server on an off-site host with Docker Compose.
2. Put HTTPS in front of it with a reverse proxy.
3. Create a site and copy its keys in the backup server's console.
4. Connect Trusted Servants Pro so it backs up to the server automatically.

Before you begin

You'll need:

• A second host to run the backup server on — separate from the machine running your portal. The whole value of off-site backup is that this box can survive your portal's machine dying, so put it somewhere independent: a small VPS on a different provider, a home server, a NAS that runs Docker, etc.
• Docker and Docker Compose installed on that host.
• A domain name you can point at the backup server (e.g. backup.example.org) so the portal can reach it over HTTPS.
• A little bit of disk space on the backup host — enough to hold as many archives as your retention policy keeps. A full portal bundle is the size of your database plus all uploads, so size the volume accordingly.

Part 1: Stand up the backup server

TS Pro Backup ships as a published image on Docker Hub — viibeware/tspro-backup. You don't have to clone anything to run it; a docker-compose.yml and a .env are all you need.

1.1 — Create a working directory

On the backup host:

mkdir tspro-backup && cd tspro-backup

Everything for the server lives here: the compose file, your .env, and a ./data folder the container creates for its database and stored archives.

1.2 — Create docker-compose.yml

Create a file named docker-compose.yml with the following contents. It pulls the published image — no source checkout required:

services:
  tspro-backup:
    image: viibeware/tspro-backup:latest
    container_name: tspro-backup
    ports:
      # The container always listens on 8000 inside; this publishes it on
      # 8095 of the host. In production a TLS reverse proxy (Part 2) sits in
      # front and the portal points at the https:// URL.
      - "${TSPB_PORT:-8095}:8000"
    volumes:
      - ./data:/data            # tspro_backup.db + storage/ + auto-generated keys
    environment:
      # Signs console sessions. REQUIRED — set a long random value in .env.
      - TSPB_SECRET_KEY=${TSPB_SECRET_KEY:?TSPB_SECRET_KEY must be set in .env}
      # First-boot console admin (ignored once the admin row exists).
      - TSPB_ADMIN_USERNAME=${TSPB_ADMIN_USERNAME:-admin}
      - TSPB_ADMIN_PASSWORD=${TSPB_ADMIN_PASSWORD:-admin}
      # Optional at-rest encryption passphrase for the storage volume.
      - TSPB_REST_PASSPHRASE=${TSPB_REST_PASSPHRASE:-}
      # Max single upload in MiB — whole-site bundles can be large.
      - TSPB_MAX_UPLOAD_MB=${TSPB_MAX_UPLOAD_MB:-8192}
      # Set to 1 ONLY for local HTTP testing without TLS.
      - TSPB_DEBUG=${TSPB_DEBUG:-0}
    restart: unless-stopped

A few things worth understanding:

• The container listens on port 8000 inside, published to 8095 on the host. The server serves both its web console and its JSON backup API on this single port.
• The ./data volume holds everything stateful: tspro_backup.db (sites, settings, and backup metadata), storage/site-<id>/ (the stored archive blobs), and any auto-generated keys. Back this folder up the same way you'd back up any data directory.
• restart: unless-stopped keeps the server coming back after reboots.

1.3 — Create the .env file

The one value you must set is TSPB_SECRET_KEY. It signs the console login session. Generate a strong, random value:

python -c "import secrets; print(secrets.token_urlsafe(48))"

Then create a file named .env next to your compose file:

# Signs console sessions. REQUIRED — paste the output of the command above.
TSPB_SECRET_KEY=replace-with-a-long-random-value

# First-boot console admin. Used only to create the initial admin account;
# change the password from the console afterwards (these are then ignored).
TSPB_ADMIN_USERNAME=admin
TSPB_ADMIN_PASSWORD=change-me-on-first-login

# Host port to expose the console on (container always listens on 8000).
TSPB_PORT=8095

# Optional: at-rest encryption passphrase for the storage volume. Leave blank
# to let the server generate a random key in ./data/rest.key. See the note
# below before you rely on this.
TSPB_REST_PASSPHRASE=

# Max single upload in MiB. Whole-site bundles can be large.
TSPB_MAX_UPLOAD_MB=8192

# Set to 1 ONLY for local plain-HTTP testing.
TSPB_DEBUG=0

1.4 — Start the server

docker compose up -d

The first boot creates the seed admin and initializes the database in ./data. Confirm it's running:

docker compose ps
docker compose logs -f      # Ctrl-C to stop following

The console is now reachable on port 8095 of the host. From a browser on the same network, open http://<backup-host>:8095 — you should see the TS Pro Backup login page. Sign in with the TSPB_ADMIN_USERNAME / TSPB_ADMIN_PASSWORD you set above.

Part 2: Put HTTPS in front of the server

Your portal authenticates to the backup server with a Bearer API key, and you log into the console with a session cookie. Neither should ever travel over plaintext HTTP. The standard fix is a reverse proxy that terminates TLS and forwards to the server on 127.0.0.1:8095.

Point a DNS record — e.g. backup.example.org — at the backup host first, then pick one of the following.

Option A — Caddy (automatic HTTPS)

Caddy fetches and renews a Let's Encrypt certificate for you with zero extra config. In your Caddyfile:

backup.example.org {
    reverse_proxy 127.0.0.1:8095
}

Reload Caddy and you're done — https://backup.example.org now serves the console with a valid certificate.

Option B — nginx

If you already run nginx (with certificates from Certbot or similar), add a server block for backup.example.org:

location / {
    proxy_pass http://127.0.0.1:8095;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;

    # Whole-site bundles can be large — don't let the proxy truncate uploads.
    client_max_body_size 8192m;
}

Your backup server is now reachable at https://backup.example.org. That HTTPS URL is the basis of what you'll give the portal in Part 4.

Part 3: Create a site in the console

Open the console — https://backup.example.org in production — and sign in. Everything in this part is done in the web interface; there are no JSON or env files to edit.

3.1 — Change the admin password

If you're still on the seeded change-me-on-first-login password, change it now from the console's account settings. The first-boot .env credentials are ignored once the admin row exists, so this is your real login from here on.

3.2 — Review the server settings

On the Settings page you can configure server-wide behavior:

• End-to-end encryption is required by default and there's rarely a reason to change that — it's what makes the storage zero-knowledge.
• Default retention — a grandfather-father-son (GFS) policy: keep the last N daily, weekly, monthly, and yearly archives per site. Retention runs independently per scope, so a burst of frontend-only snapshots never evicts your whole-site backups. Set sensible defaults here; you can tune per-site later.
• Encryption at rest (optional) — streaming AES-256 on the storage volume, using a key the server holds. This is defense-in-depth for the disk and is independent of the end-to-end layer (with E2EE on, the bytes are already opaque to the server). Enable it if you want the volume encrypted even at rest.
• Cloudflare Turnstile (optional) — a bot challenge on the console login page. If you enable it, the server needs outbound HTTPS to challenges.cloudflare.com.

3.3 — Add a site and copy its keys

A site represents one portal pushing backups here. Go to Sites → Add site and give it a name (e.g. your group's name). On creation the console shows you two secrets once:

Copy both now and store them somewhere safe — a password manager is ideal.

The site's public key stays on the server. Your portal fetches it automatically when you wire things up — you don't need to copy it by hand.

Part 4: Connect Trusted Servants Pro

Now switch over to your portal's admin interface. The off-site backup setup lives under Settings → Data, in the Off-site backups card.

Click Set up off-site backup → (or Add another backup if you already have a target). This opens a short five-step wizard.

Step 1 — Choose the backend

Give the target a name (just for you, e.g. "Off-site VPS"), then pick the backend. Choose TS Pro Backup (end-to-end encrypted) — the option described as pushing to a dedicated off-site server that can't read your backups. Continue.

Step 2 — Connection

Two fields, both verified against the keys you copied in Part 3:

Then click Test connection. On success the portal fetches the site's public key and shows its encryption key fingerprint:

🔑 Encryption key fingerprint: … — confirm this matches the backup server's console.

Step 3 — Schedule

Choose how often the portal pushes a backup. Pick a preset — Top of every hour, Every day at 03:00 UTC, Every day at 12:00 UTC, Every Sunday at 03:00 UTC, First of the month — or select Custom cron expression and enter a standard 5-field cron (min · hr · day · mo · dow), interpreted in the site's timezone (set under Settings → Timezone).

Under Retention — keep the last N archives, set how many archives the portal keeps on the remote; older ones are pruned from the remote after each successful upload. (The backup server also applies its own GFS retention from step 3.2 — the two layers stack, and whichever is stricter wins.)

Step 4 — Encryption

For a TS Pro Backup target there's nothing to configure here. The wizard confirms the destination is end-to-end encrypted automatically: every archive is encrypted to the backup server's public key (it shows the fingerprint again) before it leaves your portal, and you'll use the site's private key to decrypt when restoring. Continue.

Step 5 — Review & enable

Review the summary — name, destination, encryption key, schedule, retention. Leave Run a first backup now checked so you can confirm the whole path works immediately, then click Enable target.

The first backup runs synchronously, so you'll see the result right on the page. On success the target appears in the Off-site backups list with an OK status pill and a "last run" timestamp; the scheduler then keeps running on the cron you chose.

Restoring from an off-site backup

When you need to recover, you download the archive from the backup server, decrypt it with the site's private key, and import it into a portal.

1. In the portal, go to Settings → Data → Off-site backups and open the target's Restore view (also reachable from Manage backups). The portal lists the archives available on the server for this site.
2. Select the archive you want. Because the destination is end-to-end encrypted, you'll be asked for the Private key (tspsk_…) — the one you saved in step 3.3. It's used locally to decrypt and is never uploaded.
3. Download selected archive. You get a standard portal export .zip, decrypted.
4. To restore it into a portal, use Settings → Data → Import and select the downloaded .zip. The import replaces the database, uploads/, and the encryption key in place — see Backup & Restore for exactly what import does and how it keeps the prior state aside.

How it works under the hood

• End-to-end encryption (E2EE). Each site has an X25519 keypair. The portal encrypts every archive to the site's public key using an ECIES-style hybrid scheme (a fresh ephemeral key per archive + AES-256-GCM), streaming in blocks so even multi-gigabyte bundles encrypt with constant memory. The server only ever receives ciphertext, and its API rejects any upload that isn't already encrypted. Only the site's private key — which you hold — can decrypt.
• Two backup scopes. The server distinguishes whole-site backups (full — database + uploads + key seed) from frontend-only backups (frontend — just the public web frontend), and applies retention to each scope independently, so frequent frontend snapshots never push out your full-site archives.
• Chunked uploads. For bundles larger than a single request can carry behind a proxy body cap, the portal automatically splits the upload into chunks and the server reassembles them, so large whole-site backups don't fail at the proxy.
• Two encryption layers, on purpose. E2EE (above) is keyed to you and makes the storage zero-knowledge. The optional at-rest encryption from step 3.2 is keyed to the server and protects the disk volume. They're independent; with E2EE on, the bytes are already opaque to the server regardless.

Troubleshooting

Security notes

• Always run the backup server behind TLS in production. The Bearer key and console cookie must never cross plaintext. Leave TSPB_DEBUG=0.
• Change the seeded admin password immediately (step 3.1).
• Keep TSPB_SECRET_KEY long, random, and stable, and never commit .env.
• Guard the site private keys. They're your only way to read your backups, and the server can't recover them. A password manager entry per site is the right home.
• If you use at-rest encryption, back up rest.key / TSPB_REST_PASSPHRASE along with the volume — losing it makes the stored bytes unrecoverable at the storage layer, by design.
• Back up the backup server's ./data too. It holds the site list, settings, metadata, and the stored archives. To migrate the server to a new host, stop the container and copy the whole ./data directory.

Next steps

• Backup & Restore — local exports, imports, and what an import actually replaces.
• Configuration & Security — the portal's own environment variables and how it encrypts stored credentials.
• Email Relay — the other companion container, for hosts that block outbound SMTP.
• Upgrading & Uninstalling — staying current and clean teardown.