Image identity
Repository, rolling tag, architecture, resolved digest and source revision.
How an OCI image is translated
OCI manager Apps~6 min
From the image repository and its Compose file to a reviewable template, a deployment plan and a native LXC, without installing Docker inside.
The translation pipeline
Loading diagramβ¦
The converter reads the image and the Compose file its project publishes and writes a JSON template. A template with untranslated blockers goes through review, where a curated overlay resolves them, before it is published in the catalog. Only templates without blockers are offered for installation.
What the template keeps
Container contract
Entrypoint, Cmd, environment, user, working directory, stop signal, ports and volumes.
Proxmox VE translation
Resources, security, mount points, devices, sysctls, healthchecks and the adaptations each one needs, with their reason.
Compatibility
Supported keys, untranslated blockers and the state of each validation.
OCI provides the process; Compose provides the environment
| Source | Example | Native result |
|---|---|---|
| OCI metadata | Entrypoint, Cmd, User | Proxmox VE imports them when the CT is created |
| Docker Compose | environment, volumes, devices | LXC environment entries, mpN and devN |
| ProxMenux profile | GPU, healthcheck, credentials | questions and reviewed adaptations |
| User | VMID, storage, network | the instance contract |
What happens during an installation
- 1
Resolve
The registry is queried, the host architecture is selected and the effective digest of the rolling tag is fixed.
- 2
Download and verify
Skopeo downloads the image as an OCI archive, and every layer is checked against its digest and decompressed before anything is created. A damaged download is fetched a second time before the installation stops.
- 3
Build
pct createbuilds the rootfs from the archive and keeps the official process metadata of the image. - 4
Connect
The declared volumes, network, environment, devices and security profiles are attached.
- 5
Console
The console output of the container is kept on the host, and the Proxmox VE console opens a shell when the image ships one.
- 6
Check
The first start waits for an address and for the service to answer; a failure is not reported as a successful installation.
- 7
Register
The effective configuration is written to the instance contract that updates and recreations use.
Example: an image with /config and /downloads
A common Compose definition and the Proxmox VE configuration it becomes. The paths the application expects do not change.
Docker Compose
image: lscr.io/linuxserver/example:latest environment: - PUID=1000 - PGID=1000 volumes: - config:/config - /srv/downloads:/downloads ports: - 8080:8080
/etc/pve/lxc/VMID.conf (excerpt)
entrypoint: /init mp0: local-lvm:vm-VMID-disk-1,mp=/config,backup=1,size=8G mp1: /srv/downloads,mp=/downloads net0: name=eth0,bridge=vmbr0,ip=dhcp,type=veth lxc.environment.runtime: PUID=1000 lxc.environment.runtime: PGID=1000
mp0 is a second disk that belongs to the container, named vm-VMID-disk-N on the selected storage. It is mounted at /config and, with backup=1, it is part of the container backup. mp1 creates no disk: it binds the host directory /srv/downloads to /downloads inside the LXC. Port 8080 is not mapped: the LXC has an address of its own and the service answers on it.