Skip to content

quick-start.md

Latest commit

 

History

History
173 lines (122 loc) · 3.6 KB

quick-start.md

File metadata and controls

173 lines (122 loc) · 3.6 KB

Quick Start Guide

Get Charon deployed in 5 minutes!

Prerequisites Checklist

  • Kubernetes cluster (Linode LKE, k3s, or similar)
  • kubectl configured and working
  • Terraform v1.0+ installed
  • Cloudflare account with domain
  • Cloudflare API token (DNS edit permissions)

→ Detailed: Prerequisites Guide

1. Clone and Configure

# Clone the repository
git clone https://github.com/your-org/charon.git
cd charon

# Create environment file
cat > .env << EOF
CLOUDFLARE_API_TOKEN="your-api-token-here"
EOF

# Copy and edit terraform vars
cd terraform
cp terraform.tfvars.example terraform.tfvars

Edit terraform.tfvars:

cloudflare_zone_id    = "your-zone-id"
cert_manager_email    = "you@example.com"
headscale_server_url  = "https://vpn.example.com"
domain_name           = "example.com"

→ Detailed: Configuration Guide

2. Deploy Everything

# Load credentials
source ../.env
export TF_VAR_cloudflare_api_token="$CLOUDFLARE_API_TOKEN"

# Initialize
terraform init

# Deploy (takes ~5-10 minutes)
terraform apply

What happens:

  • ✅ cert-manager installs
  • ✅ Headscale VPN deploys
  • ✅ TLS certificates provision
  • ✅ Services start (Grafana, FreeIPA, etc.)
  • ✅ DNS records auto-configure

3. Verify Deployment

# Check all pods are running
kubectl get pods -n dev

# Should see:
# headscale-0      1/1     Running
# grafana-0        3/3     Running
# freeipa-0        2/2     Running
# open-webui-0     3/3     Running

4. Enroll Your Device

# Get a pre-auth key
kubectl exec -n dev headscale-0 -- headscale preauthkeys create \
  --user default --reusable --expiration 90d

# Connect your device
tailscale up --login-server https://vpn.example.com --authkey <your-key>

# Verify connection
tailscale status

→ Detailed: VPN Enrollment Guide

5. Access Services

Once connected to VPN:

# Grafana
https://grafana.example.com
# Login: admin / (check Grafana docs for initial password)

# FreeIPA
https://freeipa.example.com
# Login: admin / (generated password in terraform output)

# Open-WebUI
https://ai.example.com
# Use FreeIPA credentials

Next Steps

Common Issues

Pods stuck in Pending

# Check PVC status
kubectl get pvc -n dev

# Check storage class
kubectl get storageclass

Fix: Ensure your cluster has a default storage class configured.

DNS not resolving

# Check if records were created
dig vpn.example.com

Fix: Verify cloudflare_zone_id is correct and API token has DNS edit permissions.

Certificates not provisioning

# Check cert-manager
kubectl get pods -n cert-manager
kubectl logs -n cert-manager -l app=cert-manager

# Check certificate status
kubectl get certificate -n dev

Fix: Verify Cloudflare API token has Zone:DNS:Edit permissions.

→ Full guide: Troubleshooting

Clean Up

To remove everything:

cd terraform
terraform destroy

Warning: This deletes all services and data!

Navigation: 📚 Documentation Index | 🏠 Home | Next: Configuration →