Skip to content

Getting Started

New to the CharlieHub cluster? This section will help you get oriented.

In This Section

Quick Start

  1. Read the Architecture (10 min)
  2. Architecture Overview covers the complete hub2 design
  3. Understand unified Traefik (single ACME instance for all routing)

  4. Learn about security hardening and domain-manager control plane

  5. Understand the Cluster (5 min)

  6. Cluster Overview shows infrastructure topology
  7. Review node roles and storage architecture

  8. Check WireGuard VPN setup

  9. Set Up Access (15 min)

  10. Access Setup - SSH, VPN, and bastion
  11. Configure WireGuard to reach hub2 services

  12. Test connectivity to hub2

  13. Complete Onboarding (30 min)

  14. First Day Checklist
  15. Verify all systems

  16. Familiarize yourself with key services

  17. Learn Daily Tasks (5 min)

  18. Operations - Daily Tasks
  19. Understand health checks
  20. Review monitoring dashboards

Key Concepts

Unified Traefik Architecture

CharlieHub now uses a single unified Traefik instance (ACME-only) for all routing:

Aspect Details
Instance Single container (charliehub-traefik)
Access Internet (0.0.0.0:80, 0.0.0.0:443) + TCP services (0.0.0.0:8883)
Services ~23 HTTP routes + 1 TCP route (MQTT)
Certificates ACME/Let's Encrypt only (unified)
Configuration PostgreSQL domains table → Domain Manager API → generated routes.yml
Access Control Authelia SSO for public routes, IP-based for internal access

Key Change (Feb 12, 2026): Previously used dual-Traefik (public + internal CA). Now consolidated to unified ACME instance for simplicity and consistency.

See Architecture Overview for complete details.

Domain Manager Control Plane

All routing is managed through a drift-proof control plane:

PostgreSQL domains table
         ↓
Domain Manager API (/api/domains/*)
         ↓
traefik_generator.py (generates routes)
         ↓
/traefik/config/generated/routes.yml
         ↓
Traefik (loads and serves)

Key Principle: PostgreSQL is the single source of truth. Docker labels and manual YAML are disabled. All changes go through the API.

WireGuard VPN Connectivity

hub2 connects to UK and FR homelabs via WireGuard: - wg-uk: 10.44.x.x subnet (px1, px2, px3 Proxmox cluster) - wg-fr: 10.35.x.x subnet (px5-lemans, QDevice for quorum)

To access hub2 services, you should be connected to WireGuard (though many services are also internet-facing).

Security Hardening

The infrastructure includes comprehensive hardening (Feb 2026): - File permissions (code read-only, data writable) - Firewall rules persisted across reboots (netfilter-persistent) - Pre-commit hooks prevent secret leaks - Quarterly secret rotation - Full audit trail (git log, journalctl, auditd)

See Security Maintenance for details.

Standards & Governance

All infrastructure follows the 10 Commandments of the Control Plane:

  1. Database table is the source of truth
  2. All changes go through the API
  3. Never edit generated files directly
  4. Never create manual configuration files
  5. Never use Docker labels
  6. Never bypass the validation layer
  7. Extend the API, don't bypass it
  8. Output files are read-only artifacts
  9. No temporary routes, no shadow configs
  10. When unsure: STOP and propose an extension

See Standards & Governance for complete documentation.

Need Help?

Key Documentation

For Operators: - Operator How-To - Safe change procedures - Security Maintenance - Hardening details - Daily Tasks - Regular maintenance - Troubleshooting - Common issues

For New Developers: - Agent Guides - API and integration - Access Setup - SSH and VPN configuration - Services Documentation - Available services

For Infrastructure Planning: - Cluster Overview - Topology and HA - Network Layout - Subnets and routing - Disaster Recovery - Backup and failover - Standards & Governance - Control plane rules

Important Notes

Critical Bug: docker compose restart

⚠️ DO NOT USE: docker compose restart SERVICE - Does NOT reload .env variables - Changes to environment won't take effect

✅ USE INSTEAD: 

docker compose rm -f SERVICE
docker compose up -d SERVICE

See Architecture Overview for details.

Adding New Routes

Never create manual routes or use Docker labels.

Instead, use the Domain Manager API:

curl -X POST http://localhost:8001/api/domains \
  -H "X-API-Key: charliehub" \
  -d '{
    "domain": "myservice.charliehub.net",
    "protocol": "http",
    "backend_host": "myservice",
    "backend_port": 8080,
    "auth_required": true,
    "status": "active"
  }'

Routes regenerate automatically. See Operator How-To for complete procedures.

Last updated: February 12, 2026 — Unified ACME architecture