Operations

Last updated on November 20, 2026

This page covers the lifecycle of a self-hosted instance installed with Docker Compose: license, upgrades, runtime management, backups, and clean shutdown. For a Helm install, see Kubernetes.

License

Your instance pulls its license from Orbit on first boot. The license controls plan, usage limits, and feature availability.

View your license

To inspect your current license, open Settings > Subscription in your dashboard. You see your plan, license status, and current usage.

Refresh your license

When you upgrade your plan or renew, click the refresh button on the license card to sync the latest license from Orbit.

License expiry

Licenses are valid for a set period. As a license approaches or passes its expiry date, the instance gradually restricts write operations.

StateWhat changes
ActiveNormal operation.
Expiring SoonA warning banner appears, but nothing is restricted yet.
Write RestrictedCreating new users and stations is blocked. Existing data and runs are unaffected.
ExpiredA renewal prompt appears on every page. Contact sales to renew.

Air-gapped activation

When your server has no internet, you can paste the license manually:

  1. In TofuPilot Orbit, open the instance menu and select Copy license token.
  2. In your dashboard, go to Settings > Subscription.
  3. Click the upload button on the license card.
  4. Paste the token and click Activate.

Manage from Orbit

Orbit gives you an overview of every self-hosted instance, with running version, domain, and last check-in. From the instance menu you can open the dashboard, re-deploy, trigger an upgrade, copy the license token for air-gapped activation, or delete the instance.

Upgrade

To move to a newer version, back up your data and re-run the deploy script. Downgrades are not supported, which protects your data. See Upgrade for the full procedure, version pinning, realtime setup on older instances, and post-upgrade checks.

Reconfigure

When you need to change configuration after deploying, such as adding an OAuth provider or updating SMTP, edit .env and re-run the deploy command:

curl -fsSL https://www.tofupilot.com/deploy | bash

Data and auto-generated secrets are preserved across re-runs.

Manage with Docker Compose

You can manage the instance from the server with Docker Compose:

docker compose ps          # Check service statusdocker compose logs -f     # Follow live logsdocker compose restart     # Restart all servicesdocker compose down        # Stop all servicesdocker compose up -d       # Start all services

When something is not working as expected, check the application logs first:

docker compose logs tofupilot-dashboard --tail 100

Backups

Your data lives in two Docker volumes. Back them up on a regular schedule.

VolumeContents
tofupilot-pg-dataPostgreSQL database
tofupilot-seaweed-dataUploaded files, attachments, and build artifacts

A third volume, tofupilot-deployer-docker, holds the build worker's local Docker state (sandbox images it builds on demand). It is regenerated automatically and does not need backing up.

Automatic pre-migration dumps

Each time a new dashboard version starts, it dumps the database before applying its migrations. The dumps are your restore point if an upgrade goes wrong. They are not a replacement for regular backups: they only cover the database, and only at upgrade time.

PropertyBehavior
WhereThe tofupilot-backups volume, mounted at /backups in the tofupilot-dashboard container
WhenOn the first start of each version. A restart or a crash loop of the same version takes no second dump. A fresh install takes none (the database is empty).
Name<date>_<time>_pre-v<new>_from-v<old>.sql.gz: the database as version <old> left it, taken before version <new> migrated it. from-unknown means the previous version was not recorded (instances last started on 2.52.8 or earlier). Dumps made before 2.52.9 are named <date>_<time>_v<new>.sql.gz and usually hold the database of the version that ran before <new>.
Retention7 days. Incomplete dumps (.sql, .err) left by an interrupted start are removed after 24 hours.
On failureThe start continues without a dump and logs a warning. Set REQUIRE_BACKUP=true in .env to abort the start instead, before any migration runs.

Restore a pre-migration dump

Restore a dump with the version it came from, the v<old> in its name. For a from-unknown or older-style dump, <old> is the version you ran before that upgrade: the deploy script printed it on that run (Upgrading from <old> to <new>). a newer version would migrate it again, an older one cannot read it. Files uploaded after the dump stay in storage but are no longer referenced.

  1. List the dumps and copy the one you need out of the container:
docker exec tofupilot-dashboard ls -l /backupsdocker cp tofupilot-dashboard:/backups/<file>.sql.gz .
  1. Stop the dashboard and the build worker, then replace the database with an empty one:
