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.

```bash
# 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:
```bash
sudo systemctl enable docker
sudo systemctl start docker
```

Add yourself to the Docker group so you do not need `sudo` every time:
```bash
sudo usermod -aG docker $USER
```

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

Test that Docker is installed:
```bash
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.

```bash
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:
```bash
mkdir -p ~/kitestacks-live/docker/cloudflared
cd ~/kitestacks-live/docker/cloudflared
```

Create a file called `.env` that holds your tunnel token:
```bash
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:
```bash
nano docker-compose.yml
```

Paste this content:
```yaml
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:
```bash
docker compose up -d
```

Check that it is running:
```bash
docker ps
```

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

Check the logs to confirm it connected:
```bash
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.

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

Create the same `.env` and `docker-compose.yml` files, then:
```bash
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](04-core-services.md)