# Deployment Options

ODD Platform and ODD Collector ship with several supported deployment paths. This page is the entry point: it lists every option, what each is for, and where the deep-dive lives. For configuration details after deployment, the canonical reference is [Configure ODD Platform](/configuration-and-deployment/odd-platform.md); per-collector / per-adapter detail lives under the [Integrations hub](/integrations/integrations.md).

## Choose your option

| # | Option                                      | Use case                                             | Components                                                      | Persistence                                   | Production-ready?                                        | Deep-dive                                                                                                                                                                                     |
| - | ------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | **Docker Compose**                          | Local evaluation / demo on a workstation             | Platform + Collector + sample PostgreSQL                        | Container-local volumes                       | No — evaluation only                                     | [Try locally](/configuration-and-deployment/trylocally.md)                                                                                                                                    |
| 2 | **Helm on self-managed Kubernetes**         | Production deployments on a cluster you operate      | Platform + Collector (separate releases)                        | External PostgreSQL (recommended)             | Yes — when you supply persistent PostgreSQL              | [opendatadiscovery/charts](https://github.com/opendatadiscovery/charts)                                                                                                                       |
| 3 | **Helm Quick Launch (all-in-one)**          | Demo / staging on Kubernetes; AWS Marketplace launch | Platform + bundled Bitnami PostgreSQL (sub-chart)               | Bundled PostgreSQL pod (ephemeral by default) | No — bundled DB is not persistent in the default config  | [`odd-quicklaunch` chart](https://github.com/opendatadiscovery/charts/tree/main/charts/odd-quicklaunch)                                                                                       |
| 4 | **AWS EKS via CloudFormation Quick Launch** | One-click EKS deployment in a supported AWS region   | EKS cluster + bundled Bitnami PostgreSQL + Platform + Collector | Bundled PostgreSQL pod (ephemeral by default) | No — demo-grade; HTTPS not configured, DB not persistent | [Deploy to Amazon Elastic Kubernetes Service (EKS)](/configuration-and-deployment/quick_launch_on_amazon_elastic_kubernetes_service.md)                                                       |
| 5 | **Build from source**                       | Contributors and deep customisation                  | Platform + Collector built locally                              | Operator's choice                             | Yes — when paired with a production runtime              | [Build and run ODD Platform](/developer-guides/build-and-run/build-and-run-odd-platform.md) + [Build and run ODD Collectors](/developer-guides/build-and-run/build-and-run-odd-collectors.md) |

The optional `odd-tracing-gateway` is **not** one of these deployment paths — it is a separate Push adapter (standalone gateway shape) that operators deploy **alongside** the Platform when their stack already collects OpenTelemetry traces and they want microservice identities catalogued automatically. See [`odd-tracing-gateway`](/integrations/integrations/odd-tracing-gateway.md) under Integrations for the operator-facing setup, configuration, and caveats.

## Option 1: Docker Compose (local / demo)

{% hint style="info" %}
**Status: Evaluation only.** Container-local volumes; no operator-managed persistence; not for production. Use this to try the platform end-to-end on a workstation in a few minutes.
{% endhint %}

### When to use it

* You want to evaluate ODD without provisioning infrastructure.
* You're a contributor running the stack locally during development.
* You want a sample data source pre-loaded so the catalog isn't empty on first open.

### Prerequisites

* Docker Engine 19.03.0+
* `docker-compose` (latest)
* Free local ports `8080` (Platform UI / API) and `5432` (sample PostgreSQL)

### Install

1. Clone the platform repo: `git clone https://github.com/opendatadiscovery/odd-platform.git`
2. From the project root, start the demo stack with the bundled enricher:

   ```bash
   docker-compose -f docker/demo.yaml up -d odd-platform-enricher
   ```
3. Open the UI at <http://localhost:8080/>.

### Verify

* Visit <http://localhost:8080/management/datasources> — you should see \~10 predefined data sources from the bundled sample.
* Visit the **Catalog** tab — the metadata sample should be visible.

### Deep dive

* [Try locally](/configuration-and-deployment/trylocally.md) — full walkthrough including the Collector → token → `collector_config.yaml` workflow for connecting your own data source.

### Known gotchas

* Data persists only as long as the named Docker volumes do; `docker-compose down -v` wipes the catalog.
* The bundled enricher is for first-impression sample data; it should not be left running long-term against a real catalog.

## Option 2: Helm on self-managed Kubernetes

{% hint style="success" %}
**Status: Production-ready** — when you supply your own PostgreSQL with persistent storage, configure ingress / TLS, and run the bundled charts on a cluster you operate.
{% endhint %}

### When to use it

* You operate a Kubernetes cluster (self-managed, EKS, GKE, AKS, on-prem) and want long-lived ODD installations on it.
* You need to wire ODD to an existing managed PostgreSQL (RDS, Cloud SQL, Aurora, on-prem).
* You want independent release cadences for Platform and Collector(s) — they are separate charts.

### Prerequisites

* A Kubernetes cluster you have admin access to (`kubectl get nodes` succeeds).
* [Helm 3](https://helm.sh/docs/intro/install/) installed locally.
* A reachable PostgreSQL instance for the Platform (operator-supplied — bundled PostgreSQL is **not** included in this chart; that's Option 3).

### Install

1. Add the chart repo:

   ```bash
   helm repo add opendatadiscovery https://opendatadiscovery.github.io/charts
   helm repo update
   ```
2. Install the Platform with your PostgreSQL connection details:

   ```bash
   helm install odd-platform opendatadiscovery/odd-platform \
     --set config.yaml.spring.datasource.username=<your_pg_user> \
     --set config.yaml.spring.datasource.password=<your_pg_password> \
     --set config.yaml.spring.datasource.url="jdbc:postgresql://<pg_host>:5432/<db_name>"
   ```
3. Create a Collector entity in the Platform UI (**Management → Collectors**) and copy the issued token.
4. Install the Collector with that token wired into `collectorConfig`:

   ```bash
   helm install odd-collector opendatadiscovery/odd-collector \
     --set image.repository=ghcr.io/opendatadiscovery/odd-collector \
     --set-file collectorConfig=./your-collector-config.yaml
   ```

   Replace `./your-collector-config.yaml` with a `collector_config.yaml` matching the [per-adapter reference](/integrations/integrations/odd-collector.md) for the data sources you want to ingest. Mount sensitive values via `passwordSecretsEnvs` rather than baking them into the YAML.

### Minimal example: external PostgreSQL

```yaml
# odd-platform-values.yaml
config:
  yaml:
    spring:
      datasource:
        username: odd-platform
        password: !ENV ${PG_PASSWORD}
        url: "jdbc:postgresql://pg.internal.example.com:5432/odd-platform"
service:
  type: ClusterIP        # use LoadBalancer / Ingress for external access
ingress:
  enabled: true
  className: nginx
  hosts:
    - host: odd.example.com
      paths:
        - path: /
          pathType: Prefix
```

Apply with `helm install odd-platform opendatadiscovery/odd-platform -f odd-platform-values.yaml`.

### Verify

* `kubectl get pods` — every Platform pod is `Running`.
* `kubectl logs deploy/odd-platform | head` — no datasource-connection errors.
* Open the configured ingress / LoadBalancer URL — the UI loads.

### Deep dive

* [opendatadiscovery/charts → README](https://github.com/opendatadiscovery/charts) — chart-repo usage (add, install, uninstall).
* [`odd-platform` chart values](https://github.com/opendatadiscovery/charts/tree/main/charts/odd-platform) — full `values.yaml` reference.
* [`odd-collector` chart values](https://github.com/opendatadiscovery/charts/tree/main/charts/odd-collector) — Collector chart reference (image, `collectorConfig`, `env` overrides, secret-env injection via `passwordSecretsEnvs`).
* [Configure ODD Platform](/configuration-and-deployment/odd-platform.md) — every Platform-side `application.yml` key and how it maps to `config.yaml.*` Helm values.
* [Build a custom collector](/developer-guides/build-and-run/custom-collectors.md) — when the bundled adapters don't fit and you need a custom Collector image.

### Known gotchas

* **External PostgreSQL is not a chart concern.** The `odd-platform` chart points at the URL you give it; bring-up assumes the database exists, the user has rights, and the schema can be created. Test connectivity from a debug pod (`kubectl run pg-test --rm -it --image=postgres:15 -- psql -h pg.internal.example.com -U odd-platform`) before installing the chart.
* **Chart versions**: don't pin `--version` to a stale release. `helm repo update` and let Helm pick the latest unless you have a reason to lock — the charts are versioned in `Chart.yaml` (`odd-platform` 0.1.10 at the time of writing).
* **Image tag** defaults to `latest` per the chart's `appVersion` — pin `image.tag` explicitly in production to avoid surprise upgrades on pod restart.
* **Ingress is off by default** (`ingress.enabled: false`); set it explicitly with your cluster's ingress controller class and TLS configuration.
* **Upgrade / rollback**: `helm upgrade odd-platform opendatadiscovery/odd-platform -f odd-platform-values.yaml` for upgrades, `helm rollback odd-platform <revision>` for rollback. Always run `helm diff upgrade` (via the [helm-diff plugin](https://github.com/databus23/helm-diff)) on production releases first.

## Option 3: Helm Quick Launch (all-in-one)

{% hint style="warning" %}
**Status: Demo / staging only.** The bundled Bitnami PostgreSQL sub-chart runs as a single pod with `persistence.enabled: false` by default — restarting the pod erases the catalog. Graduate to Option 2 with an external persistent PostgreSQL before going to production.
{% endhint %}

### When to use it

* You want a one-command Platform deployment on a Kubernetes cluster for staging or a longer-running demo.
* You're publishing through AWS Marketplace, where this chart is the QuickLaunch delivery method.
* You don't yet have a managed PostgreSQL and want to evaluate the Platform first.

### Prerequisites

* A Kubernetes cluster (managed or self-managed).
* Helm 3.

### Install

```bash
helm repo add opendatadiscovery https://opendatadiscovery.github.io/charts
helm repo update
helm install odd-quicklaunch opendatadiscovery/odd-quicklaunch \
  --set global.postgresql.auth.postgresPassword=<choose-a-strong-password> \
  --set global.platformServiceType=LoadBalancer \
  --set global.loadBalancerSourceRanges=<your-cidr>/32
```

The single command installs:

* `odd-platform` — the Platform application.
* `postgresql` (Bitnami sub-chart, version `13.2.9`) — bundled database.

### Verify

* `kubectl get pods` — both `odd-quicklaunch-odd-platform-*` and `odd-quicklaunch-postgresql-*` pods are `Running`.
* `kubectl get svc odd-quicklaunch-odd-platform` — note the LoadBalancer external IP / hostname.
* Open `http://<external-ip-or-hostname>/` in your browser — the UI loads. **HTTP only** in this configuration; do not send sensitive data over it.

### Deep dive

* [`odd-quicklaunch` chart](https://github.com/opendatadiscovery/charts/tree/main/charts/odd-quicklaunch) — chart source, including the AWS Marketplace QuickLaunch override-parameter mapping.

### Known gotchas

* **PostgreSQL is non-persistent by default** (`postgresql.primary.persistence.enabled: false` in the chart's `values.yaml`). A pod restart wipes the data.
* **HTTPS is not configured.** The default service is a LoadBalancer over plain HTTP. Don't ingest production credentials.
* **No Collector is bundled.** Add a separate `odd-collector` install (Option 2) to actually ingest metadata.
* **Chart version drift.** The Quick Launch chart bundles a pinned `odd-platform` sub-chart version — when you `helm upgrade`, both move together; check the [Chart.yaml](https://github.com/opendatadiscovery/charts/blob/main/charts/odd-quicklaunch/Chart.yaml) for the dependency pin.

## Option 4: AWS EKS via CloudFormation Quick Launch

{% hint style="warning" %}
**Status: Demo-grade.** Provisions an EKS cluster with bundled non-persistent PostgreSQL over HTTP only. Excellent first-look on AWS; not a production posture.
{% endhint %}

### When to use it

* You want to try ODD on AWS without provisioning EKS yourself.
* You're already on one of the supported AWS regions.

### Prerequisites

* An AWS account with permissions to create CloudFormation stacks, EKS clusters, and EC2 nodes.
* You're operating in one of the supported regions: **us-west-2, us-west-1, us-east-2, us-east-1**. Other regions require manual EKS provisioning (Option 2).

### Install

The CloudFormation template is hosted at `https://odd-ct-templates.s3.us-east-2.amazonaws.com/odd_cloudformation.yaml`. Launch from the AWS console with that template URL — full step-by-step (cluster setup, node group, role, post-deploy access via `kubectl`, Bitnami PostgreSQL install, Platform install, Collector install with token wiring) lives on the dedicated EKS page below.

### Verify

* `kubectl get pods` shows `odd-platform-*`, `postgresql-*`, and `odd-collector-*` pods all `Running`.
* `kubectl get svc odd-platform -o=custom-columns=EXTERNAL-IP:.status.loadBalancer.ingress[0].hostname` returns the public hostname.
* `http://<load-balancer-hostname>/` loads the UI (HTTP only — see gotchas).

### Deep dive

* [Deploy to Amazon Elastic Kubernetes Service (EKS)](/configuration-and-deployment/quick_launch_on_amazon_elastic_kubernetes_service.md) — the canonical AWS onboarding walkthrough; covers the Quick Launch flow, kubectl auth, Bitnami PostgreSQL install, Platform install, Collector install with the `collector-values.yaml` pattern.
* [`charts/QUICKSTART.md`](https://github.com/opendatadiscovery/charts/blob/main/QUICKSTART.md) — same walkthrough on the chart repo.
* [`charts/cloudformation/odd_cloudformation.yaml`](https://github.com/opendatadiscovery/charts/blob/main/cloudformation/odd_cloudformation.yaml) — the CloudFormation template itself.

### Known gotchas

* **HTTP only** — the LoadBalancer is plain-HTTP. Don't send sensitive data over it. For production, terminate TLS at an Ingress / ALB or graduate to Option 2 with HTTPS.
* **PostgreSQL is non-persistent** — the Bitnami chart is installed with `primary.persistence.enabled=false`.
* **Region restriction** — only `us-west-2`, `us-west-1`, `us-east-2`, `us-east-1` are supported by the CloudFormation template. For other regions, do Option 2 by hand.
* **Cleanup costs** — leaving the EKS cluster running incurs AWS charges. `helm uninstall odd-platform` then [delete the CloudFormation stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html) when you're done.
* **Token regeneration** — if you don't securely store the Collector token issued by the Platform UI, you must regenerate it; the original is not recoverable from the platform.

## Option 5: Build from source / developer deployment

{% hint style="info" %}
**Status: Contributor / customisation path.** Build artefacts from source for development or to ship a customised image. Not the standard operator path.
{% endhint %}

### When to use it

* You're contributing to ODD Platform or Collector and need to run a build locally.
* You want to customise the Platform or Collector beyond what the charts expose (custom image, code patches).
* You want to test an unreleased branch before it ships as a chart.

### Prerequisites

Per [Build and run ODD Platform](/developer-guides/build-and-run/build-and-run-odd-platform.md) — Java 17, Gradle, Node, Docker. Per [Build and run ODD Collectors](/developer-guides/build-and-run/build-and-run-odd-collectors.md) — Python 3.9 or higher, Poetry 1.2.0, Docker.

### Install

* Platform: see [Build and run ODD Platform](/developer-guides/build-and-run/build-and-run-odd-platform.md) for the gradle build and Docker image steps.
* Collector: see [Build and run ODD Collectors](/developer-guides/build-and-run/build-and-run-odd-collectors.md) for the Poetry / Docker flow per sub-collector.
* Custom Collector authoring: [Build a custom collector](/developer-guides/build-and-run/custom-collectors.md) — when an existing adapter doesn't fit.

### Deep dive

* [Build and run ODD Platform](/developer-guides/build-and-run/build-and-run-odd-platform.md)
* [Build and run ODD Collectors](/developer-guides/build-and-run/build-and-run-odd-collectors.md)
* [Build a custom collector](/developer-guides/build-and-run/custom-collectors.md)

### Known gotchas

* The build paths are validated for the Linux / macOS path; Windows users typically run via WSL2.
* M1 / Apple Silicon collector builds need extra environment variables for `pyodbc`, `confluent-kafka`, and `grpcio` — see the [build-and-run troubleshooting section](/developer-guides/build-and-run/build-and-run-odd-collectors.md#troubleshooting).

## Optional companion: `odd-tracing-gateway`

`odd-tracing-gateway` is an optional companion service that bridges OpenTelemetry distributed tracing into the ODD catalog — operator microservices push OpenTelemetry traces to the gateway, and the gateway exposes the inferred service entities for the Platform to pull. It is **not** an alternative to the deployment options above; it sits beside the Platform as a separate process (the Push adapter / standalone gateway shape in the [adapter taxonomy](/introduction/main-concepts.md#the-architecture-chain)).

For installation (Helm or Docker Compose), the configuration reference, the API surfaces (inbound OTLP and outbound entities), and the operator caveats, see [`odd-tracing-gateway`](/integrations/integrations/odd-tracing-gateway.md) under Integrations — that page is the canonical home.

## Still stuck?

* File an issue against the relevant repo:
  * [opendatadiscovery/odd-platform](https://github.com/opendatadiscovery/odd-platform/issues) — Platform bugs and feature requests
  * [opendatadiscovery/odd-collectors](https://github.com/opendatadiscovery/odd-collectors/issues) — Collector / adapter issues
  * [opendatadiscovery/charts](https://github.com/opendatadiscovery/charts/issues) — Helm chart bugs
* Join the community Slack: <https://go.opendatadiscovery.org/slack>
* Read the [How to contribute](/developer-guides/how-to-contribute.md) guide for the contribution flow.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.opendatadiscovery.org/configuration-and-deployment/deployment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.