Skip to content

installation.md

Latest commit

 

History

History
375 lines (261 loc) · 8.28 KB

installation.md

File metadata and controls

375 lines (261 loc) · 8.28 KB

Installation Guide

Complete step-by-step guide for deploying Charon infrastructure.

Prerequisites

Before installation, ensure you have completed all items in Prerequisites:

  • Kubernetes cluster (K3s recommended)
  • kubectl configured
  • Terraform >= 1.0
  • Required secrets (Cloudflare API token, GitHub PAT, etc.)
  • Domain name configured

Installation Steps

1. Clone the Repository

git clone https://github.com/vegcom/charon.git
cd charon

2. Configure Terraform Variables

Create your Terraform variables file:

cd terraform
cp terraform.tfvars.example terraform.tfvars
chmod 600 terraform.tfvars  # Secure the file

Edit terraform.tfvars with your configuration:

# Domain configuration
domain_name = "example.org"

# API tokens and secrets
cloudflare_api_token = "your-cloudflare-token"
github_token         = "github_pat_xxxxx"

# Service configurations
netbox_superuser_password = "secure-password"
freeipa_admin_password   = "secure-password"
grafana_admin_password   = "secure-password"

# Optional: Custom configurations
headscale_base_domain = "vpn.example.org"

Security Note: Never commit terraform.tfvars to version control. The file is in .gitignore by default.

3. Initialize Terraform

cd terraform
terraform init

This downloads required providers:

  • Kubernetes provider
  • Helm provider
  • Cloudflare provider (for DNS)

4. Review the Deployment Plan

terraform plan

Review the resources Terraform will create:

  • Kubernetes namespaces (core, monitoring, apps)
  • StatefulSets for services
  • ConfigMaps and Secrets
  • Ingress resources
  • Cloudflare DNS records

Expected Output: 200+ resources to be created on first deployment

5. Deploy Infrastructure

Single-Stage Deployment:

terraform apply

Type yes when prompted to confirm deployment.

What Happens During Deployment:

  1. Core Services (0-5 minutes)

    • Headscale VPN server
    • PostgreSQL databases
    • Redis caches

  2. Identity & Access (5-15 minutes)

    • FreeIPA (LDAP/Kerberos)
    • Initial admin user creation

  3. Infrastructure Services (15-30 minutes)

    • NetBox (custom image build + deployment)
    • Grafana + monitoring stack
    • cert-manager for TLS certificates

  4. Application Services (30-45 minutes)

    • Redmine
    • Gitea
    • Open-WebUI
    • Other configured applications

  5. Image Builds (runs in parallel)

    • NetBox custom image (DaemonSet)
    • Tailscale lifecycle automation (DaemonSet)

Expected Total Duration: 30-45 minutes for complete deployment

Monitoring Progress:

# Watch all pods
watch kubectl get pods -A

# Check specific namespace
kubectl get pods -n core
kubectl get pods -n monitoring

# View pod logs
kubectl logs -n core netbox-0 -c netbox -f

6. Post-Deployment Verification

Check Pod Status

All pods should reach Running state:

kubectl get pods -A | grep -v Running

Expected state: No output (all pods running)

Common states during deployment:

  • ContainerCreating - Normal during startup
  • Init:0/1 - Init containers running
  • ImagePullBackOff - Image build not complete (wait for DaemonSet)
  • CrashLoopBackOff - Check logs for errors

Verify DNS Records

Check that Cloudflare DNS records were created:

# From Terraform output
terraform output cloudflare_records

# Or manually check
dig netbox.example.org
dig grafana.example.org

Test Certificate Provisioning

cert-manager should automatically provision Let's Encrypt certificates:

# Check certificate status
kubectl get certificates -A

# View cert-manager logs
kubectl logs -n cert-manager deploy/cert-manager

Certificates should show Ready: True within 2-5 minutes.

Confirm Service Access

Test accessing services via browser:

Via VPN (Headscale):

  1. Install Tailscale client
  2. Configure to use Headscale server
  3. Access services at internal domains

Via Public Ingress (if configured):

  • Navigate to https://netbox.example.org
  • Verify TLS certificate is valid
  • Login with configured credentials

Common Deployment Issues

Issue: NetBox ImagePullBackOff

Symptom: NetBox pod shows ImagePullBackOff for localhost/netbox-custom:latest

Cause: Image builder DaemonSet hasn't completed yet

Solution:

# Check image builder status
kubectl get pods -n core -l app=netbox-image-builder

# Wait for all pods to be Ready (6/6)
# Then delete NetBox pod to retry
kubectl delete pod -n core netbox-0

Issue: Tailscale Authentication Failures

Symptom: Service pods show CrashLoopBackOff in tailscale sidecar

Cause: Headscale server not ready or auth key issues

Solution:

# Verify Headscale is running
kubectl get pods -n core -l app=headscale

# Check Headscale logs
kubectl logs -n core headscale-0

# Restart affected service pod
kubectl delete pod -n core <pod-name>

Issue: Certificate Provisioning Timeout

Symptom: Certificates stuck in False state

Cause: Cloudflare DNS propagation delay or API token issues

Solution:

# Check certificate status
kubectl describe certificate -n core netbox-tls

# Verify Cloudflare secret
kubectl get secret -n cert-manager cloudflare-api-token

# Check cert-manager logs for errors
kubectl logs -n cert-manager deploy/cert-manager

Issue: Database Migration Failures

Symptom: NetBox/Redmine logs show migration errors

Cause: PostgreSQL not ready or database initialization issues

Solution:

# Check PostgreSQL sidecar
kubectl get pods -n core netbox-0 -o jsonpath='{.status.containerStatuses[?(@.name=="postgres")].ready}'

# Run migrations manually
kubectl exec -n core netbox-0 -c netbox -- python manage.py migrate

First-Time Setup Tasks

After deployment completes, perform these one-time configuration tasks:

1. Access NetBox

# Get NetBox URL from Terraform output
terraform output netbox_url

# Default credentials (change immediately)
Username: vegcom
Password: <from netbox_superuser_password variable>

First Login Tasks:

  • Change admin password
  • Configure site information
  • Import device types library
  • Set up IP prefixes and VLANs

2. Configure FreeIPA

# Access FreeIPA web UI
https://ipa.example.org

# Default credentials
Username: admin
Password: <from freeipa_admin_password variable>

First Login Tasks:

  • Create organizational units
  • Add user accounts
  • Configure group policies
  • Set up HBAC rules

3. Set Up Monitoring

Access Grafana:

https://grafana.example.org

Username: admin
Password: <from grafana_admin_password variable>

First Login Tasks:

  • Change admin password
  • Import dashboard templates
  • Configure data sources
  • Set up alert channels

4. Configure Backup Strategy

Critical Data to Backup:

  • PostgreSQL databases (NetBox, Redmine, Gitea)
  • FreeIPA data directory
  • Persistent volumes (Grafana, Loki, etc.)

See: Backup & Restore

Next Steps

After successful installation:

  1. Security Hardening

  2. Service Configuration

    • Configure LDAP integration for services
    • Set up VPN access for team members
    • Configure monitoring alerts
    • See: Configuration Guide

  3. Customize Deployment

    • Add additional services
    • Adjust resource limits
    • Configure custom domains
    • See: Adding Services

Troubleshooting Resources

Related Documentation

Navigation: Documentation Index | Home