> For the complete documentation index, see [llms.txt](https://docs.openg2p.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openg2p.org/products/open-agri-stack/deployment.md).

# Deployment

Installing Agri Stack.

Agri Stack is installed from the OpenG2P Helm charts, through Rancher. These pages are the install steps. How the parts work together: [Architecture](https://docs.openg2p.org/products/open-agri-stack/architecture.md). Managing partners and keys once it runs: [Administration](https://docs.openg2p.org/products/open-agri-stack/administration.md).

## Topology

The reference install runs three namespaces in one Kubernetes cluster. Each namespace is installed as a separate organisation, with its own commons, and calls the others only through their public hostnames.

<figure><img src="https://3034178245-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJZcdob2emEcLMvLyIxqT%2Fuploads%2Fgit-blob-0c82f06fca1b1ad75fbea4328c7be035ae5b17c3%2Fopen-agri-stack-deployment-topology.svg?alt=media" alt="Reference topology: one Kubernetes cluster with three namespaces, each installed as a separate organisation with its own commons. trial: the Farmer Registry; dept1: the Crop Sown Registry; agrix: the Exchange, with the Composite. Partners call the Composite; the Composite calls each registry by its public hostname, through the ingress."><figcaption><p>The reference topology</p></figcaption></figure>

| Namespace | Install                                          | Charts                                             |
| --------- | ------------------------------------------------ | -------------------------------------------------- |
| `trial`   | The **Farmer Registry** (Agriculture Department) | Commons Base, Commons Services, Farmer Registry    |
| `dept1`   | The **Crop Sown Registry** (Crops Department)    | Commons Base, Commons Services, Crop Sown Registry |
| `agrix`   | The **Exchange**                                 | Commons Base, Commons Services, Composite          |

Each namespace has its own domain on the `internal` gateway (`*.trial.openg2p.org`, `*.dept1.openg2p.org`, `*.agrix.openg2p.org`), with DNS and TLS. The names are examples: any work. Departments on their own clusters: [Separate Clusters](https://docs.openg2p.org/products/open-agri-stack/deployment/separate-clusters.md).

## Prerequisites

| What                                                                | Where                                                                                                                                                |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| A Kubernetes cluster with Rancher, Istio and the `internal` gateway | [Infrastructure setup](https://docs.openg2p.org/operations/deployment/infrastructure-setup.md)                                                       |
| One namespace per install, with its domain, DNS and TLS             | [Environment setup](https://docs.openg2p.org/operations/deployment/infrastructure-setup/environment-setup-multi-node.md)                             |
| The OpenG2P chart repository in Rancher (**Apps → Repositories**)   | [Commons Helm chart](https://docs.openg2p.org/operations/deployment/infrastructure-setup/environment-setup-multi-node/openg2p-commons-helm-chart.md) |
| For the test: `kubectl` and Python 3 on the operator's machine      | [Testing](https://docs.openg2p.org/products/open-agri-stack/deployment/testing.md)                                                                   |

## What the install sets up

| What                                                                                                                                                  | Done by                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| The Composite's signing key (Secret `agri-composite-signing`) and its public keys at `https://agri-composite.<Exchange domain>/.well-known/jwks.json` | The Composite chart                                           |
| The Composite onboarded in each department's Partner Management, its keys read from that URL, with no policy                                          | Commons Services (Partner Management), from **Exchange Role** |
| Trust between the Consent Managers: the Exchange CM issues consent tokens, each department CM accepts them                                            | Commons Services (Consent Manager), from **Exchange Role**    |
| The partner portal's Keycloak realm, client, roles and `partner_id` attribute                                                                         | Commons Services (Consent Manager), with **Partner Portal?**  |

Because each Partner Management reads the Composite's key when needed, the departments and the Exchange can be installed in either order. Left to people, by design: what each department releases to the Composite, and which partners may use which use cases ([Administration](https://docs.openg2p.org/products/open-agri-stack/administration.md)).

## Install steps

<figure><img src="https://3034178245-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJZcdob2emEcLMvLyIxqT%2Fuploads%2Fgit-blob-b1c2e1e4a86f37db5e812000aa0f1688fb06f65f%2Fopen-agri-stack-install-order.svg?alt=media" alt="Install steps: the registries, each in its own namespace with its commons, and the Exchange with its commons and the Composite, in either order; then each department releases its registry&#x27;s data to the Composite in its Partner Management; then the test script."><figcaption><p>Install steps</p></figcaption></figure>

| # | Step                                                                                                                                                  | Page                                                                                                                                                                                                         |
| - | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1 | Install the registries: Farmer Registry in `trial`, Crop Sown Registry in `dept1`                                                                     | [Farmer Registry](https://docs.openg2p.org/products/open-agri-stack/deployment/farmer-registry.md), [Crop Sown Registry](https://docs.openg2p.org/products/open-agri-stack/deployment/crop-sown-registry.md) |
| 2 | Install the Exchange in `agrix`: Commons Base, Commons Services, the Composite                                                                        | [Exchange](https://docs.openg2p.org/products/open-agri-stack/deployment/exchange.md)                                                                                                                         |
| 3 | In each department's Partner Management, add the Composite's scope policy for its registry. Until then the registry releases nothing to the Composite | [Releasing Registry Data to the Composite](https://docs.openg2p.org/products/open-agri-stack/administration/releasing-data-to-the-composite.md)                                                              |
| 4 | Run the test                                                                                                                                          | [Testing](https://docs.openg2p.org/products/open-agri-stack/deployment/testing.md)                                                                                                                           |

* Steps 1 and 2 can come in either order. Registries usually exist already; upgrading their Commons Services with **Exchange Role** `department` is then step 1.
* Start each install once the one before it in the same namespace is ready: releases `deployed`, all pods running (`helm -n <ns> list`, `kubectl -n <ns> get pods`).
* Every install loads the same country pack (Commons Services default `ETH`; it carries a [licence obligation](https://docs.openg2p.org/platform/platform-services/master-data-service/country-packs.md#sources-and-licence)).
* For a test install, step 4 adds the step 3 policies itself, for the use case it tests.
* Before going live: [Production](https://docs.openg2p.org/products/open-agri-stack/deployment/production.md).

## Settings that must agree across installs

Each install is configured on its own, yet some values are used by more than one install: the Exchange and the departments recognise each other by them. The defaults already agree, so a default install sets none of them. If you change one, change it in every install listed.

| Setting              | Default                                 | Must match in                                                                                                                                                                 |
| -------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Composite partner ID | `agri-composite`                        | The Composite; its Partner Management entry `PARTNER_AGRI_COMPOSITE` in every install; the token presenter at the Exchange CM and the trusted presenter at the department CMs |
| Composite hostname   | `agri-composite.<Exchange domain>`      | The departments' Partner Management reads the Composite's keys there (**Composite JWKS URL** otherwise)                                                                       |
| Consent token issuer | `agri-stack-exchange-cm`                | The Exchange CM (issuer); the department CMs (trusted issuer)                                                                                                                 |
| Data controllers     | `farmer-registry`, `crop-sown-registry` | Each registry; the Composite's registries; consents; Partner Management scope policies                                                                                        |
| Subject ID types     | `FAYDA_FAN`, `FARMER_ID`                | Use cases, Partner Management policies (Master Data list `SUBJECT_ID_TYPE`), consents. The registries map the DCI type `UIN` to `FAYDA_FAN`                                   |
| Purposes             | `credit-assessment`                     | Use cases, Partner Management policies (Master Data list `CONSENT_PURPOSE`), consents                                                                                         |
| Exchange domain      | `agrix.<parent domain>`                 | The department CMs read the Exchange CM's public keys there, and their Partner Management the Composite's                                                                     |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openg2p.org/products/open-agri-stack/deployment.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
