This guide provides quick reference information for Claude Code when working with the Lucille4 homelab repository. It emphasizes security best practices, common operations, and troubleshooting procedures.
Note: This is a wiki reference page. The authoritative CLAUDE.md instructions live with the code in the homelab-lucille4 GitHub repository. This architectural pattern ensures Claude Code instructions are version-controlled alongside the infrastructure code they document.
.env file (encrypted with git-crypt)latest tag only for utility containerscaddy network for externally accessible servicesinternal network for backend-only servicessudo -E ./backup.sh before major updatesdocker compose up -d [service] # Deploy or update service
docker compose logs -f [service] # View real-time logs
docker compose restart [service] # Restart service
docker compose down [service] # Stop and remove container
docker compose ps # List all services
sudo -E ./backup.sh # Full backup (Paperless + Restic)
docker ps # Check running containers
docker stats # Real-time resource usage
python3 check-updates.py # Check for container updates
df -h # Check disk space
docker system df # Docker disk usage
./reload-caddy.sh # Reload Caddy configuration
/home/mspeicher/homelab-lucille4/
├── docker-compose.yml # Main service definitions
├── .env # Encrypted credentials (git-crypt)
├── backup.sh # Automated backup script
├── profile.yaml # Restic backup configuration
├── check-updates.py # Container update checker
├── reload-caddy.sh # Caddy reload helper
├── caddy/
│ └── etc/Caddyfile # External service routing
├── paperless/
│ └── data/ # Document storage
├── ollama/
│ └── models/ # LLM model storage
├── qdrant/ # Vector database storage
└── mcp-servers/ # MCP server configurations
caddy and internalinternal onlymyservice:
image: myimage:1.0.0 # Always pin version
container_name: myservice
restart: always
networks:
- caddy # If externally accessible
- internal # If needs database access
environment:
- MY_VAR=${MY_VAR} # From .env file
labels: # Auto-configure Caddy
caddy: myservice.speicher.family
caddy.reverse_proxy: "{{upstreams 8080}}"
caddy.encode: gzip zstd
volumes:
- myservice_data:/data # Use named volumes
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s
timeout: 10s
retries: 3
volumes:
myservice_data:
external: true
Create in 1Password first:
Add to .env file:
op item create --category=login \
--title="MyService - Homelab" \
--vault="Private" \
--tags=homelab \
generate-password=32
MY_SERVICE_PASSWORD=generated_password_here
docker compose up -d myservice
## Check logs for errors
docker logs [container] --tail 50
## Recreate container
docker compose down [service]
docker compose up -d [service]
## Check for port conflicts
docker ps | grep :8080
## Pull latest image
docker compose pull [service]
## Recreate with new image
docker compose up -d [service]
## Verify update
docker ps | grep [service]
sudo -E ./backup.sh
df -h # System disk usage
docker system df # Docker specific usage
docker system prune -a # Clean up (careful!)
## Stop all services
docker compose down
## Start critical services first
docker compose up -d auth-db auth-redis auth-server
docker compose up -d caddy
docker compose up -d paperless-db paperless-broker paperless
## Then start remaining services
docker compose up -d
op item create --category=login \
--title="ServiceName - Homelab" \
--vault="Private" \
--tags=homelab \
username=admin \
generate-password=letters,digits,symbols,32
op item list --vault Private --tags homelab
op item get "ServiceName - Homelab" --fields password