Technical Product Information - ADOGRC 15

Overview​

Starting with ADOGRC 15, the product is delivered to on-premise customers in a fully containerised form. This marks an important step towards improved scalability, portability and operational flexibility. By adopting a modern container-based delivery model, ADOGRC can be deployed more efficiently in current and future IT environments while preserving the familiar capabilities of earlier versions.

Architecture​

With ADOGRC 15, the application is distributed as a set of OCI-compliant container images. This approach maintains the functional architecture of previous ADOGRC versions while enabling a flexible and modern deployment model.

The main application components are executed as two separate containers:

• web server container

• application server container

The corresponding images are made available through an OCI-compliant registry.

ADOGRC supports two deployment variants:

• Kubernetes deployment, using the supplied Helm chart

• Docker Compose deployment, using the supplied Compose configuration

Both deployment options orchestrate the same two containerised application components. Kubernetes offers advanced orchestration capabilities with specialized resource types and integration features and is, in general, an enterprise-grade cluster architecture, while Docker Compose provides a simpler setup for environments that do not require full Kubernetes capabilities.

The ADOGRC database is typically operated outside the Kubernetes cluster or Docker environment. Customers continue to manage their existing database server independently.

Kubernetes Deployment​

The following diagram illustrates how ADOGRC 15 is deployed in a Kubernetes environment. The application components run in a dedicated namespace, while supporting infrastructure components are typically provided in other namespaces.

Prerequisites on Kubernetes​

The Kubernetes cluster in which ADOGRC will run must provide:

• An Ingress controller or Gateway API controller for routing end-user traffic

• A StorageClass for provisioning persistent volumes

  • allowVolumeExpansion=true is highly recommended

It is recommended that the cluster also provides:

• cert-manager for automating TLS certificate handling for ingress or HTTPRoute

• ClamAV, exposing a TCP endpoint for malware scanning during file upload/download

Architectural Details​

ADOGRC Namespace​

The ADOGRC application components run in their own namespace and consist of:

• HttpRoute / Ingress, which acts as the entry point for external traffic into the ADOGRC namespace.

• web server tier, where the web server is exposed through a Kubernetes service and uses a persistent volume for storing local logs.

• application server tier, where the application server runs as a separate deployment with its own service and persistent storage for the full-text search index and local logs.

Other Namespaces​

Cluster-level components that support the ADOGRC deployment:

• Ingress controller / gateway API controller for routing external traffic

• StorageClass used to provision persistent volumes

• cert-manager (optional) for TLS certificate automation

• ClamAV (optional) for malware scanning

Deployment Behaviour​

• Both the web server and application server deployments support vertical scaling through memory and CPU requests/limits.

• From Kubernetes 1.35 onwards, requests and limits can be adjusted at pod level without recreating the Pod.

• Each deployment uses a single replica; ADOGRC 15 does not support horizontal scaling with multiple replicas.

• Local logs are required to enable creation of a Support Information Package (SIP) within the application, which is necessary for technical support.

External Database​

ADOGRC uses an external PostgreSQL or Microsoft SQL Server database, which runs outside the Kubernetes cluster and is managed independently.

Docker Compose Deployment​

The following diagram illustrates how ADOGRC 15 can be deployed on a single host using Docker Compose-compatible tooling such as Docker or Podman.

In this setup, the ADOGRC web server and application server containers run on the same machine. Persistent data is stored using Docker volumes, and external access is typically provided through a reverse proxy.

Architectural Details​

ADOGRC Docker Compose Stack​

The Compose stack consists of:

• reverse proxy (e.g. nginx), which handles incoming HTTP(S) requests and forwards them to the ADOGRC web server

• web server container

• application server container

• volumes, used to store local logs and the full-text search index

Deployment Behaviour​

• Both the web server and application server run on a single host.

• Container volumes ensure persistence for logs and search index data.

• Scaling is limited to a single-node setup; multi-replica or distributed deployment is not supported.

• Local logs stored in volumes enable the creation of a Support Information Package (SIP) for hotline support.

External Database​

ADOGRC uses an external PostgreSQL or Microsoft SQL Server database, which runs outside the Kubernetes cluster and is managed independently.

Registry and Updates​

ADOGRC 15 is distributed in a container-based format. The following release artefacts are provided.

Container Images​

The ADOGRC application is distributed as a set of container images, including:

• web server image – provides the web interface and handles HTTP(S) requests

• application server image – executes the ADOGRC application logic and backend operations.

