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

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

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 Vicedomini Softworks' engineering approach, focused on long-term technical sustainability. 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 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 rigorous design 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 its core, we find NGINX, which not only acts as a reverse proxy but also as a true intelligent gateway. HTTP requests are routed strategically: traffic to the dashboard is sent to the frontend developed with Astro, while all OCI-compatible calls (under /v2/) are handled directly with NGINX's native efficiency.

This architectural choice prevents heavy binary flows – such as Docker image push and pull – 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 primarily sends static HTML to the browser, using JavaScript only where truly necessary.

But Astro is not limited to the UI. In ViceRegistry, it also acts as an 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 its focus on security, often overlooked in simpler registries.

For web dashboard access, ViceRegistry supports the WebAuthn standard, which enables authentication via hardware devices like YubiKeys 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.

For CLI use, 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 a source of truth.

Every uploaded image is indexed, allowing for:

• fast searches on repositories and tags
• advanced permission management (RBAC)
• secure storage of MFA data
• audit logs and analysis

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 comparison with Harbor, one of the most widespread open-source solutions, ViceRegistry's positioning becomes clear. 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, 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 quickly started via Docker Compose. The entire stack – Astro, NGINX, PostgreSQL, and Registry – can be brought online in a few seconds.

Building processes also follow modern best practices, using multi-stage images with TypeScript code compiled during the build phase and distributed on minimal Alpine images, reducing the attack surface.

Conclusions: a Concrete and Sustainable Alternative

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

By integrating standards such as 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, Vicedomini Softworks' approach 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 GitHub repository or contact the team directly through their software consulting services.