Quick Start

Quick Start Guide¶

Goal

Deploy your first self-hosted services in under 10 minutes!

Prerequisites Check¶

Before we begin, make sure you have:

[x] Docker Engine 24.0+ with Docker Compose v2
[x] Ansible installed on your control machine
[x] Domain name with Cloudflare DNS management
[x] Cloudflare API credentials (Global API Key or API Token)
[x] Linux/Unix environment (Ubuntu 20.04+, Debian 11+, or similar)
[x] Network storage (optional - for persistent data via SMB/CIFS)

Don't have these yet?

Check out our detailed installation guide for step-by-step setup instructions.

🚀 Quick Deployment¶

Step 1: Clone and Setup¶

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

# Copy environment template
cp .env.example .env

Step 2: Configure Your Environment¶

Edit your .env file with your domain and credentials:

nano .env

Essential Configuration:

.env

# Your domain
BASE_DOMAIN=yourdomain.com

# Cloudflare API credentials (choose one method)
CF_Token=your_cloudflare_api_token          # ✅ Recommended method
# OR
CF_Email=your@email.com                     # Legacy method
CF_Key=your_global_api_key                  # Legacy method

# Email for SSL certificates
ACME_EMAIL=your-email@example.com

# Network storage (if you have NAS/SMB shares)
NAS_SERVER=nas.yourdomain.com
SMB_USERNAME=your_smb_username
SMB_PASSWORD=your_smb_password

Getting Cloudflare API Token

Go to Cloudflare API Tokens
Click "Create Token"
Use "Custom token" template
Add permissions: Zone:DNS:Edit and Zone:Zone:Read
Include your domain in "Zone Resources"

Step 3: See Available Services¶

Check what services are available to deploy:

ls stacks/apps/

Expected output:

actual_server  cryptpad      downloads     emby          homeassistant
homepage       librechat     photoprism    prowlarr      radarr
sonarr

All these services have Docker Compose files and will be deployed automatically!

Step 4: Configure Multi-Node Setup¶

Create and edit the Ansible inventory file:

nano ansible/inventory/02-hosts.yml

For single-machine setup, you can just configure the manager host. For a multi-node setup, add workers.

Step 5: Deploy Everything¶

Deploy all available services:

# Install Ansible and dependencies
task ansible:install

# Bootstrap all nodes
task ansible:bootstrap

# Initialize the Docker Swarm cluster
task ansible:cluster:init

# Deploy all services
task ansible:deploy:full

Or deploy specific services only:

# Deploy only homepage and actual budget
task ansible:deploy:stack -- -e "stack_name=homepage"
task ansible:deploy:stack -- -e "stack_name=actual_server"

Step 6: Access Your Services¶

Once deployment completes, access your services at:

Homepage Dashboard: https://homepage.yourdomain.com
Actual Budget: https://actual.yourdomain.com
Home Assistant: https://homeassistant.yourdomain.com
And many more...

The Homepage dashboard will show all your deployed services!

🎉 Congratulations!

You now have a complete self-hosted infrastructure running on Docker Swarm with automatic SSL certificates!

What's Next?¶

Service Management

Learn how to add, remove, and configure services
SSL & Domains - Automatic SSL via Traefik + Cloudflare

Configure automatic SSL certificates and custom domains
Volume Management - Network storage with NAS/OMV

Set up persistent storage and backups with SMB/CIFS
Multi-Node Setup - Docker Swarm cluster configuration

Scale across multiple machines with Docker Swarm

Essential Commands Reference¶

# Deployment Commands
task ansible:deploy:full                     # Deploy all services
task ansible:deploy:stack -- -e "stack_name=service1"  # Deploy a specific service

# Cluster Management
task ansible:cluster:init                   # Initialize Docker Swarm
task ansible:cluster:status                 # Check cluster status
task ansible:teardown:full                  # Destroy entire cluster (including data)

# Check Available Services
ls stacks/apps/                                # See all available services

# Docker Swarm Management
docker stack ls                                # List deployed stacks
docker stack services <stack-name>            # Show services in a stack
docker stack ps <stack-name>                  # Show tasks/containers for a stack

# Monitoring
task ansible:cluster:status                     # Cluster health check

Troubleshooting Quick Fixes¶

??? question "Service won't start or keeps restarting?"

Check the service logs:
```bash
# Find the service name first
docker stack services <stack-name>

# Check specific service logs
docker service logs <service-name> --tail 50 --follow
```

??? question "Domain not resolving?"

Verify your DNS settings:
```bash
# Check if domain points to your server
dig yourdomain.com

# Test specific service subdomain
dig homepage.yourdomain.com
```

??? question "SSL certificate issues?"

Check Traefik and certificate status:
```bash
# Check reverse-proxy stack logs
docker stack services reverse-proxy
docker service logs reverse-proxy_traefik --tail 50

# Check if certificates are being generated
docker exec -it $(docker ps -q -f name=reverse-proxy_traefik) ls -la /letsencrypt/
```

??? question "Volume/storage issues?"

Check SMB/CIFS connection:
```bash
# Test SMB connection manually
smbclient -L //${NAS_SERVER} -U ${SMB_USERNAME}

# Check volume mount status
docker volume ls | grep <service-name>
```

Need more help? Check the First Deployment guide for detailed troubleshooting.