Daniel Nashed's Blog

Domino NRPC Proxy – A Modern Proxy Platform for Domino

The Domino NRPC Proxy project started with a simple but ambitious goal: provide a modern, production-ready proxy for Domino NRPC connections that integrates naturally with Docker and Kubernetes.

While traditional TCP proxies can forward NRPC traffic, they have no understanding of the Domino protocol itself.
At the heart of the project is a custom NGINX Stream module that understands the initial Domino NRPC handshake and enables intelligent routing based on the requested Domino server.
Since then, the project has grown well beyond its original scope.
Today it provides a complete proxy platform for Domino, combining NRPC routing, HTTPS reverse proxy support, generic stream proxying.


Key Features

• Custom NGINX Stream module for Domino NRPC
• Intelligent NRPC routing based on the requested Domino server
• HTTPS reverse proxy support
• Generic TCP stream proxy support
• Optional ACME certificate management using LEGO
• Dynamic configuration generation from templates
• Zero-downtime configuration updates
• Automatic certificate reload
• Native Docker and Kubernetes support
• Docker Secrets and Kubernetes Secrets integration
• Environment variable driven configuration
• Own Prometheus metrics endpoint including details about configuration status
  

The container build compiles NGINX and the stream module. The Image can be build with the included build script. The image is also available on the GitHub registry as part of the GitHub project.


Intelligent NRPC Routing


The Domino NRPC Proxy is much more than a TCP forwarder.
The project includes a custom NGINX Stream module developed specifically for Domino NRPC. The module understands the initial NRPC protocol exchange and extracts the Domino server name requested by the Notes client.
This information is then used to make an intelligent routing decision before forwarding the connection to the appropriate back-end Domino server.
The entire process is completely transparent to the client and requires no changes to existing Notes or Domino installations.

This makes it possible to:

• Publish a single NRPC endpoint for multiple Domino servers.
• Route Notes clients automatically to the requested server.
• Hide backend Domino servers inside private Docker or Kubernetes networks.
• Dynamically route connections as infrastructure changes.
• Simplify load balancer configurations.
• Scale from a single Domino server to large Domino deployments.

This capability is particularly valuable in Kubernetes environments, where Domino servers are represented by services and pods whose network topology may change over time.


HTTPS Reverse Proxy


Although NRPC remains the primary focus of the project, most Domino environments also expose HTTP and HTTPS services.
The Domino NRPC Proxy now includes a fully integrated HTTPS reverse proxy based on NGINX.

Features include:

• HTTPS reverse proxy
• HTTP to HTTPS redirection
• Multiple virtual hosts
• Configurable upstream servers
• Dynamic configuration generation

Running both NRPC and HTTPS within the same proxy simplifies deployments while providing a consistent operational model.


Generic Stream Proxy Support


The custom NRPC module is one part of the project.
The surrounding infrastructure has been designed to support generic TCP stream proxying as well.
This allows the same container to proxy additional TCP services using the same configuration framework, making the project useful beyond Domino-specific scenarios.


Designed for Docker and Kubernetes


The project was designed from day one with containers in mind.
Whether you're deploying a single Domino server with Docker Compose or operating a large Kubernetes cluster, the same container image can be used without modification.
Configuration is generated automatically during startup, allowing deployments to be driven entirely by environment variables and secrets.
The result is a container that fits naturally into Infrastructure-as-Code workflows and automated deployments.


Dynamic Configuration Templating


Maintaining multiple static NGINX configuration files quickly becomes difficult as deployments grow.
Instead, the Domino NRPC Proxy gene7rates its configuration dynamically from templates.

The templating system supports:

• HTTP configuration
• Stream configuration
• Environment variable substitution
• Optional feature enablement
• User supplied templates
• Deployment specific customization

This approach keeps the container image generic while allowing extensive customization without rebuilding images.


Zero-Downtime Configuration Updates


Container environments are dynamic by nature.
Services may be added, removed or updated while the proxy continues running.
Whenever configuration changes are detected, the proxy automatically:

• Generates the new configuration
• Validates it using nginx -t
• Atomically replaces the active configuration
• Reloads NGINX without interrupting existing client sessions
  
  

Existing NRPC and HTTPS connections continue uninterrupted while new connections immediately use the updated configuration.


Automatic Certificate Management


The latest versions add optional integrated ACME support using the excellent LEGO client.
The proxy can automatically request and renew certificates from Let's Encrypt or any RFC 8555 compatible ACME provider.

Supported features include:

• Let's Encrypt Production and Staging
• Alternative ACME providers
• HTTP-01 challenge support
• Automatic renewals
• Environment variable based configuration
• Automatic NGINX reload after successful renewal
• Support LEGO environment configuration

The implementation also handles the initial bootstrap process, allowing completely unattended deployments.


Automatic Certificate Reload


Certificates may also be provided by external certificate management solutions.
The Domino NRPC Proxy automatically detects updated certificates and reloads NGINX without requiring container restarts.
This enables continuous certificate management without downtime or maintenance windows.


Secret Integration


Security is an important design goal.
Sensitive configuration data should never be embedded in container images.

The Domino NRPC Proxy provides native support for:

• Docker Secrets
• Kubernetes Secrets

Certificates, private keys, bearer tokens, API credentials and other sensitive configuration can be securely mounted while remaining fully compatible with the templating framework.


Built Around Automation


One of the guiding principles throughout the project has been automation.
A modern infrastructure component should require as little manual configuration as possible.
The Domino NRPC Proxy therefore focuses on:

• Convention over configuration
• Environment variable driven deployments
• Dynamic configuration generation
• Automated certificate management
• Automatic configuration validation
• Zero-downtime updates
  
  

The result is a proxy that is equally at home in a simple Docker installation or a fully automated Kubernetes platform.


Part of the Domino Infrastructure Ecosystem


The Domino NRPC Proxy has become one of the core building blocks of a larger Domino infrastructure ecosystem.
It integrates naturally with projects such as:

• Domino Fleet Manager
• Cube Control
• CertMgr
• Domino monitoring components
  
  

Each project is designed to work independently, while together they provide a modern platform for deploying, managing and operating HCL Domino environments.


Open Source


The Domino NRPC Proxy is available as an open source project on GitHub:
https://github.com/nashcom/domino-nrpc-proxy
The project has evolved considerably since its first release and continues to grow with new features and deployment options.
If you're running Domino in Docker, Kubernetes, or simply looking for a modern proxy platform for Domino services, I hope you'll find it useful.


Comments Disabled