LobeHub SSOT

3 min read

Runtime runbook

Preconditions

  • working directory: ~/dev/lobe
  • Docker access: every Compose command uses sudo -n
  • required external dependency:
    • Docker network lllm_default exists
    • container lllm-proxy is attached and ready on port 4000
  • protected configuration:
    • .env exists, is gitignored, and has mode 0600
    • never read or print .env during routine operation

Validate without rendering secrets

cd ~/dev/lobe
sudo -n docker compose config --quiet

A zero exit proves Compose can parse and interpolate the protected configuration. Do not run docker compose config without --quiet; its rendered output contains secret values.

Start or reconcile

cd ~/dev/lobe
sudo -n docker compose up -d
sudo -n docker compose ps -a

Expected dependency order:

  • PostgreSQL, Redis, and RustFS become healthy.
  • rustfs-init creates bucket lobe, applies the anonymous read policy, and exits 0.
  • Lobe starts only after those health and completion conditions pass.
  • SearXNG runs privately on the Compose network.

up -d also reconciles an edited image digest and allows LobeHub to perform its normal database migration. Follow upgrades before using it for a version change.

Read status

sudo -n docker compose ps -a

The stable shape is:

  • lobe: running and healthy
  • lobe-postgres: running and healthy
  • lobe-redis: running and healthy
  • lobe-rustfs: running and healthy
  • lobe-searxng: running
  • lobe-rustfs-init: exited with status 0

SearXNG has no Compose healthcheck, so its expected state is running rather than a healthy annotation.

Read scoped logs

sudo -n docker compose logs --tail=100 lobe
sudo -n docker compose logs --tail=100 postgresql
sudo -n docker compose logs --tail=100 redis
sudo -n docker compose logs --tail=100 rustfs
sudo -n docker compose logs --tail=100 rustfs-init
sudo -n docker compose logs --tail=100 searxng

Use the service name shown in docker-compose.yml. Do not dump container environments or add shell tracing around commands that consume .env.

Host health checks

curl -fsS http://127.0.0.1:52100/ >/dev/null
curl -fsS http://127.0.0.1:52101/health >/dev/null
curl -fsS https://lobe.loca.zone/ >/dev/null
curl -fsS https://wiki.lobe.loca.zone/ >/dev/null

Interpretation:

  • loopback application failure isolates the fault below nginx
  • public application failure with successful loopback narrows the fault to nginx, TLS, or name routing
  • RustFS health failure blocks rustfs-init and therefore blocks Lobe startup
  • wiki health is independent of Compose and follows the active Quartz current symlink

Confirm the one-shot initializer

sudo -n docker compose ps -a rustfs-init
sudo -n docker compose logs --tail=100 rustfs-init

Success is an exited status of 0 after bucket creation or confirmation and policy installation. Restart loops are not expected because the service has restart: "no".

Public-route expectations

  • https://lobe.loca.zone/: LobeHub; nginx proxy buffering and cache disabled for streamed responses
  • https://s3.lobe.loca.zone/: RustFS S3 API only; no console
  • https://wiki.lobe.loca.zone/: static Quartz release
  • missing wiki routes: 404
  • HTTP on all three names: ACME challenge handling followed by HTTPS redirect for other paths

Next procedures