How to Set Up Docker in Your Homelab: A Beginner's Guide

So you've got your homelab hardware sorted — maybe a Proxmox cluster with LXC containers, a TrueNAS box, or just an old desktop repurposed as a server. Now you want to run services without the headache of managing dependencies, conflicting versions, and system-wide installations. That's where Docker comes in.

🏷️

What You'll Need (prerequisites)• Ubuntu 22.04+ or Debian-based system
• At least 2GB RAM (4GB recommended)
• 10GB free disk space
• Sudo access

This guide walks you through setting up Docker on a typical homelab server, including specific considerations for LXC containers. By the end, you'll have a working Docker installation and understand the core concepts to build from.

Prerequisites: LXC-Specific Setup

If you're running Docker inside an LXC container (common in Proxmox homelabs), you need to enable nesting and keyctl support on the host first.

💡

Skip this section if you're installing Docker directly on bare metal or a VM.

On your Proxmox host, run:

📋

# Stop the LXC container pct stop <container-id> # Enable nesting and keyctl pct set <container-id> -features nesting=1,keyctl=1 # Start the container pct start <container-id>

⚠️

Without these settings, Docker will fail to start with errors about cgroups or AppArmor.

Verify nesting is enabled inside the LXC with:

📋

cat /proc/self/status | grep -i unshare

You should see Unshare_ns entries. If not, revisit the host configuration.

Why Docker for Homelabs?

Before we dive in, here's why Docker is a homelab game-changer:

• Isolation: Each service runs in its own container with its own dependencies

• Portability: Move containers between hosts without reconfiguration

• Version control: Pin specific versions and roll back easily

• Resource efficiency: Containers share the host kernel, using less overhead than VMs

• Community images: Thousands of pre-built images for common homelab services

Step 1: Install Docker Engine

First, let's get Docker installed on your host system. We'll use the official Docker repository for the latest stable version.

📋

# Update package index sudo apt update # Install prerequisites sudo apt install -y ca-certificates curl gnupg # Create keyring directory sudo install -m 0755 -d /etc/apt/keyrings # Add Docker's GPG key curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /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 $(. /etc/os-release && echo "$VERSION_CODENAME") 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

Step 2: Verify Docker Installation

Before proceeding, confirm Docker is working correctly:

📋

# Check Docker version docker --version # Check Docker Compose version (v2) docker compose version # Run the hello-world test container docker run hello-world

✅

The hello-world image downloads a small container that prints a success message. If you see "Hello from Docker!", your installation is working.

Step 3: Configure Docker for Non-Root Usage

Running Docker commands as root is tedious and error-prone. Add your user to the docker group:

📋

# Create docker group and add your user sudo groupadd docker sudo usermod -aG docker $USER # Apply group changes (or log out and back in) newgrp docker # Test without sudo docker run hello-world

Step 4: Understand Docker Compose

For homelabs, you'll rarely run single containers. You'll want multiple services working together — a web server, database, and maybe a reverse proxy. Docker Compose lets you define and manage multi-container applications with a single YAML file.

💡

Docker Compose v2 uses docker compose (with a space) as a Docker CLI plugin. The old v1 used docker-compose (with a hyphen).

Basic Docker Compose Structure

Here's a typical structure for a homelab service:

📋

version: '3.8' services: myservice: image: linuxserver/myservice:latest container_name: myservice environment: - PUID=1000 - PGID=1000 - TZ=Europe/London volumes: - ./config:/config - ./data:/data ports: - 8080:80 restart: unless-stopped networks: - homelab networks: homelab: external: true

Key Points:

• image: The container image to pull

• volumes: Persist data outside the container

• ports: Map host ports to container ports

• restart: Auto-restart after reboot or crashes

• environment: Pass configuration variables

Step 5: Deploy Your First Service

Let's deploy a practical example: Uptime Kuma, a popular self-hosted monitoring tool.

📋

# Create project directory mkdir -p ~/docker/uptime-kuma cd ~/docker/uptime-kuma # Create docker-compose.yml cat > docker-compose.yml << 'EOF' version: '3.8' services: uptime-kuma: image: louislam/uptime-kuma:1 container_name: uptime-kuma volumes: - ./data:/app/data ports: - 3001:3001 restart: unless-stopped EOF # Start the service docker compose up -d # Check status docker compose ps docker compose logs -f

