Lab setup

After docker compose up -d, the WireGuard container generates a peer config for the isopod peer and writes it to a named volume. Print it:

docker compose exec vpn cat /config/peer_isopod/peer_isopod.conf

Or copy the file to your working directory:

docker compose cp vpn:/config/peer_isopod/peer_isopod.conf ./isopod.conf

The config contains a private key, the server endpoint, and the allowed IPs route (10.78.8.0/24). Keep it local — it grants LAN access.

Open the WireGuard app (macOS: App Store; Windows: wireguard.com). Click Import tunnel from file and select isopod.conf, or use the CLI:

# macOS (after installing wireguard-tools via Homebrew)
wg-quick up ./isopod.conf

# Windows (admin PowerShell)
& "C:\Program Files\WireGuard\wireguard.exe" /installtunnelservice isopod.conf

Activate the tunnel in the app (toggle it on), or the wg-quick up command does it immediately. You only need to do this once per session — the tunnel stays up until you deactivate it.

With the tunnel active, the full LAN is reachable by IP:

ping 10.78.8.10
ssh isopod@10.78.8.10        # no port flag needed
curl http://10.78.8.20/      # webserver
curl http://10.78.8.20/api/  # REST API

If you rebuild the lab with docker compose down -v the WireGuard volume is wiped and a new key pair is generated on the next up. You will need to re-extract and re-import the config.

docker compose ps

The client service must show running or Up, not restarting or exited. If it is not running, read the logs:

docker compose logs client

The container may be running but the port binding may have failed silently (e.g. another process already held the port at compose-up time).

# macOS / Linux
lsof -i :2222

# Linux alternative
ss -tlnp | grep 2222

# Quick reachability test (exits 0 if something answers)
nc -zv 127.0.0.1 2222

If Docker (or com.docker) owns port 2222, the binding is correct — the problem is inside the container; continue to step 3. If a different process owns it, that process grabbed the port before Docker could — see step 4. If nothing appears, Docker never bound the port at all; re-check step 1 and look at docker compose logs client for startup errors.

docker compose up -d returns as soon as the container process starts, not after the init system inside has finished launching sshd. On a cold build this can take a few seconds. Run:

docker compose exec client ps aux | grep sshd

If sshd is absent, wait five seconds and try again. If it never appears, the Dockerfile entrypoint may have failed:

docker compose logs --tail 50 client

Find and kill the conflicting process, then re-create the container so Docker can bind the port:

# Find the PID holding port 2222
lsof -ti :2222

# Kill it (replace <PID>)
kill <PID>

# Re-create the client container
docker compose up -d --force-recreate client

Common culprits: a previous container that was not fully stopped, a local SSH proxy, or another lab stack. Running docker compose down before up -d avoids this.

If you previously connected and then rebuilt the lab volumes, the host key changes and SSH refuses with a REMOTE HOST IDENTIFICATION HAS CHANGED error. Clear the stale entry:

ssh-keygen -R "[127.0.0.1]:2222"

Then reconnect — SSH will prompt you to accept the new fingerprint.

Docker Desktop must be running (macOS menu bar / Windows system tray) for port forwarding to work. If you started the containers in a previous session and Docker Desktop was restarted since then, the port mappings may have been dropped. Bring everything back up:

docker compose down
docker compose up -d