Monitor and maintain

This page covers running a Sluby server day to day: the health endpoint, the status view, logs, Prometheus metrics, the storage check that compares your database with Sia, and upgrades.

The commands below are for the base stack. On a production server, add -f docker-compose.yml -f docker-compose.prod.yml after docker compose.

Service healthCopy Anchor Link

The postgres, redis, backend and web services have Docker health checks. See their state with:

docker compose ps

The web proxy starts only after the backend reports healthy, and its own health check goes through to the backend, so web turns unhealthy when it can no longer reach the backend.

Health endpointCopy Anchor Link

GET /health answers while the backend process is up:

curl http://localhost:8080/health

{ "status": "ok", "timestamp": "2026-10-20T09:00:00.000Z", "version": "0.2.0" }

It reports liveness only, so a slow indexer never makes Docker restart the backend. The state of the database, Redis and the Sia indexer is in the status view below. The version field is the backend's version.

Status viewCopy Anchor Link

Admins see the full status in the Studio under Deployment > Health: database, Redis, the Sia indexer with account usage and hosts, the last storage check and the delivery cache. See Overview, health and metrics.

The same data comes from GET /api/v1/system/status. Admins get the full status, members a health summary: system status reference.

LogsCopy Anchor Link

docker compose logs -f backend

• LOG_LEVEL sets how much the backend logs.
• With NODE_ENV set to production each line is a JSON object. Otherwise the lines are colored text.
• Requests to /health log at debug, so the health checks do not fill the log at info.
• Docker keeps at most five files of 10 MB of logs per service, then drops the oldest.

Prometheus metricsCopy Anchor Link

The backend serves Prometheus metrics at GET /metrics on its port 3000. The Compose files publish no backend port, so a scraper reaches it in one of two ways:

So metrics are never public: through the web proxy they need METRICS_TOKEN, and without it the proxy answers 404 and does not reveal that the endpoint exists. The backend tells the two apart by the X-Forwarded-For header, which the web proxy always sets on /metrics, replacing any value the client sent. A request with X-Forwarded-For or Forwarded counts as proxied, so a proxy of your own in front of port 3000 that adds either header is treated the same way.

To scrape from outside the server, set a token:

METRICS_TOKEN=<generated value>

and give your scraper the same value as a bearer token, for example in Prometheus:

scrape_configs:
  - job_name: sluby
    scheme: https
    authorization:
      credentials: <generated value>
    static_configs:
      - targets: ['video.example.com']

The web proxy limits /metrics per client address like sign-in (WEB_AUTH_RATE and the settings next to it), which a scrape every few seconds stays well under.

To look at the metrics from the server:

docker compose exec backend node -e "fetch('http://127.0.0.1:3000/metrics').then(r => r.text()).then(console.log)"

Add { headers: { Authorization: 'Bearer <token>' } } as the second argument to fetch when a token is set.

Besides the Node.js process metrics, the backend exports:

Storage checkCopy Anchor Link

The storage check (reconciliation) compares the objects your database expects with what the indexer stores, and reports the differences. It runs on a schedule, and a separate sweep on its own schedule finishes deletions that stopped partway. What the report means: Deletion and reconciliation.

• In the Studio: an admin sees the result on the Storage check card of the Health page and starts a run with Check now.
• With the API: read the latest report with GET /api/v1/reconciliation and start a run with POST /api/v1/reconciliation/run, which needs an admin's key with the manage scope.

Turn the schedules on or off and change their intervals with RECONCILE_ENABLED, RECONCILE_INTERVAL_MS, DELETION_GC_ENABLED and DELETION_GC_INTERVAL_MS. The configuration reference lists each default.

Housekeeping the backend doesCopy Anchor Link

At startup and then every hour, the backend cleans up on its own. Nothing needs to be scheduled for this. It removes:

• uploads that expired unfinished (when an upload expires);
• source files it no longer needs;
• ended Studio sessions past their retention (sessions);
• webhook delivery records past their retention (delivery log).

UpgradeCopy Anchor Link

git pull

docker compose up -d --build

docker compose logs backend | grep -i migration

When several backend containers start at once, they apply migrations one at a time; the later ones find nothing left to do.

On stop or restart, the backend stops taking requests and gives running work 25 seconds to finish. Docker waits 30 seconds before it kills the container.

RelatedCopy Anchor Link

• Troubleshooting
• Configuration reference