💡

Access Uptime Kuma at http://your-server-ip:3001 and complete the initial setup.

Step 6: Organise Your Homelab

As you add more services, stay organised:

📋

~/docker/ ├── uptime-kuma/ │ ├── docker-compose.yml │ └── data/ ├── nginx-proxy-manager/ │ ├── docker-compose.yml │ ├── data/ │ └── letsencrypt/ ├── pi-hole/ │ ├── docker-compose.yml │ └── data/ └── .env # Shared environment variables (DO NOT commit to git!)

⚠️

Never commit .env files with passwords to version control. Add them to .gitignore immediately.

Create a Shared Network

Create a shared network for inter-container communication:

📋

docker network create homelab

Step 7: Using Traefik as a Reverse Proxy

For a more advanced setup, Traefik provides automatic SSL and routing:

📋

version: '3.8' services: traefik: image: traefik:v2.10 container_name: traefik command: - "--api.dashboard=true" - "--providers.docker=true" - "--entrypoints.web.address=:80" - "--entrypoints.websecure.address=:443" ports: - "80:80" - "443:443" - "8080:8080" volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - ./config/traefik.yml:/etc/traefik/traefik.yml:ro restart: unless-stopped networks: - homelab networks: homelab: external: true

⚠️

The Traefik dashboard is exposed on port 8080 by default — do not expose this to the internet without authentication!

Step 8: Essential Maintenance Commands

Keep your Docker environment healthy:

📋

# View running containers docker ps # View all containers (including stopped) docker ps -a # Check container logs docker logs -f container_name # Restart a container docker restart container_name # Stop and remove a container docker compose down # Update an image docker compose pull docker compose up -d # Clean up unused resources docker system prune -a

Backup Your Docker Services

Container data lives in volumes — back these up regularly:

📋

# Create a backup of a service's data directory tar -czf uptime-kuma-backup-$(date +%F).tar.gz ~/docker/uptime-kuma/data/ # Store on remote backup server rsync -avz ~/docker/backups/ user@backup-server:/backups/docker/ # Automate with cron 0 2 * * * tar -czf /backups/docker/backup-$(date +\%F).tar.gz ~/docker/*/data/

✅

Test your restores periodically — a backup you can't restore isn't a backup.

Troubleshooting: LXC-Specific Errors

Running Docker in LXC? Here are common issues:

Permission Denied When Starting Docker

📋

# Check if nesting is enabled cat /proc/self/status | grep -i unshare # If no output, enable on Proxmox host: pct set <container-id> -features nesting=1,keyctl=1 pct restart <container-id>

Cgroup Namespace Not Supported

This means your LXC doesn't have the right features. On the Proxmox host:

📋

pct set <container-id> -features nesting=1,keyctl=1

AppArmor Profile Not Found

Add this to your LXC config on the host:

📋

lxc.apparmor.profile: unconfined lxc.apparmor.allow_nesting: 1

Docker0 Bridge Not Created

📋

sudo systemctl restart docker

Next Steps

Now you've got Docker running, here are common homelab services to explore:

• Nginx Proxy Manager: Reverse proxy with Let's Encrypt SSL

• Pi-hole or AdGuard Home: Network-wide ad blocking

• Jellyfin or Plex: Media streaming

• Nextcloud: Self-hosted file sync and share

• Home Assistant: Home automation hub

• Vikunja: Task and project management

Each follows the same pattern: pull an image, configure volumes and environment variables, and deploy with Docker Compose.

General Troubleshooting Tips

• Permission denied errors: Check PUID/PGID match your user (id $USER)

• Port already in use: Change the host port in docker-compose.yml

• Container won't start: Check logs with docker logs container_name

• Can't access service: Verify firewall rules and port mappings

• Docker commands fail without sudo: Run newgrp docker or log out/in

✅

Happy homelabbing! Drop a comment if you run into issues or want to share your setup.

How to Set Up Docker in Your Homelab: A Beginner's Guide

Table of Contents