homelab/docs/getting-started.md

Getting Started with Homelab

This guide will walk you through setting up your homelab from scratch.

Prerequisites

Hardware Requirements

• Server/VM: Linux server with Docker support
• CPU: 2+ cores recommended
• RAM: 8GB minimum, 16GB+ recommended
• Storage: 100GB+ for Docker containers and config
• Optional GPU: NVIDIA GPU for hardware transcoding (Jellyfin, Immich)

Software Requirements

• Operating System: Ubuntu 22.04 or similar Linux distribution
• Docker: Version 24.0+
• Docker Compose: Version 2.20+
• Git: For cloning the repository
• Domain Names: *.fig.systems and *.edfig.dev (or your domains)

Network Requirements

• Ports: 80 and 443 accessible from internet (for Let's Encrypt)
• DNS: Ability to create A records for your domains
• Static IP: Recommended for your homelab server

Step 1: Prepare Your Server

Install Docker and Docker Compose

# Update package index
sudo apt update

# Install dependencies
sudo apt install -y ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Set up the repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to docker group (logout and login after this)
sudo usermod -aG docker $USER

# Verify installation
docker --version
docker compose version

Create Media Directory Structure

# Create media folders
sudo mkdir -p /media/{audiobooks,books,comics,complete,downloads,homemovies,incomplete,movies,music,photos,tv}

# Set ownership (replace with your username)
sudo chown -R $(whoami):$(whoami) /media

# Verify structure
tree -L 1 /media

Step 2: Clone the Repository

# Clone the repository
cd ~
git clone https://github.com/efigueroa/homelab.git
cd homelab

# Checkout the main branch
git checkout main  # or your target branch

Step 3: Configure DNS

You need to point your domains to your server's IP address.

Option 1: Wildcard DNS (Recommended)

Add these A records to your DNS provider:

*.fig.systems    A    YOUR_SERVER_IP
*.edfig.dev      A    YOUR_SERVER_IP

Option 2: Individual Records

Create A records for each service:

traefik.fig.systems     A    YOUR_SERVER_IP
lldap.fig.systems       A    YOUR_SERVER_IP
auth.fig.systems        A    YOUR_SERVER_IP
home.fig.systems        A    YOUR_SERVER_IP
backup.fig.systems      A    YOUR_SERVER_IP
flix.fig.systems        A    YOUR_SERVER_IP
photos.fig.systems      A    YOUR_SERVER_IP
# ... and so on for all services

Verify DNS

Wait a few minutes for DNS propagation, then verify:

# Test DNS resolution
dig traefik.fig.systems +short
dig lldap.fig.systems +short

# Should return your server IP

Step 4: Configure Environment Variables

Each service needs its environment variables configured with secure values.

Generate Secure Secrets

Use these commands to generate secure values:

# For JWT secrets and session secrets (64 characters)
openssl rand -hex 32

# For passwords (32 alphanumeric characters)
openssl rand -base64 32 | tr -d /=+ | cut -c1-32

# For API keys (32 characters)
openssl rand -hex 16

Update Core Services

LLDAP (compose/core/lldap/.env):

cd compose/core/lldap
nano .env

# Update these values:
LLDAP_LDAP_USER_PASS=<your-strong-password>
LLDAP_JWT_SECRET=<output-from-openssl-rand-hex-32>

Tinyauth (compose/core/tinyauth/.env):

cd ../tinyauth
nano .env

# Update these values (LDAP_BIND_PASSWORD must match LLDAP_LDAP_USER_PASS):
LDAP_BIND_PASSWORD=<same-as-LLDAP_LDAP_USER_PASS>
SESSION_SECRET=<output-from-openssl-rand-hex-32>

Immich (compose/media/frontend/immich/.env):

cd ../../media/frontend/immich
nano .env

# Update:
DB_PASSWORD=<output-from-openssl-rand-base64>

Update All Other Services

Go through each service's .env file and replace all changeme_* values:

# Find all files that need updating
grep -r "changeme_" ~/homelab/compose

# Or update them individually
cd ~/homelab/compose/services/linkwarden
nano .env  # Update NEXTAUTH_SECRET, POSTGRES_PASSWORD, MEILI_MASTER_KEY

cd ../vikunja
nano .env  # Update VIKUNJA_DATABASE_PASSWORD, VIKUNJA_SERVICE_JWTSECRET, POSTGRES_PASSWORD

💡 Tip: Keep your secrets in a password manager!

See Secrets Management Guide for detailed instructions.

Step 5: Create Docker Network

# Create the external homelab network
docker network create homelab

# Verify it was created
docker network ls | grep homelab

Step 6: Deploy Services

Deploy services in order, starting with core infrastructure:

Deploy Core Infrastructure

cd ~/homelab

# Deploy Traefik (reverse proxy)
cd compose/core/traefik
docker compose up -d

# Check logs to ensure it starts successfully
docker compose logs -f

# Wait for "Server configuration reloaded" message, then Ctrl+C

# Deploy LLDAP (user directory)
cd ../lldap
docker compose up -d
docker compose logs -f

# Access: https://lldap.fig.systems
# Default login: admin / <your LLDAP_LDAP_USER_PASS>

# Deploy Tinyauth (SSO)
cd ../tinyauth
docker compose up -d
docker compose logs -f

# Access: https://auth.fig.systems

Create LLDAP Users

Before deploying other services, create your user in LLDAP:

1. Go to https://lldap.fig.systems
2. Login with admin credentials
3. Create your user:
   • Username: edfig (or your choice)
   • Email: admin@edfig.dev
   • Password: strong password
   • Add to lldap_admin group

Deploy Media Services

cd ~/homelab/compose/media/frontend

# Jellyfin
cd jellyfin
docker compose up -d
# Access: https://flix.fig.systems

# Immich
cd ../immich
docker compose up -d
# Access: https://photos.fig.systems

# Jellyseerr
cd ../jellyseer
docker compose up -d
# Access: https://requests.fig.systems

# Media automation
cd ~/homelab/compose/media/automation

cd sonarr && docker compose up -d && cd ..
cd radarr && docker compose up -d && cd ..
cd sabnzbd && docker compose up -d && cd ..
cd qbittorrent && docker compose up -d && cd ..

Deploy Utility Services

cd ~/homelab/compose/services

# Dashboard (start with this - it shows all your services!)
cd homarr && docker compose up -d && cd ..
# Access: https://home.fig.systems

# Backup manager
cd backrest && docker compose up -d && cd ..
# Access: https://backup.fig.systems

# Other services
cd linkwarden && docker compose up -d && cd ..
cd vikunja && docker compose up -d && cd ..
cd lubelogger && docker compose up -d && cd ..
cd calibre-web && docker compose up -d && cd ..
cd booklore && docker compose up -d && cd ..
cd FreshRSS && docker compose up -d && cd ..
cd rsshub && docker compose up -d && cd ..
cd microbin && docker compose up -d && cd ..
cd filebrowser && docker compose up -d && cd ..

Quick Deploy All (Alternative)

If you've configured everything and want to deploy all at once:

cd ~/homelab

# Create a deployment script
cat > deploy-all.sh << 'SCRIPT'
#!/bin/bash
set -e

echo "Deploying homelab services..."

# Core
echo "==> Core Infrastructure"
cd compose/core/traefik && docker compose up -d && cd ../../..
sleep 5
cd compose/core/lldap && docker compose up -d && cd ../../..
sleep 5
cd compose/core/tinyauth && docker compose up -d && cd ../../..

# Media
echo "==> Media Services"
cd compose/media/frontend/immich && docker compose up -d && cd ../../../..
cd compose/media/frontend/jellyfin && docker compose up -d && cd ../../../..
cd compose/media/frontend/jellyseer && docker compose up -d && cd ../../../..
cd compose/media/automation/sonarr && docker compose up -d && cd ../../../..
cd compose/media/automation/radarr && docker compose up -d && cd ../../../..
cd compose/media/automation/sabnzbd && docker compose up -d && cd ../../../..
cd compose/media/automation/qbittorrent && docker compose up -d && cd ../../../..

# Utility
echo "==> Utility Services"
cd compose/services/homarr && docker compose up -d && cd ../..
cd compose/services/backrest && docker compose up -d && cd ../..
cd compose/services/linkwarden && docker compose up -d && cd ../..
cd compose/services/vikunja && docker compose up -d && cd ../..
cd compose/services/lubelogger && docker compose up -d && cd ../..
cd compose/services/calibre-web && docker compose up -d && cd ../..
cd compose/services/booklore && docker compose up -d && cd ../..
cd compose/services/FreshRSS && docker compose up -d && cd ../..
cd compose/services/rsshub && docker compose up -d && cd ../..
cd compose/services/microbin && docker compose up -d && cd ../..
cd compose/services/filebrowser && docker compose up -d && cd ../..

echo "==> Deployment Complete!"
echo "Access your dashboard at: https://home.fig.systems"
SCRIPT

chmod +x deploy-all.sh
./deploy-all.sh

Step 7: Verify Deployment

Check All Containers Are Running

# List all containers
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Check for any stopped containers
docker ps -a --filter "status=exited"

Verify SSL Certificates

# Test SSL certificate
curl -I https://home.fig.systems

# Should show HTTP/2 200 and valid SSL cert

Access Services

Visit your dashboard: https://home.fig.systems

This should show all your services with their status!

Test SSO

1. Go to any SSO-protected service (e.g., https://tasks.fig.systems)
2. You should be redirected to https://auth.fig.systems
3. Login with your LLDAP credentials
4. You should be redirected back to the service

Step 8: Initial Service Configuration

Jellyfin Setup

1. Go to https://flix.fig.systems
2. Select language and create admin account
3. Add media libraries:
   • Movies: /media/movies
   • TV Shows: /media/tv
   • Music: /media/music
   • Photos: /media/photos

Immich Setup

1. Go to https://photos.fig.systems
2. Create admin account
3. Upload some photos to test
4. Configure storage in Settings

Sonarr/Radarr Setup

1. Go to https://sonarr.fig.systems and https://radarr.fig.systems
2. Complete initial setup wizard
3. Add indexers (for finding content)
4. Add download clients:
   • SABnzbd: http://sabnzbd:8080
   • qBittorrent: http://qbittorrent:8080
5. Configure root folders:
   • Sonarr: /media/tv
   • Radarr: /media/movies

Jellyseerr Setup

1. Go to https://requests.fig.systems
2. Sign in with Jellyfin
3. Connect to Sonarr and Radarr
4. Configure user permissions

Backrest Setup

1. Go to https://backup.fig.systems
2. Add Backblaze B2 repository (see Backup Guide)
3. Create backup plan for Immich photos
4. Schedule automated backups

Step 9: Optional Configurations

Enable GPU Acceleration

If you have an NVIDIA GPU, see GPU Setup Guide.

Configure Backups

See Backup Operations Guide.

Add More Services

See Adding Services Guide.

Next Steps

• ✅ Set up automated backups
• ✅ Configure monitoring
• ✅ Review security settings
• ✅ Enable GPU acceleration (optional)
• ✅ Configure media automation

Troubleshooting

If you encounter issues during setup, see:

• Common Issues
• FAQ
• Debugging Guide

Quick Command Reference

# View all running containers
docker ps

# View logs for a service
cd compose/path/to/service
docker compose logs -f

# Restart a service
docker compose restart

# Stop a service
docker compose down

# Update and restart a service
docker compose pull
docker compose up -d

# View resource usage
docker stats

Getting Help

• Check the FAQ
• Review service-specific guides in docs/services/
• Check container logs for errors
• Verify DNS and SSL certificates

Welcome to your homelab! 🎉