Helm Charts​

For Kubernetes-based deployments, ADOGRC provides a Helm chart for each released ADOGRC version. This chart defines the Kubernetes resources and configuration parameters required to run ADOGRC components in a containerised environment.

The delivery includes an umbrella chart that defines the full ADOGRC deployment.

The umbrella chart contains a central values.yaml file, which specifies:

• container image references

• resource settings

• service configuration

• environment-specific parameters

These values can be customised to suit the target environment.

The Helm chart contains only deployment configuration, such as:

• container image definitions

• Kubernetes resource specifications

• configuration parameters

The Helm chart does not contain or preload application data.

Application data is stored persistently in the configured database and is therefore not affected by deploying, upgrading, or redeploying the Helm chart. This ensures that deployments remain stateless at the application layer, while persistent data is managed independently via the database and configured persistent storage.

Artifact Distribution​

Container Registry​

All container images and Helm charts are distributed through an official, BOC-managed OCI-compliant registry.

To find out how to obtain access to the BOC OCI registry, see Container Registry Access for Containerized Deployments.

• Customers receive an email invitation to onboard to the registry.

• Registry access is secured using authenticated, role-based access control.

• Once onboarded, customers can manage their own access credentials (e.g. access keys or tokens).

These credentials can be used to securely authenticate and pull the required ADOGRC artifacts from the registry via:

• container runtimes (e.g. Docker, containerd, Podman)

• Kubernetes environments

• CI/CD pipelines or deployment automation tools

Air-Gapped Environments​

Container images may be mirrored into internal registries to support restricted or air-gapped environments.

Examples of internal registry solutions include:

• JFrog Artifactory

• Harbor

• Nexus Repository

Updates​

Updates for container images and Helm charts follow the standard ADOGRC release and maintenance process. New versions of the images are published to the OCI container registry as part of official product releases, maintenance updates, or security fixes.

Customers are notified about new releases through the usual communication channels (such as release notes and customer information). Updated images can then be pulled from the registry and deployed according to the customer’s internal deployment and update procedures.

Customers retain full control over when updates are applied in their environments.

System Requirements​

Client Requirements​

The software requirements for the ADOGRC web client remain unchanged compared to previous ADOGRC versions.

Supported Browsers​

Using the latest browser versions is recommended to ensure full functionality and security.

Server Requirements​

Container Runtime​

ADOGRC 15 supports OCI-compliant container runtimes on AMD64 (x86_64) architecture. The following platforms are supported or expected to work:

The BOC Group operates ADOGRC in its own SaaS environment using Kubernetes, and uses Docker and Docker Compose for internal development, testing, and validation. These environments are therefore fully validated.

Platforms classified as "expected to be compatible" are not individually tested or validated but are expected to function correctly if they conform to the respective Kubernetes and OCI standards.

Operating System​

ADOGRC 15 can run on modern Linux distributions that support Kubernetes or Docker/containerd, such as:

• Ubuntu

• Debian

• Red Hat Enterprise Linux (RHEL)

• SUSE Linux Enterprise Server (SLES)

Any modern Linux distribution capable of running the chosen container runtime is expected to be compatible.

Kubernetes and Deployment Tooling​

ADOGRC 15 deployments are typically performed using Kubernetes and Helm.

Database​

ADOGRC requires an external database to store all persistent repository data. Database requirements remain unchanged compared to the previous ADOGRC version. Database requirements are documented in the ADOGRC 15 Hardware/Software Requirements.

Persistent Storage​

Persistent storage is required for the full-text search index and for application log files. Storage is typically provided using Kubernetes Persistent Volumes (PV) and Persistent Volume Claims (PVC), configured via the delivered Helm chart.

Networking​

Container images are distributed via an OCI-compliant registry and accessed over HTTPS.

Typical networking requirements include:

ADOGRC is typically exposed via a Kubernetes Ingress controller, Gateway API controller or an external reverse proxy.

The ADOGRC web server container exposes port 8080 and does not terminate HTTPS connections itself.

For encrypted access (HTTPS), TLS termination must therefore be performed by the Ingress/gateway component in Kubernetes or by a reverse proxy in Docker Compose deployments.

Hardware Requirements​

General Principles​

Hardware requirements for ADOGRC 15 running in containers are broadly comparable to previous Windows-based deployments. The ADOGRC 15 Hardware/Software Requirements provide general hardware sizing recommendations.

Typical Component Resources​

The following values provide typical CPU and memory requirements for each ADOGRC container.

