Deployment

How the National Social Registry is packaged as an extension of the Registry Platform, and how to deploy it on Kubernetes.

New home: GitLab. national-social-registry is now developed at github.com/OpenG2P/national-social-registry.

The National Social Registry is not a registry built from scratch. It is a thin extension of the OpenG2P Registry Platform, which publishes the runnable Docker images and the openg2p-registry Helm chart. This repository adds only the NSR domain on top.

The packaging model — why the platform publishes the artifacts and a domain registry extends them — is described once, in the platform docs: Deployment and Extension. This section covers only what is NSR-specific.

How the NSR is packaged

Three layers, each inherited from the platform and narrowed by this repo:

Layer	Platform provides	NSR adds
Code	The runtime images (openg2p-registry-*) — core, APIs, celery, UI	nsr-extension — Individual and Household registers, their sub-registers, schemas, services, seed metadata. Thin FROM-image Dockerfiles select it at runtime via REGISTRY_EXTENSION_MODULE.
Deployment	The openg2p-registry chart — every template, service, IAM/Keycloak wiring	openg2p-nsr — a wrapper chart: a pinned dependency plus a values overlay, and templates only for the analytics/reporting layer. See Helm chart.
Tests	The sanity harness + the extension-independent tests	Only the NSR field-specific tests. See Sanity testing.

The platform version is pinned in two places that move together: RP_VERSION in each Dockerfile (the base image tag) and the openg2p-registry dependency version in the wrapper chart's Chart.yaml. Nothing about the platform is vendored or copied.

• Helm chart — the wrapper chart, what it deploys, and how it is configured.

• Data seeding — the seed content this repo owns and the inherited machinery that applies it.

• Sanity testing — the two-part test model and what the NSR contributes.

Where the artifacts are

Artifact	Location
Source	openg2p/registry/national-social-registry
Helm chart	helm/openg2p-nsr, published to the openg2p/charts GitLab Helm registry
Docker images	openg2p/openg2p-nsr-<name>
Versions & changelog	openg2p-packaging/national-social-registry/CHANGELOG — see Versions

Prerequisites

1. Infrastructure and environment created.

2. Full admin rights to the cluster and the Rancher UI.

3. commons-services deployed in the environment. The registry bundles none of the shared services — Keycloak, master-data, Consent Manager, Partner Management, the Approval Workflow Engine (AWE) and Audit Manager all come from commons-services and are reached through global.* URLs.

The db-seed Job waits for AWE to be healthy before it runs. If AWE is down, db-seed blocks, Helm's install timeout expires, and the release is marked failed before the sanity Job is ever created. Confirm commons-services is healthy first.

Installation

Using Rancher (recommended)

1. Log in to the Rancher console and select the cluster and namespace.

2. Under Apps → Repositories, ensure the OpenG2P catalogue repository is added.

3. Under Apps → Charts, refresh repositories and select OpenG2P National Social Registry.

4. Choose the version. Three-digit versions are frozen; -develop versions are moving — tick Show pre-release versions to see 0.0.0-develop.N.

5. Give the installation a name (the release name is free and scopes the resources, so more than one registry can share a namespace), tick Customize Helm options before install, then Next.

6. Review the values and Install.

The configuration form shows the same questions as the platform chart — they are inherited from the pinned openg2p-registry dependency at packaging time rather than duplicated here, so they never drift. Platform-level settings appear under the registry key; global.* settings are unchanged.

Using Helm CLI

helm dependency update ./helm/openg2p-nsr

helm install nsr ./helm/openg2p-nsr \
  --namespace <namespace> --create-namespace \
  --version <chart-version> \
  --set global.registryHostname=nsr.example.org

Use --devel to resolve a moving 0.0.0-develop.N version.

Post-install check

1. The install runs ordered hook Jobs — db-seed → the sanity seeds → iam-register → sanity → and, when analytics is on, bulk-sample → reporting-views → dashboards. Check they all completed: kubectl -n <namespace> get jobs. Helm stops at the first failure, so a job that never appears means an earlier one failed — see the install sequence for the full order and what each step does.

2. Open <release>.<your-domain> in a browser; you should get the Keycloak login page.

3. Log in with the credentials provisioned by keycloak-init and change the password when prompted.

4. Review the sanity Job logs: kubectl -n <namespace> logs job/<release>-sanity.

Tearing down

helm uninstall leaves behind hook Jobs, PVCs and secrets carrying resource-policy: keep. The repo ships scripts/uninstall-registry.sh, which removes the release, its leftover Jobs and Pods, and the registry databases.

Before going to production

• Leave global.partnerSignatureValidationEnabled and global.consentEnforcementEnabled on (the default) — they govern real PII egress and the chart fails closed. See Helm chart.

• Turn off the sample-data loaders (registry.dbSeed.loadSampleData, loadImages, loadGeoData) — see Data seeding.