CharlieHub Traefik & Domain Management - Hub2 Specific Guidelines¶

Last Updated: 2026-02-09 Scope: Hub2 Only - For infrastructure management and domain routing Status: ENFORCED

🚨 CRITICAL MANDATE: Use the API, Never Edit Traefik YAML¶

THE RULE¶

ALL domain routing, DNS configuration, and Traefik setup MUST go through the Domain Manager API.

❌ DO NOT edit files in /opt/charliehub/traefik/config/dynamic/ directly ❌ DO NOT create new YAML files manually ❌ DO NOT modify existing .yml files via nano, vim, sed, or sudo tee

✅ DO use charliehub-domain command ✅ DO use the REST API if the CLI isn't available ✅ DO verify changes through the audit trail

✅ How to Add/Update Domains on Hub2¶

Option 1: Simple CLI Wrapper (Fastest)¶

# Add a new domain (with optional auth bypass)
charliehub-domain add rodent.microshare.eu 10.44.1.235:8000 --no-auth --deploy

# Update an existing domain
charliehub-domain update 27 10.44.1.250:9000 --deploy

# List all domains
charliehub-domain list

# Get help
charliehub-domain help

Option 2: Direct API (When CLI Isn't Available)¶

# Set API key (ask DevOps if you don't have it)
export DOMAIN_MANAGER_API_KEY="YOUR_API_KEY_HERE"

# Create domain
curl -X POST http://172.19.0.5:8001/api/domains \
  -H "X-API-Key: $DOMAIN_MANAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "rodent.microshare.eu",
    "service_type": "http",
    "backend_host": "10.44.1.235",
    "backend_port": 8000,
    "auth_required": false
  }'

# Deploy changes
curl -X POST http://172.19.0.5:8001/api/deploy-all \
  -H "X-API-Key: $DOMAIN_MANAGER_API_KEY"

📋 Deployment Checklist (Before Adding Domain)¶

When you need to expose a service on Hub2:

# 1. Verify service is running
ping 10.44.1.235
curl http://10.44.1.235:8000/health

# 2. Register domain via charliehub-domain
charliehub-domain add rodent.microshare.eu 10.44.1.235:8000 --no-auth --deploy

# 3. Verify DNS resolves
dig rodent.microshare.eu +short

# 4. Test public URL
curl -I https://rodent.microshare.eu/

# 5. Check audit trail
charliehub-audit-report | tail -5

🚫 Banned on Hub2¶

What	Why	Use Instead
Editing `/opt/charliehub/traefik/config/dynamic/*.yml`	Bypasses validation & audit	`charliehub-domain`
Creating new `.yml` files in traefik/config/dynamic/	Manual edits = no audit trail	`charliehub-domain add`
`sudo nano/vim/sed` on Traefik configs	No validation, breaks routing	Use the API
Direct database edits	Database is firewalled by design	Use the API
`docker restart charliehub-traefik` without deploy	Doesn't apply config changes	Use `charliehub-domain --deploy`

🆘 Emergency: Service is 404/503¶

Even in emergencies, use the API (it's actually faster):

# What DOESN'T work:
ssh hub2 "sudo vim /opt/charliehub/traefik/config/dynamic/something.yml"
# ^ Takes manual investigation + file editing + doesn't validate

# What DOES work (5 seconds):
charliehub-domain add missing-domain.charliehub.net 10.44.x.x:port --deploy
# ^ Validates + applies + logs automatically

📚 Full Documentation¶

For complete API reference: /opt/charliehub/AGENT_API_GUIDE.md

For troubleshooting errors: /opt/charliehub/AGENT_TROUBLESHOOTING.md

For quick start: /opt/charliehub/AGENT_START_HERE.md

For all agent guidelines: See CLAUDE.md files on other nodes (referenced below)

This file applies only to Hub2 and domain/Traefik management.

For general node management, see CLAUDE.md on: - px1 - Proxmox cluster management - px2 - Proxmox cluster management - px3 - Proxmox cluster management - px5 - Proxmox cluster management

Each node has its own guidelines. This file overrides them only for Traefik/domain routing.

✋ Before You Deploy¶

Checklist:

[ ] Service is running on the container (curl /health returns 200)
[ ] Backend IP:port is reachable from hub2 (ping + curl work)
[ ] Domain name is registered with charliehub-domain
[ ] Deploy command was run (charliehub-domain ... --deploy)
[ ] Changes appear in audit trail (charliehub-audit-report)
[ ] DNS resolves (dig domain.charliehub.net +short)
[ ] Public URL is accessible and returns correct status

🆘 Troubleshooting¶

"Permission denied" when editing Traefik files? → Good! Files are read-only by design. Use charliehub-domain instead.

"Connection refused" to database? → Normal. Database is firewalled. Use the API instead.

Domain still returns 404? → Run charliehub-domain list and verify it exists → Run charliehub-domain ... --deploy to ensure changes applied

API returns error? → See AGENT_API_GUIDE.md troubleshooting section → Or run /opt/charliehub/agent-help

💡 Remember¶

🎯 API = Safe + Validated + Audited + Fast
🚫 Manual YAML = Dangerous + Silent failures + No audit trail

If you bypass the API, you're not saving time—you're creating debt.

Questions? 1. Run: charliehub-domain help 2. Read: AGENT_API_GUIDE.md 3. Run: /opt/charliehub/agent-help 4. Ask: Your DevOps engineer

Last updated: 2026-02-09 For issues: Report to DevOps team