docker compose stop tofupilot-dashboard tofupilot-deployerdocker exec tofupilot-pg dropdb -U tofupilot tofupilotdocker exec tofupilot-pg createdb -U tofupilot tofupilot
  1. Load the dump:
gunzip -c <file>.sql.gz | docker exec -i tofupilot-pg psql -U tofupilot -d tofupilot -v ON_ERROR_STOP=1
  1. Remove the dashboard container, so the deploy script accepts the older version, and deploy the version the dump came from:
docker compose rm -f tofupilot-dashboardcurl -fsSL https://www.tofupilot.com/deploy | bash -s -- --version <old>

Troubleshooting

Realtime views not updating

Live station status, telemetry, and streaming build logs connect over WebSocket to CENTRIFUGO_DOMAIN_NAME. If those views fall back to manual refresh:

  1. Confirm the realtime subdomain has a DNS A record pointing at the server and that its TLS certificate issued (docker compose logs tofupilot-proxy shows the Let's Encrypt exchange).
  2. Check the realtime server is up: docker compose logs tofupilot-centrifugo --tail 50.
  3. Verify the browser can reach wss://<CENTRIFUGO_DOMAIN_NAME>/connection/websocket (a 400 from a plain HTTPS request is expected — it means the endpoint is reachable and waiting for a WebSocket upgrade).

The rest of the application works without realtime; only the live views are affected.

If one station has no live view while the others do, open its page: it says when the station and the dashboard speak different realtime protocols, and which one to upgrade. See Station and dashboard compatibility.

If no station has a live view and each station page says the realtime server is not configured for this dashboard, the realtime server predates the dashboard: re-run the deploy script, which rewrites centrifugo-config.json and recreates the realtime server. If you edited centrifugo-config.json by hand, run docker compose up -d --force-recreate tofupilot-centrifugo: the realtime server reads it only at start, and an editor that saves to a new file leaves a restarted container on the old one.

Deployments not building

The deployments pipeline runs in the tofupilot-deployer container:

  1. It needs standard (root) Docker. Under rootless Docker it will not start — check docker compose ps and use a root Docker installation if it is missing.
  2. Inspect build activity: docker compose logs tofupilot-deployer --tail 100.
  3. On the first build the worker builds its sandbox image inside its own Docker daemon, which takes a few minutes; subsequent builds are fast.

Uninstall

To remove TofuPilot from your server completely, run:

curl -fsSL https://www.tofupilot.com/deploy | bash -s -- --uninstall

Run it from the directory where TofuPilot was installed, the one that holds its docker-compose.yml. From any other directory, or next to a compose file that is not TofuPilot's, the script stops without deleting anything. It shows what it will delete and asks you to type DELETE before it starts.

The uninstall removes only what the deploy script created for this install, identified by its Docker Compose project (the directory name, for example root for /root):

  • Containers: tofupilot-proxy, tofupilot-dashboard, tofupilot-pg, tofupilot-seaweed, tofupilot-centrifugo, tofupilot-deployer.
  • Volumes, with all their data: <project>_tofupilot-pg-data (database), <project>_tofupilot-seaweed-data (uploaded files), <project>_tofupilot-backups (database dumps taken before each migration), <project>_tofupilot-proxy-acme (Let's Encrypt certificates), <project>_tofupilot-deployer-docker (deployer build cache).
  • Network: <project>_tofupilot.
  • Configuration: .env, docker-compose.yml, centrifugo-config.json, traefik-routes.yml, traefik-tls.yml.
  • Images: every ghcr.io/tofupilot/* image, plus traefik:v3, postgres:17-alpine, chrislusf/seaweedfs:3.80, chrislusf/seaweedfs:4.54 and centrifugo/centrifugo:v6.9.7 when no other container uses them.

It does not touch anything else on the server: other containers, volumes and networks, including other Compose stacks in the same directory, are kept. Images other than the ones above are kept. A listed third-party image you pulled for other work is removed if no container uses it at that moment; docker pull brings it back. Your custom certificate and CA files and backups stored outside these volumes are kept too. Back up the database and uploaded files first (see Backups) if you may need the data again.

To also revoke the license, delete the instance from TofuPilot Orbit.

How is this guide?

On this page