Docker Host

Creating the virtual machine in Proxmox.

1. Upload the installer. Download the Manjaro XFCE minimal ISO and upload it under local > ISO Images.
2. Start the wizard. Click Create VM, give it ID 101 and the name docker, and tick Start at boot. Select the ISO and set the guest type to Linux.
3. System and disk. Set the SCSI controller to VirtIO SCSI single, then create a 64 GiB disk on local-lvm with IO thread ticked and the Write back cache mode.
4. CPU and memory. One socket with 4 cores of type x86-64-v2-AES, and 8192 MiB of memory.
5. Network. One VirtIO network card on vmbr0, the LAN bridge.
6. Install the system. Start the VM, boot the live environment, and run the installer, letting it use the whole 64 GiB disk. When it finishes, detach the ISO under Hardware > CD/DVD Drive and reboot.

From a fresh install to a working engine.

1. Update the system and install Docker with its Compose plugin:

   $ sudo pacman -Syu
   $ sudo pacman -S docker docker-compose

2. Start it now and at every boot:

   $ sudo systemctl enable --now docker

3. Let your user run Docker without sudo, then sign out and back in so the change takes effect:

   $ sudo usermod -aG docker $USER

4. Check that it works:

   $ docker run --rm hello-world

5. Reserve the VM’s address. Give the Docker host a static mapping on the firewall (OPNsense Guide 1) so that the reverse proxy always finds it.

Managing containers with Portainer.

Portainer gives the Docker host a web interface for containers, volumes, networks, and Compose stacks. It runs as a container itself, from its own Compose file in /opt, and it reaches Docker through the engine’s socket.

1. Deploy Portainer. Save this as compose.yaml in a folder such as /opt/portainer and start it with docker compose up -d:

   services:
     portainer:
       image: portainer/portainer-ce:latest
       restart: unless-stopped
       ports:
         - "9443:9443"
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock
         - portainer_data:/data
   
   volumes:
     portainer_data:

2. Create the administrator. Browse to https://<host-address>:9443 within a few minutes of the first start and set the admin password. Portainer locks the setup page if it is left too long.
3. Add a stack. Open Stacks > Add stack, name it (for example 2000-infrastructure), paste a Compose file into the web editor, and click Deploy the stack.
4. Update a stack. Open the stack, edit the file if needed, and update it with the option to re-pull images, which recreates the containers on the newest image.
5. Create an access token. Under My account > Access tokens, add a token for scripts or read-only inspection. It is sent in an X-API-Key header, and it carries the same rights as your account.

Notes

• Treat Portainer like root. Access to the Docker socket is effectively administrator access to the whole host. Keep Portainer behind the reverse proxy with an access list, or reach it over the VPN, and use a strong password.
• Staying current. Most images follow their latest tag, and What’s Up Docker watches for newer versions, so updates are a deliberate redeploy from Portainer rather than something that happens by surprise.

A small service to prove the path end to end.

A tiny web service that reports which container answered is a good first test. Save this as compose.yaml in a new folder:

services:
  whoami:
    image: traefik/whoami
    ports:
      - "8080:80"
    restart: unless-stopped

Start it, then request it from another device on the network (using your Docker host’s reserved address in place of the example one):

$ docker compose up -d
$ curl http://192.168.10.20:8080

The same address and port are what you enter as the upstream in the Caddy handler (OPNsense Guide 4), which puts the service behind a trusted HTTPS hostname. restart: unless-stopped brings the container back after a reboot.

Giving the VM a physical USB device.

One USB device on the mini PC is passed through to this VM, so software in a container can talk to the hardware directly.

1. Open the VM’s Hardware > Add > USB Device.
2. Choose Use USB Port and pick the port the device is plugged into. This setup uses the port form, so the device keeps working after it is unplugged and plugged back in, as long as it stays in the same socket. Use USB Vendor/Device ID follows the device to any socket instead.
3. Restart the VM, then confirm the guest sees it with lsusb.
4. To give a container access, pass the device node through in Compose with a devices: entry.

The rest of the lab.

1. ProxmoxThe hypervisor that hosts this virtual machine.
2. OPNsenseAn open-source firewall and routing platform.
3. Home Assistant OSThe appliance operating system for Home Assistant.