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 apply                    Reconcile stack to docker/profiles.env (recommended)
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 runner                  + h5h-runner task runner & R2 backup daemon

# 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 & Offsite
make backup-now              Run local backup and push to Cloudflare R2
make backup-stream           Stream Tier 1 state directly to Cloudflare R2 via rclone (0 host disk writes)
make r2-status               Check Cloudflare R2 backup storage capacity and objects

# 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.

Declarative Profile Management (make apply)

Instead of starting every profile at once or manually managing flags, make apply brings the local stack into the state declared in docker/profiles.env:

1. Toggle a profile: In docker/profiles.env, set the desired profile to true or false (for example, photos=true or photos=false) and run make apply.
2. Reconciliation: Running make apply starts newly enabled profiles and uses --remove-orphans to cleanly stop and remove any profiles set to false.
3. Default set: The default configuration declares core=true, monitoring=true, security=true, and runner=true, keeping MacBook RAM usage lean.

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