ViceRegistry: Architecture and implementation of a FOSS Docker Registry with Astro and Nginx

In the current cloud computing landscape, the management of software artifacts has become a critical component of the supply chain. Increasingly, companies find themselves trapped between two less-than-ideal options: on one hand, SaaS platforms, which are convenient but expensive in the long run, and on the other, complex enterprise on-premise solutions that are difficult to maintain.

It is precisely from this tension that ViceRegistry was born, a project developed by Vicedomini Softworks, designed to offer a concrete alternative: a lightweight and secure open source Docker registry, built according to the principles of Free and Open Source Software.

Rather than reinventing what already exists, ViceRegistry positions itself as an intelligent layer above the official Docker Registry, adding advanced authentication, search, and management features.

The philosophy: engineering with a long-term vision

At the heart of the project is the engineering approach of Vicedomini Softworks, oriented towards technical sustainability over time. In a sector often dominated by release speed, the goal is to build software that remains solid, understandable, and scalable even after years.

ViceRegistry was actually born as an internal solution, developed to avoid the costs and limitations of commercial registries. Only later was it evolved into an open source project, while maintaining the same design rigor required in enterprise environments.

Architecture: apparent simplicity, engineering depth

One of the most interesting aspects of ViceRegistry is its architecture, built on a clear separation of responsibilities.

At the center we find NGINX, which does not just act as a reverse proxy but acts as a true intelligent gateway. HTTP requests are routed strategically: traffic to the dashboard is sent to the frontend developed with Astro, while all calls compatible with the OCI standard (under /v2/) are handled directly with the native efficiency of NGINX.

This architectural choice allows avoiding heavy binary flows – such as pushing and pulling Docker images – from passing through more complex application runtimes, drastically reducing latency and resource consumption.

Astro: fast frontend and authentication server

The choice of Astro is not accidental. Thanks to its “Islands” architecture, the framework allows sending mainly static HTML to the browser, using JavaScript only where really necessary.

But Astro is not limited to the UI. In ViceRegistry, it also plays the role of authentication server. When a client attempts to authenticate, the system generates a signed JSON Web Token (JWT), which becomes the central mechanism for authorizing all subsequent operations.

Security: a modern and multifactorial approach

One of the distinctive elements of the project is the attention to security, often overlooked in simpler registries.

For access to the web dashboard, ViceRegistry supports the WebAuthn standard, which allows authentication via hardware devices such as YubiKey or biometric systems. This entirely eliminates reliance on traditional passwords, drastically reducing the risk of phishing.

Alternatively, the TOTP protocol is also available, compatible with major authentication apps.

Regarding CLI usage, the flow follows the Docker CLI standard: after login, a JWT token with granular permissions and limited duration is issued, ensuring precise and secure access control.

PostgreSQL: from simple registry to intelligent platform

One of the historical limitations of the Docker Registry is the lack of advanced search and metadata management tools. ViceRegistry overcomes this problem by introducing PostgreSQL as the source of truth.

Every uploaded image is indexed, allowing:

• quick searches on repositories and tags
• advanced permission management (RBAC)
• secure MFA data storage
• audit logs and analytics

In this way, the registry ceases to be a simple storage and becomes a true management platform.

Comparison with alternatives: Harbor and Docker Hub

In the comparison with Harbor, one of the most widespread open source solutions, the positioning of ViceRegistry emerges clearly. Harbor offers many features but requires complex infrastructure and high resources. ViceRegistry, on the other hand, focuses on lightness: it can run with less than 1GB of RAM, making it ideal for edge environments or small teams.

Compared to Docker Hub, however, the main advantage is data sovereignty. By using a self-hosted solution, companies eliminate rate limiting, reduce transfer costs, and maintain full control over their images.

Deployment: container-first simplicity

Consistent with the DevOps philosophy, ViceRegistry is designed to be started quickly via Docker Compose. The entire stack – Astro, NGINX, PostgreSQL, and Registry – can be brought online in a few seconds.

The build process also follows modern best practices, using multi-stage images with code in TypeScript compiled at build time and distributed on minimal Alpine images, reducing the attack surface.

Conclusions: a concrete and sustainable alternative

ViceRegistry proves that it is possible to build a modern Docker registry without compromises between performance, security, and simplicity.

By integrating standards like WebAuthn, leveraging the power of PostgreSQL, and adopting a lightweight architecture based on Astro and NGINX, the project represents a concrete solution for companies that want to maintain control over their infrastructure.

In an era where software tends to become increasingly complex and dependent on external services, the approach of Vicedomini Softworks demonstrates that there is still room for careful, sustainable, and long-term oriented engineering.

To learn more or contribute to the project, you can consult the official repository on GitHub or contact the team directly through our software consulting services.