Configuration Reference

An on-premise installation is configured in three files, each holding a different kind of value. Knowing which file owns what is most of the work.

File	Holds	In version control?
`ansible/group_vars/all/vault.yml`	Secrets: passwords, keys, tokens	No — encrypted with `ansible-vault`, git-ignored
`values-<client>.yaml`	Helm values: images, hostnames, resources	No — git-ignored, one per deployment
`ansible/inventory/hosts.ini`	The target host and deployment-wide variables	No — git-ignored

All three are per-deployment and all three stay out of the repository. A values file committed to the repo becomes the file the next installation is accidentally run against.

The Vault

Copy ansible/group_vars/all/vault.example.yml to vault.yml, fill it in, and encrypt it. Every top-level key becomes one Kubernetes Secret in the release namespace.

`root-services`

Key	What it is
`app_url`	The platform’s own URL — `https://<your hostname>`.
`ip_geo_location_url`, `ip_location_key`	Geo-IP lookup for the audit trail. Supplied by you or left pointing at a service you run.
`better_auth_secret`	Signing secret for sessions. Generate a long random string; changing it invalidates every session.
`externalApiUsername`, `externalApiPassword`	Credentials for the platform’s outbound integrations.
`internal_service_token`	Shared secret for service-to-service calls inside the cluster. Generate randomly.

`database`

Five connection strings, one per database. In Scenario C the installer creates all five on the host it provisions; in Scenario B you point them at your own endpoint.

Key	Database
`dbauth`	Identity, organisations, files, vaults
`dbmail`	Outbound email
`dbManagement`	Platform management
`dbSmartContracts`	Smart contracts and anchoring
`dbNotifications`	In-app notifications

Scenario C also needs vault_postgres_passwords, a separate top-level block naming one password per role:

vault_postgres_passwords:
  dbauth: "..."
  dbmail: "..."
  dbManagement: "..."
  dbSmartContracts: "..."
  dbNotifications: "..."

The installer applies exactly these with ALTER ROLE; it never generates its own. Re-running an install therefore re-asserts what your vault says rather than rotating anything behind your back, which is also what makes rotating a password a matter of editing the vault and re-running.

`aws-bucket`

Object storage. In an on-premise installation this is MinIO running in your cluster, not AWS — the key names are historical.

Key	What it is
`BUCKET_NAME`	The bucket the platform writes to. Created on first start. Must be a valid S3 bucket name: lowercase, 3–63 characters, no underscores.
`PUBLIC_ACCESS_KEY`	MinIO root user. Minimum 3 characters or MinIO refuses to start.
`PRIVATE_ACCESS_KEY`	MinIO root password. Minimum 8 characters, same.
`S3_REGION`	The region MinIO is started with and the applications sign requests against.
`CLOUDFRONT_ID`	Unused on-premise. Present because the same configuration module serves both deployments.

BUCKET_NAME is one of the keys the value gate does not type-check. A CHANGE_ME left here passes the gate, and the installation then fails at the MinIO Ingress precondition — which is loud and early, but only because that check was added for exactly this.

`control-plane`

Key	What it is
`deployment_id`	The UUID ROOTKey issues for this deployment. The gate rejects anything that is not a UUID.
`enrollment_token`	One-time token that enrols the deployment with the Control Plane.

The rest

Secret	Holds	Notes
`redis`	`host`, `password`	In-cluster Redis.
`kafka`	`brokers`, `username`, `password`	In-cluster Kafka, SASL.
`email`	`host`, `port`, `user`, `password`	SMTP.
`blockchain`	`RPC_URL`, `TESTNET_RPC_URL`, `WEB3_API_KEY`, `TESTNET_WEB3_API_KEY`	Where anchoring transactions are sent. Yours or ours — see below.
`azure`	`clientId`, `tenantId`	Azure AD, when used for staff access.
`social-providers`	Microsoft, Google and LinkedIn client id/secret pairs	Yours, not ours. Register your own applications; their redirect URIs point at your hostname.
`observability`	`log_level`
`container-config`	`port`, `env`	Leave `port` at `3333`. See the warning below.

Social sign-in is optional and per-provider. A deployment that configures none simply does not offer social sign-in — the providers are registered only when configured, rather than half-registered with empty credentials.

