Full Installation

Full Installation Guide¶

This guide walks through the complete installation of the homelab platform, from initial configuration to full deployment of infrastructure and applications.

Prerequisites Required

Before installing, ensure you have completed the Prerequisites guide to set up: - Target nodes with compatible OS (Ubuntu 22.04+ or Debian 11+) - SSH key-based access between your control machine and all nodes - Cloudflare domain and API token - (Optional) Network storage (NAS/OMV with CIFS/iSCSI)

Step 1: Clone and Prepare¶

Clone the repository:

git clone https://github.com/chutch3/homelab.git
cd homelab

Install dependencies: The project uses Ansible for automation. Install it and other requirements via Task:
```
task ansible:install
```

Step 2: Configuration¶

1. Configure Host Inventory¶

Create your cluster configuration in the Ansible inventory:

# Create and edit your hosts file
nano ansible/inventory/02-hosts.yml

Example multi-node configuration:

ansible/inventory/02-hosts.yml

all:
  children:
    managers:
      hosts:
        manager-01:
          ansible_host: 192.168.1.100
          ansible_user: ubuntu
    workers:
      hosts:
        worker-01:
          ansible_host: 192.168.1.101
          ansible_user: ubuntu
          node_labels:
            gpu: true

2. Configure Environment Variables¶

Create your .env file from the provided example:

cp .env.example .env
nano .env

Essential Configuration:

.env

# Domain Configuration
BASE_DOMAIN=yourdomain.com
CF_Token=your_cloudflare_api_token
ACME_EMAIL=admin@yourdomain.com

# User IDs (usually 1000 for the first user)
UID=1000
GID=1000

# Service Credentials (generate secure values)
DNS_ADMIN_PASSWORD=secure_password
GRAFANA_ADMIN_PASSWORD=secure_password

See the Configuration Guide for a full list of available variables.

Step 3: Deployment¶

The deployment process is split into bootstrapping the nodes and then deploying the cluster.

Bootstrap Nodes: Prepares all nodes with Docker, dependencies, and security hardening.
```
task ansible:bootstrap
```
Initialize Cluster & Deploy: Initializes Docker Swarm and deploys all infrastructure and application stacks.
```
task ansible:deploy
```

What Happens During Deployment?¶

Docker Swarm: A multi-node cluster is initialized and joined.
Networking: An overlay network (traefik-public) is created for service communication.
Core Infrastructure:
- Traefik: Reverse proxy with automatic SSL (Let's Encrypt).
- Technitium DNS: Internal DNS resolution.
- Monitoring: Prometheus, Grafana, Loki, and Promtail.
Applications: All services in stacks/apps/ are deployed according to their configurations.
DNS Registration: A/CNAME records are automatically added for all services.

Step 4: Verification¶

Check that all services are running correctly:

Check Stack Status:
```
docker stack ls
```
Check Individual Services:
```
docker service ls
```

View Logs (example for Traefik):

docker service logs reverse-proxy_traefik --tail 50 -f

Step 5: Access Your Services¶

Once deployment completes, access your services via their configured domains:

Homepage Dashboard: https://homepage.yourdomain.com
Traefik Dashboard: https://traefik.yourdomain.com
Grafana Monitoring: https://grafana.yourdomain.com
DNS Server: http://dns.yourdomain.com:5380

Management Commands¶

Service Operations¶

# Deploy or update a specific service
task ansible:deploy:service -- -e "stack_name=homeassistant"

# Tear down a specific service (preserves volumes)
task ansible:teardown:service -- -e "stack_name=homeassistant"

# Tear down a service and DELETE its data (Destructive)
task ansible:teardown:service -- -e "stack_name=homeassistant remove_volumes=true"

Cluster Operations¶

# Check cluster health
task ansible:cluster:status

# Full cluster teardown (preserves volumes)
task ansible:teardown

# Full cluster teardown including volumes (Destructive)
task ansible:teardown:with-volumes

Troubleshooting¶

??? question "Docker permission denied?" Ensure your user is in the docker group:

sudo usermod -aG docker $USER
newgrp docker

??? question "Services stuck in 'Pending'?" Check service status for placement constraints or resource issues:

docker service ps <service_name>

??? question "SSL certificate issues?" Verify your Cloudflare token and check Traefik logs:

docker service logs reverse-proxy_traefik | grep -i acme

For more detailed issues, see the Troubleshooting Guide.