DockVMap

DockVMap is a self-hosted Docker and OCI registry proxy. It gives container deployments a stable image tag while keeping control over the version behind that tag.

The idea

Docker image tags create a trade-off when managing updates.

A tag such as latest can change at any time. A fixed version such as 1.4.2 gives more control, but every upgrade requires changes to the deployment configuration.

DockVMap adds a layer between the deployment and the upstream registry.

A container can always pull:

registry.example.com/app:current

DockVMap maps current to a real image tag, such as app:1.4.2.

When a new version is ready, an administrator can change that mapping from the web interface. The container configuration stays the same.

This keeps image references stable while making version changes explicit and easy to track.

Tracking new versions

DockVMap checks upstream registries for new tags. It groups related tags into version families and can identify newer versions within the same family.

For example, an image may currently use 1.4.2 while 1.4.3 and 1.5.0 become available upstream. DockVMap can detect those changes and show them in the web interface.

Finding a new version does not change the active mapping. An administrator decides when to promote a new version.

DockVMap also keeps a history of every version used by a virtual tag. This provides a simple record of what changed and when.

Registry proxy

Docker clients use the standard OCI Distribution API to communicate with DockVMap.

The proxy can work with Docker Hub, GitHub Container Registry, private registries, and other OCI-compatible registries.

DockVMap can also cache image manifests and blobs on disk. This reduces repeated downloads when multiple clients request the same image data.

Authentication for private upstream registries is supported as well.

Web interface

A web interface provides a central place to manage registries, virtual images, and version mappings.

It also shows available updates and version history. Notifications can alert administrators when upstream tags change or when a new upgrade becomes available.

Email notifications use SMTP. Generic webhooks are also available for integration with other services.

The application records state-changing actions in an audit log. Each entry includes the action, the user, and the client address.

Deployment

DockVMap runs as a single service. The application includes the registry proxy, web interface, REST API, and background workers.

The backend uses Go. The web interface uses Svelte. SQLite stores the application data.

This keeps the deployment simple. There is no separate database or message queue to maintain.

DockVMap can run as a standalone binary or through Docker Compose.

The result is a simple way to manage container image updates without changing image references throughout an infrastructure setup.