container-config.port must stay 3333. It looks like a free choice and it is not.Twenty-one of the twenty-two workloads take their listening port from this one value, via BACKEND_PORT, and the chart pins containerPort: 3333 against it. Change it and every one of them listens where its own Service does not point.What makes it expensive is how it fails. Most of those workloads have no liveness or readiness probe, so they come up, report Running, and serve nothing. Only one workload is instrumented, and it is the only reason the misconfiguration is visible at all — it fails its probe, restarts, and keeps restarting. We hit this with a value of 3000: twenty workloads looked healthy, one restarted 231 times, and the install timed out waiting for a deployment that could never become ready.The shipped vault.example.yml already has the right value. Copy it rather than retyping it.

Who owns the blockchain endpoint

The blockchain values can be yours or ROOTKey’s, and it is a deliberate choice rather than a default:

You want	You supply
To run the blockchain infrastructure yourself	Your own RPC endpoints and Web3 API keys. Anchoring traffic leaves your perimeter only towards a node you control.
To delegate it to ROOTKey	Endpoints and keys ROOTKey provides. One fewer piece of infrastructure to operate, at the cost of an outbound dependency on it.

Either way the wallet that signs stays inside your deployment: the RPC endpoint is where transactions are sent, not who signs them. Decide this during scoping, because it changes both the egress allowlist and who is responsible for the node’s availability.

Three top-level keys, outside `rootkey_secret_data`

Everything above lives under rootkey_secret_data and becomes a Kubernetes Secret. These do not — they sit at the top level of the same file and are read by the installer itself. Miss them and the install fails while pulling the first image.

vault_image_pull_registry: "rootkeydist.azurecr.io"   # already correct — do not change it
vault_image_pull_username: "<from ROOTKey>"
vault_image_pull_password: "<from ROOTKey>"

These are the registry credentials from your delivery record. They become the rootkey-registry pull secret that every workload references.

vault_image_pull_registry ships with the right value and is the one of the three that looks filled in and is not checked as carefully as the other two. Leave it alone — a changed hostname produces a pull secret registered for a registry nobody pulls from, and the resulting ImagePullBackOff names the image rather than the secret.

And, in Scenario C only, where the installer creates the PostgreSQL databases itself:

vault_postgres_passwords:
  dbauth: "..."
  dbmail: "..."
  dbManagement: "..."
  dbSmartContracts: "..."
  dbNotifications: "..."

One per line, never reused across deployments — openssl rand -base64 24. In this mode the installer builds each connection string from the node address plus these, which is why the database block above may keep its placeholders.

Licensing

The licence is issued by the Control Plane at rootkey_control_plane_url, and is fetched and renewed over that link.

Offline licensing — in development. Licence delivery for deployments with no Control Plane link is being built, with its own issuing and verification path.In the meantime there is nothing to configure for it in the vault.If your deployment is air-gapped, raise licensing with ROOTKey during scoping. It is a conversation to have before the install rather than after, and we will tell you where the offline path stands for your timeline.

The Helm Values File

Copy helm/values-onprem.example.yaml. Everything below is per-deployment.

Images

Every one of the 22 workloads needs a real repository and tag. The tag is the released commit SHA of that service, which ROOTKey publishes with each release.

auth-service:
  image:
    repository: <registry>/auth-service
    tag: "68a44018e520d96b3c595d3c6f49db2a6466f4c7"
  imagePullSecrets:
    - name: rootkey-registry

The value gate rejects <commit-sha>, registry.example.com and CHANGE_ME in any image field.

The file base URL

global:
  envOverrides:
    PUBLIC_FILE_BASE_URL: https://rootkey.acme.example/files

This is where a browser fetches a stored file from. It reaches every workload that declares the variable.

Getting this wrong is the single most common way an installation “succeeds” and is unusable. Every pod is Ready, Helm reports success, users register, files upload and anchor — and then no avatar, logo, file link or compliance report opens, with nothing in any log, because the URL is only ever dereferenced by the user’s browser and never reaches the cluster.

Three rules:

The host must be the same as the platform frontend Ingress host, and the same as rootkey_public_host.
The path must be /files.
Do not include the bucket name. The MinIO Ingress prepends it from the vault.

Ingress

platform-frontend:
  ingress:
    enabled: true
    className: nginx
    hosts:
      - host: rootkey.acme.example
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: rootkey-tls
        hosts:
          - rootkey.acme.example

The TLS Secret must already exist in the namespace. There is no ACME issuer.

Resources