Actual resource usage depends on factors such as:

• number of concurrent users

• size and complexity of the repository

• workflow tasks and reporting activity

• application workload patterns

Deployment Configuration and Setup​

Configuration Approach​

Configuration of ADOGRC 15 follows two complementary mechanisms:

Settings and Configuration Stored Within the Application​

These settings are managed either individually by users or centrally through the ADOGRC Administration. They are stored in the ADOGRC database.

Examples include:

• authentication configuration

• rights administration

• REST API settings

• application-level preferences

Settings and Configuration Read From the Environment​

These settings are read by the application from the runtime environment.

In earlier ADOGRC versions, such settings were stored in .properties or .conf files inside the application server (e.g. server.conf) or web application (e.g. adoxx_web.properties) directories.

With ADOGRC 15, the application is distributed as container images for the application server and the web server. Because containers are ephemeral, file-based configuration is no longer supported.

Instead, all deployment-specific configuration is now injected via environment variables:

• Kubernetes: variables are defined in the values.yaml file and passed to containers when the Helm chart is deployed.

• Docker: variables are defined in docker-compose.yaml and applied when the containers start.

Configuration of the Application Server​

Configuration properties for the application server are provided as environment variables via either:

• the Helm values.yaml file (Kubernetes deployments), or

• the docker-compose.yaml file (Docker deployments)

All application server variables are prefixed with ADOXX_.

The following examples show how to configure the database name and the application worker (aworker) ports.

Kubernetes:

aserver:
  env:
    - name: ADOXX_SERVER_DBNAME
      value: adodb
    - name: ADOXX_SERVER_PORTS
      value: 54321,54322

Docker:

aserver:
  image: ADOGRC.image/aserver
  container_name: aserver
  ...
  environment:
    - ADOXX_SERVER_DBNAME=adodb
    - ADOXX_SERVER_PORTS=54321,54322

Configuration of the Web Server​

Configuration properties for the web server are also provided as environment variables via the values.yaml (Kubernetes) or docker-compose.yaml (Docker) files.

Web server variables are prefixed with AXW_PROPERTIES_.

The following examples show how the used application server and aworker processes are configured and how the maximum size for REST log files is increased to 300MB.

Kubernetes:

webserver:
  env:
    - name: AXW_PROPERTIES_aservers
      value: AS1:ADOGRC.host
    - name: AXW_PROPERTIES_aworkers
      value: AS1:54321,AS1:54322
    - name: AXW_PROPERTIES_axw_logger_appender_rest_maxfilesize
      value: 300MB

Docker:

webserver:
  image: ADOGRC.image/webserver
  container_name: webserver
  ...
  environment:
    - AXW_PROPERTIES_aservers=AS1:ADOGRC.host
    - AXW_PROPERTIES_aworkers=AS1:54321,AS1:54322
    - AXW_PROPERTIES_axw_logger_appender_rest_maxfilesize=300MB

Kubernetes Configuration Example​

The Installation Manual comes with an example of a values.yaml which shows a minimal configuration for deploying ADOGRC: Create the Configuration File. This example will configure:

• one application server instance

• multiple aworkers

• database connection settings

• logging configuration

• runtime parameters

It defines the environment variables for both the application server (aserver) and web server (webserver) components, serving as the input for Kubernetes-based deployment via Helm.

Docker Compose Configuration Example​

You can find an example docker-compose.yaml in our Github repository. This Docker Compose setup deploys ADOGRC with:

• one application server instance

• two aworker ports

• external database connection

• local volume-based logging

• a shared bridge network

Authentication and Identity Integration​

Authentication in ADOGRC is handled at the web application layer and is independent of the underlying operating system. The web application has historically supported operation on multiple platforms, including Linux, Solaris, and Windows.

LDAP and SAML Authentication​

LDAP and SAML authentication are unaffected by the migration to a Linux-based, containerised deployment.

Communication with identity systems uses standard network protocols (LDAP, HTTP, HTTPS), which are operating system-agnostic.

Existing LDAP or SAML configurations can be reused without OS-specific changes.

Configuration Impact​

Because authentication is handled in the web application and relies on OS-independent communication, the move to containerised deployment introduces no functional changes for supported authentication mechanisms.

Only environment-specific adjustments (e.g. hostnames or network settings) may be required.

Upgrade from ADOGRC 13.x/14.x to ADOGRC 15​

The Installation Manual contains a migration guide that will help you upgrade ADOGRC from an older version to version 15.0. The guide contains all the steps that need to be taken, with everything explained in detail:

