Day 0: The Training Ground
Goal: Create the lab VM, install Docker and decK, fetch the companion code and start the backend that Kong publishes from Day 1 on. · Duration: approx. 45 min · Prerequisite: none
Briefing
- You work in the Ubuntu 24.04 VM
kong, as userubuntuin~/kong-lab. You connect from your laptop over SSH. - The backend is a Compose project:
notes-api, Postgres andecho, a service that mirrors every request back, headers included. - The backend publishes no port. From Day 1 on, Kong is the only door.
- All containers are attached to the Docker network
lab.
Laptop VM kong
┌─────────┐ ssh ┌──────────────────────────────────────────────┐
│ Browser │───────►│ ~/kong-lab/ setup/ code/ tagNN/ │
│ ssh │ │ Net lab: notes-api :8080 db :5432 echo :8080│
└─────────┘ │ (no port exposed) │
└──────────────────────────────────────────────┘
Drill 1: The Lab VM
On the laptop (Multipass from multipass.run). The second
command stores your SSH key in the VM so that you can build tunnels from
Day 1 on:
multipass launch 24.04 --name kong --cpus 2 --memory 4G --disk 30G
multipass exec kong -- bash -c "echo '$(cat ~/.ssh/id_ed25519.pub)' \
>> ~/.ssh/authorized_keys"
multipass info kong | grep IPv4Expected (shortened, your IP will differ):
Launched: kong
IPv4: 192.168.64.7
Note the IP as KONG_IP and log in:
export KONG_IP=192.168.64.7
ssh ubuntu@$KONG_IPFrom here on, everything runs in the VM:
grep PRETTY_NAME /etc/os-release
uname -mExpected:
PRETTY_NAME="Ubuntu 24.04.5 LTS"
x86_64
On a Mac with Apple Silicon this shows aarch64. Docker,
Kong and decK are available for both architectures; the commands in this
book pick the right one themselves.
Save your progress? Sign up for free
Drill 2: Install Docker
Docker CE comes from Docker’s package repository, not from Ubuntu:
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-o /etc/apt/keyrings/docker.asc
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
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin jq
sudo usermod -aG docker ubuntuThe docker group only takes effect after a new login.
Log out (exit), log back in
(ssh ubuntu@$KONG_IP) and check:
docker --version
docker compose version
docker run --rm hello-world | grep HelloExpected:
Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1
Hello from Docker!
Security: Anyone in the
dockergroup effectively has root privileges on the VM. In the lab that is fine, on a shared server it is not.
Save your progress? Sign up for free
Drill 3: Install decK
decK is Kong’s tool for declarative configuration (Day 3). You install a release binary in four steps: download, verify the checksum, unpack, install.
mkdir -p /tmp/dl && cd /tmp/dl
V=1.69.0
ARCH=$(dpkg --print-architecture)
B=https://github.com/Kong/deck/releases/download/v$V
curl -fsSLO "$B/deck_${V}_linux_${ARCH}.tar.gz"
curl -fsSLO "$B/checksums.txt"
sha256sum --check --ignore-missing checksums.txt
tar xzf "deck_${V}_linux_${ARCH}.tar.gz" deck
sudo install deck /usr/local/bin/
deck version
cd ~ && rm -rf /tmp/dlExpected:
deck_1.69.0_linux_amd64.tar.gz: OK
decK v1.69.0 (7b20626)
--ignore-missing checks only the file you downloaded. If
it does not say OK, you install nothing.
Save your progress? Sign up for free
Drill 4: Companion Code and Working Directory
mkdir -p ~/kong-lab && cd ~/kong-lab
git clone https://github.com/thomaszachmann/kong-zum-anfassen.git code
mkdir -p setup && cp code/setup/env.sh setup/
source ~/kong-lab/setup/env.sh
ls code
echo "$ADMIN $PROXY"Expected (shortened):
Cloning into 'code'...
LICENSE README.md backend keycloak kong notes observability plugins setup …
http://localhost:8001 http://localhost:8000
You source setup/env.sh every morning.
$ADMIN is Kong’s Admin API, $PROXY the
entrance for clients. code/ stays unchanged; your work goes
into tagNN/.
Save your progress? Sign up for free
Drill 5: The notes-api Image
notes-api is the Go API from “Dockerfiles hands-on”. Build the image once:
cd ~/kong-lab/code/notes/notes-api
docker build -q --build-arg VERSION=0.2.0 -t notes-api:0.2.0 .
docker images notes-apiExpected (shortened, one to two minutes the first time):
sha256:7b0d2646bc6e…
IMAGE ID DISK USAGE CONTENT SIZE EXTRA
notes-api:0.2.0 7b0d2646bc6e 16.4MB 4.5MB
16 MB: a static Go binary on scratch.
GET /notes is open, POST /notes requires the
X-API-Key header. From Day 5 on, Kong takes over exactly
this check.
Save your progress? Sign up for free
Drill 6: Start the Backend
cd ~/kong-lab/code/backend
docker compose up -d --wait
docker compose ps --format "table {{.Service}}\t{{.Status}}\t{{.Ports}}"Expected (shortened):
Container backend-db-1 Healthy
Container backend-echo-1 Healthy
Container backend-notes-api-1 Healthy
SERVICE STATUS PORTS
db Up 9 seconds (healthy) 5432/tcp
echo Up 8 seconds 8080/tcp
notes-api Up 2 seconds (healthy) 8080/tcp
The PORTS column only shows ports
inside the lab network, no arrows to the
outside. From the VM you can reach the services only through a container
in the same network:
docker run --rm --network lab curlimages/curl:8.17.0 -s notes-api:8080/version
docker run --rm --network lab curlimages/curl:8.17.0 -s echo:8080/get | jq .urlExpected:
0.2.0
"http://echo:8080/get"
Save your progress? Sign up for free
Checkpoint
docker compose -f ~/kong-lab/code/backend/compose.yaml ps --servicesExpected: three running services (migrate has finished
and is therefore missing).
db
echo
notes-api
docker network ls --filter name=labExpected: the lab network, which Kong also joins from
Day 1 on.
NETWORK ID NAME DRIVER SCOPE
53d72b31cbd3 lab bridge local
deck versionExpected:
decK v1.69.0 (7b20626)
Challenge
Create a note with notes-api without opening any backend port to the outside. Then check that it is stored in Postgres.
Note: The curl container from Drill 6 can POST too;
you find the key in compose.yaml.
Solution
docker run --rm --network lab curlimages/curl:8.17.0 -s -X POST \
-H 'X-API-Key: lab-api-key-123' -H 'Content-Type: application/json' \
-d '{"text":"vor dem Gateway"}' notes-api:8080/notes
docker compose -f ~/kong-lab/code/backend/compose.yaml exec db \
psql -U notes -d notes -c 'select text from notes'Expected (shortened):
{"id":"ba87895f-…","text":"vor dem Gateway"}
text
-----------------
vor dem Gateway
(1 row)
Without Kong, every client has to know the API’s key and get directly
into the lab network. Both change starting tomorrow.
Save your progress? Sign up for free
Enterprise Note
- No port to the outside: Backends behind a gateway are reachable only in the internal network. The gateway is the only point that faces the outside.
- Secrets: The lab values are in plain text in
compose.yamlhere. In production they come from Docker secrets, a vault or Kong’s secret references ({vault://…}). - Verify binaries: Every downloaded tool is verified against the vendor’s checksum, better still against a signature (“Container tools hands-on”).
- Pin versions:
notes-api:0.2.0,postgres:18.6-alpine, neverlatest.