The CPU and memory limits shipped in the chart are sized for the multi-tenant cloud, where a tight per-pod limit stops one customer starving another. An on-premise box is the opposite: it is dedicated to one client, and the same limit becomes a brake with no beneficiary.

This is measured, not estimated. On an eight-core box at 16% utilisation, a service limited to 200m accumulated 84 throttling events and 4.69 seconds of throttled time during a 3-second test, with 6.7 cores idle beside it. The visible symptom is file creation timing out after five seconds on a machine that looks unloaded.

Raise the limits in your values file. The example file ships with values already raised for a dedicated host and explains each one.

The Inventory

ansible/inventory/hosts.ini — the target, plus variables that belong to the deployment rather than to Helm.

[rootkey]
acme-node-1 ansible_host=10.0.0.10 ansible_user=rootkey ansible_ssh_private_key_file=~/.ssh/acme

[rootkey:vars]
rootkey_region=eu-lisbon
rootkey_tenant=acme
rootkey_public_host=rootkey.acme.example
rootkey_deployment_tenancy=single-tenant

Variable	What it is
`rootkey_public_host`	The platform hostname. The MinIO chart is a separate top-level chart with no values file, so this is the only place it can learn the host.
`rootkey_deployment_tenancy`	`single-tenant` or `multi-tenant`. Required — the install stops without it. See below.
`rootkey_region`, `rootkey_tenant`	Data-residency labels. They surface in the install manifest for audit.

rootkey_deployment_tenancy has no default, on purpose, and the deploy stage asserts it. An install without it stops with a message naming the variable, rather than guessing.There is no safe default because both values are wrong for somebody and neither failure announces itself. A direct client left on multi-tenant never gets the licence’s plan materialised, so registration falls through to a local path and the deployment appears to work until somebody looks at what plan the users are on.If you are unsure which you are, it is in your contract — ask before installing rather than picking one.

Values set here win over ansible/group_vars/all/main.yml, which ships with rootkey_public_host empty. That file is shared and versioned; the inventory is yours.

Deployment-Wide Variables

Set in ansible/group_vars/all/main.yml, or overridden per deployment with -e KEY=VALUE.

Variable	Default	What it controls
`rootkey_namespace`	`rootkey`	The Kubernetes namespace everything installs into.
`rootkey_redis_in_cluster`	`true`	Set false only when you supply your own Redis.
`rootkey_kafka_in_cluster`	`true`	Same, for Kafka.
`rootkey_minio_in_cluster`	`true`	Set false only when you supply your own S3-compatible endpoint.
`rootkey_minio_ingress_enabled`	`true`	Publishes stored files at `<host>/files`. Turn off only when something else already fronts MinIO.
`rootkey_tls_secret_name`	`rootkey-tls`	The Secret holding the certificate for `rootkey_public_host`.
`rootkey_control_plane_url`	`https://control-api.rootkey.ai`	Where the deployment enrols and renews its licence.
`rootkey_control_plane_endpoints`	`control-api.rootkey.ai`	The host the firewall rule needs. Must contain the host of the URL above.
`rootkey_contract_seed_enabled`	`true`	Seeds the smart contracts. With this off, creating a file returns 500.

→ Next: Verification

Introduction

Quickstart

Connectors

Integrations

Ecosystem Guides

Protocols

RKP-1 - Full On-Chain

RKP-2 - Off-Chain

RKP-3 - Hybrid

Data Sovereignty

Data Retention

Deployment Methods

On-Premise Installation

Developer Resources

Additional Resources

Configuration Reference

The Vault

`root-services`

`database`

`aws-bucket`

`control-plane`

The rest

Who owns the blockchain endpoint

Three top-level keys, outside `rootkey_secret_data`

Licensing

The Helm Values File

Images

The file base URL

Ingress

Resources

The Inventory

Deployment-Wide Variables

​The Vault

​root-services

​database

​aws-bucket

​control-plane

​The rest

​Who owns the blockchain endpoint

​Three top-level keys, outside rootkey_secret_data

​Licensing

​The Helm Values File

​Images

​The file base URL

​Ingress

​Resources

​The Inventory

​Deployment-Wide Variables

The Vault

`root-services`

`database`

`aws-bucket`

`control-plane`

The rest

Who owns the blockchain endpoint

Three top-level keys, outside `rootkey_secret_data`

Licensing

The Helm Values File

Images

The file base URL

Ingress

Resources

The Inventory

Deployment-Wide Variables