Quick Start Guide¶

Get your secure homelab running in minutes!

⚡ Fast Track (5 Minutes)¶

1. Initial Setup¶

# Clone and initialize
git clone <your-repo>
cd homelab
./scripts/init-homelab.sh

2. Generate Secrets¶

# Run the secret generator
./scripts/generate-secrets.sh

# Choose option 7 for complete service set
# Save the output securely!

3. Configure Your First Service (Authelia)¶

cd Authelia/Authelia

# Edit .env with generated secrets
vim .env
# Replace all CHANGE_ME values

# Update domain
sed -i 's/smartmur.lab/smartmur.lab/g' .env

# Start service
docker-compose up -d

# Check it's running
docker-compose ps
docker-compose logs -f

4. Access Your Service¶

Visit: https://auth.smartmur.lab

🎯 Essential Services Setup¶

Traefik (Reverse Proxy) - Required First¶

cd Traefikv3
cp .env.example .env

# Edit these values:
# DOMAIN=smartmur.lab
# CF_API_TOKEN=your_cloudflare_token
# ACME_EMAIL=your@email.com

# Create acme.json
touch config/acme.json && chmod 600 config/acme.json

docker-compose up -d

Pi-hole (DNS & Ad Blocking)¶

cd Pihole
cp .env.example .env
# Set PIHOLE_PASSWORD
docker-compose up -d

Watchtower (Auto Updates)¶

cd Watchtower
cp .env.example .env
# Set WATCHTOWER_HTTP_API_TOKEN
docker-compose up -d

🔑 Secret Management Cheat Sheet¶

Generate Random Secret¶

openssl rand -base64 32

Generate Password Hash (Authelia)¶

docker run authelia/authelia:latest authelia crypto hash generate argon2 --password 'yourpassword'

Generate htpasswd (Traefik Dashboard)¶

echo $(htpasswd -nb admin yourpassword) | sed -e s/\\$/\\$\\$/g

📁 Repository Structure¶

homelab/
├── scripts/              # Helper scripts
│   ├── init-homelab.sh   # Initial setup
│   ├── generate-secrets.sh
│   ├── validate-secrets.sh
│   └── rotate-secrets.sh
├── Authelia/            # Authentication
├── Traefik/            # Reverse proxy
├── Watchtower/         # Auto-updates
├── README.md           # Main documentation
├── SECURITY.md         # Security guide
├── DEPLOYMENT.md       # Deployment guide
└── MIGRATION-GUIDE.md  # Migration guide

✅ Pre-Flight Checklist¶

Before deploying: - [ ] Docker & Docker Compose installed - [ ] Domain name configured (or using local DNS) - [ ] Cloudflare account setup (for SSL) - [ ] Pre-commit hooks installed: pre-commit install - [ ] All .env files created from .example files - [ ] All CHANGE_ME values replaced with real secrets - [ ] Secrets backed up securely (encrypted)

🔒 Security Checklist¶

After deployment: - [ ] Changed all default passwords - [ ] Enabled 2FA in Authelia - [ ] SSL certificates working (HTTPS) - [ ] Firewall configured (ports 80, 443, 22) - [ ] Secrets not committed to git (git status --ignored) - [ ] Pre-commit hooks active and testing - [ ] Backup strategy in place

🆘 Quick Troubleshooting¶

Service won't start¶

docker-compose logs -f
docker-compose config  # Validate syntax

Can't access via domain¶

# Check DNS
nslookup smartmur.lab

# Check Traefik
cd Traefikv3
docker-compose logs traefik

Forgot password¶

# Authelia: Generate new hash
docker run authelia/authelia:latest authelia crypto hash generate argon2
# Update users_database.yml

Check secrets not exposed¶

./scripts/validate-secrets.sh

📚 Next Steps¶

Read the full docs:
Home - Overview
Security - Security practices
Deployment - Detailed deployment
Add more services:
Browse service directories
Copy .env.example to .env
Configure and deploy
Set up monitoring:
Deploy Uptime Kuma
Configure Grafana (optional)
Schedule maintenance:
Secret rotation (90 days)
System updates (weekly)
Backup verification (monthly)

💡 Pro Tips¶

Start small: Deploy core services first (Traefik, Authelia, Pi-hole)
Test locally: Use /etc/hosts before DNS changes
Keep backups: Encrypt and store .env files safely
Document changes: Keep notes on customizations
Use labels: Control Watchtower per container

🔗 Useful Commands¶

# View all running containers
docker ps

# View all containers (including stopped)
docker ps -a

# Check disk usage
docker system df

# Clean up unused resources
docker system prune -a

# Follow logs for all services
docker-compose logs -f

# Restart a service
docker-compose restart service-name

# Update all images
docker-compose pull
docker-compose up -d

📞 Get Help¶

Check service README: cat ServiceName/README.md
Validate setup: ./scripts/validate-secrets.sh
View logs: docker-compose logs -f
Open an issue (never include real secrets!)

Remember: Security first! Never commit secrets to git. 🔐