Operations

This page covers the lifecycle of a self-hosted instance: license, updates, runtime management, and clean shutdown.

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.

State	What changes
Active	Normal operation.
Expiring Soon	A warning banner appears, but nothing is restricted yet.
Write Restricted	Creating new users and stations is blocked. Existing data and runs are unaffected.
Expired	A 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:

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

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 update, copy the license token for air-gapped activation, or delete the instance.

Update

To update to the latest version, re-run the deploy script:

curl -sSL https://tofupilot.sh/deploy | bash

To pin a specific version, pass it explicitly:

curl -sSL https://tofupilot.sh/deploy | bash -s -- --version 2.8.0

Downgrades are not supported, which protects your data. Orbit shows the new version once the update finishes.

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://tofupilot.sh/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.

Volume	Contents
`tofupilot-pg-data`	PostgreSQL database
`tofupilot-seaweed-data`	Uploaded 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.

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:

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).
Check the realtime server is up: docker compose logs tofupilot-centrifugo --tail 50.
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.

Deployments not building

The deployments pipeline runs in the tofupilot-deployer container:

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.
Inspect build activity: docker compose logs tofupilot-deployer --tail 100.
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 -sSL https://tofupilot.sh/deploy | bash -s -- --uninstall

This deletes all containers, volumes, configuration, and data. To also revoke the license, delete the instance from TofuPilot Orbit.