Raymii.org

Table of Contents

• Introduction and info on Proxmox VE 9.1's OCI image feature
• Starting an OCI image in Proxmox VE 9.1.1

Proxmox VE is a virtualization platform, like VMWare, but open source, based on Debian. It can run KVM virtual machines and Linux Containers (LXC). I've been using it for over 10 years, the first article I wrote mentioning it was in 2012. At home I have a 2 node Proxmox VE cluster consisting of 2 HP EliteDesk Mini machines, both running with 16 GB RAM and both an NVMe and SATA SSD with ZFS on root (256 GB). It's small enough (physically) and is just enough for my homelab needs specs wise. Proxmox VE 9.1 was released recently and this new version is able to run Docker containers / OCI images natively, no more hacks or VM's required to run docker. This post shows you how to run a simple container from a docker image.

Recently I removed all Google Ads from this site due to their invasive tracking, as well as Google Analytics. Please, if you found this content useful, consider a small donation using any of the options below. It means the world to me if you show your appreciation and you'll help pay the server costs:

GitHub Sponsorship

PCBWay referral link (You get $5, I get $20 after you've placed an order)

Digital Ocea referral link ($200 credit for 60 days. Spend $25 after your credit expires and I'll get $25!)

Introduction and info on Proxmox VE 9.1's OCI image feature

Linux Containers (LXC) in Proxmox VE behave more like a virtual machine than Docker containers, most of the time. A Docker container runs one application, an LXC container runs a whole slew (init system, ssh, an entire distribution). For as long as I can remember, Proxmox VE has no official way of running Docker containers natively. They recommend to run docker inside a Proxmox QEMU virtual machine. Sometimes (recently), Docker-inside-LXC actually breaks.

But nobody wants to manage an entire VM just to play around with some containers and running Docker directly on your Proxmox VE host is a bad idea as well.

They did something quite clever. They sort of convert the container image to a full fledged LXC image. In some place it seems that skopeo is used.

Quoting a forum post with more info:

May I ask why docker LXC's are a no-no?

Generally this causes issues between our use of Apparmor and other parts of our code base over and over again. So we heavily discourage it. However, with the release of Proxmox VE 9.1 you can use OCI templates for application containers on Proxmox VE.

This means that you can run Docker containers as application containers on Proxmox VE like you would any other LXC container. It works by translating the Docker images (which are OCI images) to LXC containers on Proxmox VE.

Not everything works yet, this is still a tech preview as of writing:

While it can be convenient to run "Application Containers" directly as Proxmox Containers, doing so is currently a tech preview. For use cases requiring container orchestration or live migration, it is still recommended to run them inside a Proxmox QEMU virtual machine.

In the current technology preview state of our OCI image support, all layers are squashed into one rootfs upon container creation. Because of this, you currently cannot update a container simply by swapping in a newer image

So technically the title of this article is wrong, you aren't running Docker containers natively, they're converted. But for what it's worth, it saves so much time already. Now only if Proxmox VE supported docker-compose files, that would be even more amazing.

Upgrading containers (a docker pull) isn't straightforward ( yet), it requires fiddling with data volumes and re-creating a container. The console also does not provide a shell in most containers, it just shows the stdout/in of the main init process.

Running pct enter xxx did drop me inside a working shell in the converted container.

Starting an OCI image in Proxmox VE 9.1.1

Make sure you've updated Proxmox VE to at least 9.1.1.

Starting a docker container (OCI image, I'll use these terms interchangeably in this article) consists of two steps, first you must download the image to template storage, then you can create a container from that image.

Navigate to your storage and click the Pull from OCI Registry button:

Enter the full URL to a container image. For example, docker.io/eclipse-mosquitto:

(If you spell the URL wrong you'll get weird errors, I got a few errors mentioning "Unauthorized", while I just had a typo in the reference, nothing to do with authorization).

Click the Download button and watch the image being pulled:

That was the storage part. Now the container part. Click the Create CT button, fill in the first tab and on the second (Template) tab, select the OCI image we've just downloaded:

On the Disks tab, you can add extra volumes under a mount point, in this case for the mosquitto configuration:

This is comparable with the -v option when running docker containers to mount a local directory inside a container

Fill in the other tabs as you would normally do. This is the summary page:

In the Create task output you can see that Proxmox VE detected that the image is an OCI container / Docker image. It will do some extra stuff to "convert" it to an LXC container:

That's all there is to it. You can now start your container and enjoy all the features you would normally get from an LXC container managed by Proxmox VE.

The console shows an extra notification regarding this being an OCI image based container:

In my case the console did not work, as mentioned earlier, but I was able to enter the container just fine:

After editing the mosquitto config (on the /mosquitto/config volume) and restarting the container I was able to connect just fine:

# example config:
listener 1883
allow_anonymous true

Environment variables are available in the Options tab once the container is created:

(but currently not during initialization)

I also tried the official nginx docker container image, that worked just fine as well. This will be a major time saver when running containers.

Tags: docker , homelab , kvm , linux , lxc , oci , proxmox , proxmox-ve , qemu , sysadmin , tutorials , virtualization