Skip to content
Citinet Docs

Command-Line Reference

Everything in Managing Your Hub works entirely through the browser; you should never need a terminal to run a hub. This page is for admins who want to go a level deeper anyway: the actual commands used to inspect, debug, and understand what a hub is doing underneath, the same way problems on this project get diagnosed in practice.

Your hub’s containers

Section titled “Your hub’s containers”

A hub runs as a handful of Docker containers, each with one job:

Container What it does
citinet-api The API and web portal your hub actually serves
citinet-db Postgres, your hub’s database
citinet-storage MinIO, your hub’s file storage
citinet-redis Redis, used for caching/sessions
citinet-caddy Terminates HTTPS using your hub’s certificate
citinet-ollama Local AI, only present if enabled

Checking what’s running

Section titled “Checking what’s running”
Terminal window
docker compose ps

Shows every container for this hub and whether Docker considers it healthy. docker ps (no compose) shows this for every container on the machine, not just this hub’s.

Reading logs

Section titled “Reading logs”
Terminal window
docker logs citinet-api --tail 50

The most recent 50 lines from that container. Drop --tail 50 to see everything since it started, or add -f to follow new lines live (Ctrl+C to stop):

Terminal window
docker logs -f citinet-api

Swap citinet-api for any container name from the table above.

Finding a specific kind of log line

Section titled “Finding a specific kind of log line”
Terminal window
docker logs citinet-api 2>&1 | grep certAgent

Useful for checking on the automatic-HTTPS system specifically, see The Cert Broker for what these lines mean. Swap certAgent for anything else you’re looking for.

Getting a shell inside a container

Section titled “Getting a shell inside a container”
Terminal window
docker exec -it citinet-api sh

Drops you into a live shell inside that container. citinet-api runs on Alpine Linux, so it’s sh, not bash. Type exit to leave, this does not stop the container.

Talking to the database directly

Section titled “Talking to the database directly”
Terminal window
docker exec -it citinet-db psql -U citinet -d citinet

Opens a live Postgres prompt against your hub’s actual database. \dt lists tables, \q quits. This is real, live production data. See the safety note below before running anything beyond read-only SELECT queries.

Restarting a specific service

Section titled “Restarting a specific service”
Terminal window
docker compose restart citinet-api

Restarts just that one container, leaving everything else (and all data) untouched. Useful after changing something in .env that a service reads only at startup.

Checking your hub’s HTTPS certificate

Section titled “Checking your hub’s HTTPS certificate”

From any machine, not necessarily the hub itself:

Terminal window
curl -I https://yourhub.hub.citinet.cloud

A 200 OK (or similar) with no certificate warning means it’s working. To see the certificate’s actual details, issuer, and expiry date:

Terminal window
echo | openssl s_client -connect yourhub.hub.citinet.cloud:443 -servername yourhub.hub.citinet.cloud 2>/dev/null | openssl x509 -noout -issuer -subject -dates

A real certificate shows issuer=... O=Let's Encrypt .... If it instead shows the same name in both issuer and subject, that’s a temporary self-signed placeholder Caddy uses for the first minute or two after a hub starts, before the real certificate arrives, see The Cert Broker for why that exists.

Safety notes

Section titled “Safety notes”

A few commands look similar to the ones above but are meaningfully more dangerous. Know the difference before running them:

If you’re ever unsure whether a command is safe to run on a live hub, it’s worth asking first, see Troubleshooting & Getting Help.