• Upgrade from ADOGRC 13.0 – 13.6 or 14.0 – 14.4 to ADOGRC 15.0

Security​

Rights and Permissions​

ADOGRC container images do not require root privileges.

All processes inside the containers run under a predefined non-root user (ado).

No additional host-level permissions or elevated Kubernetes privileges are required.

Minimal Image Principle​

ADOGRC container images follow a distroless approach.

Unnecessary operating system components and utilities are removed, reducing the attack surface and enforcing the principle of minimalism.

Cluster Resources​

The ADOGRC deployment does not require privileged containers or global Kubernetes resources. In particular:

• no privileged mode

• no NodePorts

• no Kubernetes Operators

• no cluster-wide access rights

This allows deployment in restrictive enterprise clusters with strict security policies.

Namespaces and Resource Isolation​

All required Kubernetes resources can be deployed and operated entirely within a single namespace.

This supports namespace-level isolation, role-based access control (RBAC), and organisation-specific security frameworks.

Storage Permissions​

Persistent storage is required only for specific components, such as the full-text search index and application logs.

The required Persistent Volumes and Persistent Volume Claims are defined through the Helm chart and do not require elevated cluster permissions.

Access is limited to the ADOGRC application server and web server containers.

Operations​

Scaling​

Horizontal Pod Autoscaling (HPA) is not supported in ADOGRC 15.

Scaling is therefore performed primarily through vertical scaling, by adjusting the CPU and memory resources assigned to the application containers.

The delivered Helm charts support deploying multiple application server instances. As with previous ADOGRC releases, running two or more application servers is supported and recommended to distribute the workload across multiple servers.

Resource allocation should be sized according to:

• expected workload

• number of concurrent users

• overall system usage

Logging and Monitoring​

Logging​

Both the web server and application server containers generate log information for system events and errors.

To enable creation of the Support Information Package (SIP) within ADOGRC, log files are written to persistent storage. A dedicated persistent volume is required for these logs.

The SIP is required for support and troubleshooting.

In addition to file-based logging, ADOGRC also outputs logs via standard container logging streams (stdout/stderr).

This enables integration with external logging solutions such as central log collectors, SIEM platforms, or data lakes.

Log Storage and Retention​

Log files are stored on the configured persistent volume.

Retention, rotation, and rollover behaviour can be configured through the logging setup.

The effective retention period depends on:

• logging configuration

• customer infrastructure

• organisational operational policies

Log Levels​

ADOGRC uses the following log levels:

Log levels behave the same way as in previous Windows-based versions of ADOGRC (ADOGRC 17 and earlier).

Log Configuration​

Logging behaviour can be configured using environment variables provided through:

• values.yaml (Kubernetes)

• docker-compose.yaml (Docker)

Configurable parameters include:

• log level

• maximum file size

• maximum history

• total log size limits

Details on available parameters are described in the configuration section.

Data Protection in Logs​

Sensitive values and personal data written to logs are pseudonymised wherever applicable.

This behaviour is consistent with earlier ADOGRC versions.

Log Output Format​

The general structure of log output remains largely consistent with previous releases.

Some adjustments have been made to improve consistency across different log types.

Monitoring​

Logs Monitoring​

ADOGRC does not provide a built-in logging stack.

Customers are expected to integrate ADOGRC logs into their existing observability or monitoring infrastructure.

ADOGRC supports this through:

• log output via standard container logging mechanisms (stdout/stderr)

• compatibility with common log collection agents (e.g. Fluent Bit)

• forwarding logs to systems such as OpenSearch, Elasticsearch, or similar platforms

In Kubernetes environments, container logs are typically stored temporarily on the node and collected by a log processor before being forwarded to the organisation’s central log system.

Metrics and operational monitoring can be integrated into existing tools such as Prometheus, Grafana, or other enterprise monitoring platforms.

Monitoring Mechanisms​

ADOGRC provides built-in monitoring mechanisms for platform-level health checks.

The delivered container images include functionality used for Kubernetes liveness and readiness probes.

Licensing​

Existing ADOGRC licensing remains valid for all current usage scenarios.

The deployment model, whether Windows-based or containerised, does not affect the applicable licensing terms.

Support & lifecycle​

The introduction of the containerised deployment model does not change the existing ADOGRC support or product lifecycle policies.

All support terms, maintenance services, and lifecycle rules continue to apply as they did for previous ADOGRC versions.