kitestacks-homelab/homelab-mastery/build-guide/with-ai/03-docker-setup.md

Step 3 — Installing Docker

Track: With AI (Beginner)
Time for this step: 30–60 minutes (on both your home computer and your VPS)

Docker is the technology that runs all your services. Think of it like a machine that can run many small, isolated programs at the same time — each program thinks it is the only one on the computer, even though they are all sharing the same hardware.

Each program is called a container. You will have about 15 containers running.

---

What Is Docker? (Plain English)

Imagine you want to run fifteen different apps on your computer. If you installed them all directly, they might conflict — one app needs Python version 3.9, another needs 3.11, and they fight over which one to use. Docker solves this by giving each app its own little bubble where it has exactly what it needs, completely separate from everything else.

A container is one of those bubbles. A Docker image is the recipe for making a bubble. Docker Compose is a tool that lets you describe multiple containers in one file and start them all with one command.

Ask your AI: "Can you explain Docker containers vs Docker images using a simple analogy?"

---

Installing Docker on Your Home Computer (monk)

Run these commands one at a time. Before each one, ask your AI what it does.

# Install required packages
sudo apt install -y ca-certificates curl

# Add Docker's official GPG key (proves the software is authentic)
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add Docker's package source
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Update package list and install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Now let Docker start automatically when your computer boots:

sudo systemctl enable docker
sudo systemctl start docker

Add yourself to the Docker group so you do not need sudo every time:

sudo usermod -aG docker $USER

Log out and log back in (or reboot) for this change to take effect.

Test that Docker is installed:

docker --version
docker compose version

You should see version numbers printed. If you see errors, ask your AI to help.

---

Installing Docker on Your Cloud VPS (kscloud1)

SSH into your VPS and run the exact same commands as above. The process is identical.

ssh root@YOUR_VPS_IP

Then run all the same installation commands.

---

Your First Container — Cloudflared (Tunnel Connector)

The first container you will run is cloudflared — this is what creates the tunnel between your computer and Cloudflare. Without this, nothing else can be reached from the internet.

On your home computer, create a folder for it:

mkdir -p ~/kitestacks-live/docker/cloudflared
cd ~/kitestacks-live/docker/cloudflared

Create a file called .env that holds your tunnel token:

nano .env

Inside the file, type:

TUNNEL_TOKEN=paste-your-token-here

Replace paste-your-token-here with the token you saved from Step 2. Press Ctrl+X, then Y, then Enter to save.

Now create the docker-compose.yml file:

nano docker-compose.yml

Paste this content:

services:
  cloudflared:
    image: cloudflare/cloudflared:latest
    container_name: cloudflared
    restart: unless-stopped
    command: tunnel --no-autoupdate run
    environment:
      - TUNNEL_TOKEN=${TUNNEL_TOKEN:?set TUNNEL_TOKEN in .env}
    networks:
      - default
      - kitestacks

networks:
  kitestacks:
    external: true

Save and close the file. Then start it:

docker compose up -d

Check that it is running:

docker ps

You should see cloudflared in the list with a status of Up.

Check the logs to confirm it connected:

docker logs cloudflared

You should see something like "Connection established" or "Registered tunnel connection".

Ask your AI: "What does restart: unless-stopped mean in a Docker Compose file?"

---

Run Cloudflared on Your VPS Too

SSH into your VPS and do the exact same thing. Use the same tunnel token — Cloudflare will register this as a second connector for the same tunnel. If your home computer goes offline, the VPS will keep serving traffic.

mkdir -p /opt/kitestacks/docker/cloudflared
cd /opt/kitestacks/docker/cloudflared

Create the same .env and docker-compose.yml files, then:

docker compose up -d
docker logs cloudflared

---

Checkpoint

Before moving to Step 4:

• Docker is installed on your home computer
• Docker is installed on your VPS
• docker ps shows cloudflared running on both machines
• docker logs cloudflared shows successful connection on both

Go to your Cloudflare Tunnel dashboard. Under your tunnel, you should now see 2 connectors listed — one from your home computer and one from your VPS. If you only see one, wait a few minutes and refresh.

---

Next: Step 4 — Core Services