Using Docker Compose on a Proxmox VM

March 26, 2026

Before getting deeper in my Kubernetes studies, I took some time to get back into the container fundamentals with Docker and Docker Compose. Since I have a Proxmox setup I made a dedicated VM for this process. Here’s what I had to do, from start to finish.

Create a new Proxmox VM

After setting up the vm, the first step was to install Ubuntu Server. I already have the ISO on Proxmox, and it’s an easy install. After that I had to make it accessible through ssh which is 2 main steps: adding the QEMU agent, then adding my ssh key.

Adding the QEMU Agent

To avoid any issue during the service activation, it’s useful to enable the “QEMU Guest Agent” setting in the VM options before installing the agent.

sudo apt update
sudo apt install qemu-guest-agent
sudo systemctl start qemu-guest-agent
sudo systemctl enable qemu-guest-agent

At that point I have an IP I can use to access the VM from my local network.

Configure SSH connection

I already have a ssh key, so I sent the public key to the VM with ssh-copy-id <user>@<server>. After making sure it was working, I disabled password authentication, only allowing ssh:

PasswordAuthentication no
PubkeyAuthentication yes

Then I restarted the ssh service, and made sure I could still connect.

sudo systemctl restart sshd

I like to have an easy access to my servers so I added a line in my hosts file, and a new block to my ssh config

# In /etc/hosts
<ip>        docker-vm-1

# In ~/.ssh/config
Host docker-vm-1
    HostName docker-vm-1
    User <username>
    IdentityFile ~/.ssh/id_ed25519

Docker

Installing Docker Engine on Ubuntu

To install Docker on the VM I used this guide.

I had an permission issue: permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

My user was not in the docker group, so I added myself with sudo usermod -aG docker $USER. To avoid having to log out and in angain, I used newgroup docker to use the group instantly. At that point, docker ps was working as expected and I could move on to my laptop setup.

Using Docker Contexts

Now that Docker was on the VM, I had to get a way to use it from the laptop. Docker was already installed there, so I just had to add a new docker context.

# create the new context
docker context create docker-vm-1 --docker "host=ssh://user@docker-vm-1"

# use the context
docker context use docker-vm-1

# now all the following commands will use that context

Deploying something using Docker Compose

With everything ready, I could use my new setup to deploy a local app. As a first app I used PageTurner. This is still a work in progress, so I build and deploy with a --build flag:

docker-compose up --build

I had an error with the vite config:

Blocked request. This host ("docker-vm-1") is not allowed.
To allow this host, add "docker-vm-1" to `server.allowedHosts` in vite.config.js.

I used that opportunity to add a new env variable to the project to control what hosts are allowed.

I still need to do the proper work to make it accessible online. But I have a new ISP installation next week and a new router coming with it so I’ll do that once it’s there. In the meantime, I wanted to test ngrok. For basic usage it’s very simple, I can see this being a nice tool for a quick demo of a project to someone remote.

# Install ngrok
curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
  && echo "deb https://ngrok-agent.s3.amazonaws.com bookworm main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list \
  && sudo apt update \
  && sudo apt install ngrok

# Add token
ngrok config add-authtoken <token>

# Use ngrok
ngrok http <port>

While it’s running you get a display of request being made, and the url you need to use is also displayed. Can’t make it easier than that.

Summary

I now have a new VM for Docker projects! I already tried a few apps on there, but this is only a temporary step towards a kubernetes homelab. I’m looking forward to what the next iteration will bring.

Tags: