Operations & Troubleshooting

Make commands

Run all commands from the top-level repo or code/ directory:

Canonical source is make help (auto-derived from the Makefile). The summary below is for orientation.

# Setup
make init             First-time setup (secrets, dirs, locks data/)
make setup-authentik  Configure 4-Tier RBAC automatically in Authentik (~60 s)
make setup-tunnel     Create Cloudflare tunnel + DNS + ingress; writes CF_TUNNEL_TOKEN to .env
make secrets          Regenerate random secrets in docker/.env

# Compose lifecycle
make up                      Start all services (all profiles)
make down                    Stop & remove all services
make start / make stop       Start/stop existing services without (re)creating them
make restart                 Restart all services
make logs                    Tail all logs
make status                  docker compose ps
make health                  Container health list
make update                  Pull + recreate all services

# Profiles (each of these auto-runs `core` first)
make core                    Traefik + Authentik + Dashboard + Tunnel
make photos                  + Immich (server + ML + postgres + redis)
make drive                   + Nextcloud + Obsidian
make plex                    + Plex + qBittorrent
make monitoring              + Grafana + Prometheus + Node Exporter
make vpn                     + Tailscale
make security                + CrowdSec + Loki + Promtail
make backup                  + nightly offen backup

# Targeted ops
make down-service s=X / stop-service s=X
make down-profile p=X / stop-profile p=X
make update-profile p=X / update-service s=X

# Data safety
make protect / unprotect / data-status    chflags uchg management
make clean                                docker system prune -f (never touches data/)

# Backup
make backup-now              Run a nightly-style backup immediately (offen)

# Observability
make mem-check               Per-container memory vs limits + OOM events
make emergency-stop          Stop everything except Traefik + Authentik + Dashboard + Tunnel

# Dev
make build / build-web       Build all / portfolio Docker images
make dev                     Run portfolio locally (Vite :5173)

make down vs make stop

• down: Stops and completely removes the containers and internal networks. This is the cleanest way to reset the environment. Because data/ is mounted independently, you will not lose your actual data.
• stop: Merely halts the containers but leaves them structurally intact. Use this if you just want to pause a service temporarily to save RAM.

Useful troubleshooting commands

# Check RAM usage of all containers
make mem-check

# Check memory manually via Docker directly:
docker stats --no-stream --format "table {{.Name}}\t{{.MemUsage}}\t{{.MemPerc}}"

# Check for OOM kills manually
docker inspect --format '{{.Name}}: OOMKilled={{.State.OOMKilled}}' $(docker ps -q)

# View Tailscale status
docker exec h5h_tailscale tailscale status

# View CrowdSec banned IPs
docker exec h5h_crowdsec cscli decisions list

# View CrowdSec alerts
docker exec h5h_crowdsec cscli alerts list

# Manually ban an IP in CrowdSec
docker exec h5h_crowdsec cscli decisions add -i 1.2.3.4 -d 24h -R "manual ban"

# Traefik logs via LogQL query in Grafana
# Go to grafana.h5h.me → Explore → Select Loki → LogQL:
#   {container="h5h_traefik"}         
#   {job="traefik-access"} |= "401"   

# Tail specific service logs manually
docker compose -f docker/docker-compose.yml logs -f tailscale
docker compose -f docker/docker-compose.yml logs -f crowdsec

Docker Compose Context

Services are strictly segmented into profiles so you don't overwhelm your RAM.

# Profile-based startup (recommended)
docker compose --profile photos --profile monitoring up -d

# Using Make explicitly
make photos && make monitoring