Deployment Options

Pick a deployment path for ODD Platform and Collector — Docker Compose, Helm, AWS EKS, or from source — with step-by-step setup and pointers to the config deep-dives.

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; per-collector / per-adapter detail lives under the Integrations hub.

Choose your option

Option

Use case

Components

Persistence

Production-ready?

Deep-dive

Docker Compose

Local evaluation / demo on a workstation

Platform + Collector + sample PostgreSQL

Container-local volumes

No — evaluation only

Try locally

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

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

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)

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 + Build and run ODD Collectors

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 under Integrations for the operator-facing setup, configuration, and caveats.

Option 1: Docker Compose (local / demo)

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.

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

Clone the platform repo: git clone https://github.com/opendatadiscovery/odd-platform.git
From the project root, start the demo stack with the bundled enricher:
```
docker-compose -f docker/demo.yaml up -d odd-platform-enricher
```
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 — 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

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.

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 installed locally.
A reachable PostgreSQL instance for the Platform (operator-supplied — bundled PostgreSQL is not included in this chart; that's Option 3).

Install

Add the chart repo:

helm repo add opendatadiscovery https://opendatadiscovery.github.io/charts
helm repo update

Install the Platform with your PostgreSQL connection details:

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>"

Create a Collector entity in the Platform UI (Management → Collectors) and copy the issued token.
Install the Collector with that token wired into collectorConfig:
```
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 for the data sources you want to ingest. Mount sensitive values via passwordSecretsEnvs rather than baking them into the YAML.

Minimal example: external PostgreSQL

# 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 — chart-repo usage (add, install, uninstall).
odd-platform chart values — full values.yaml reference.
odd-collector chart values — Collector chart reference (image, collectorConfig, env overrides, secret-env injection via passwordSecretsEnvs).
Configure ODD Platform — every Platform-side application.yml key and how it maps to config.yaml.* Helm values.
Build a custom collector — 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) on production releases first.

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

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.

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

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 — 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 for the dependency pin.

Option 4: AWS EKS via CloudFormation Quick Launch

Status: Demo-grade. Provisions an EKS cluster with bundled non-persistent PostgreSQL over HTTP only. Excellent first-look on AWS; not a production posture.

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) — 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 — same walkthrough on the chart repo.
charts/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 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

Status: Contributor / customisation path. Build artefacts from source for development or to ship a customised image. Not the standard operator path.

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 — Java 17, Gradle, Node, Docker. Per Build and run ODD Collectors — Python 3.9 or higher, Poetry 1.2.0, Docker.

Install

Platform: see Build and run ODD Platform for the gradle build and Docker image steps.
Collector: see Build and run ODD Collectors for the Poetry / Docker flow per sub-collector.
Custom Collector authoring: Build a custom collector — when an existing adapter doesn't fit.

Deep dive

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.

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).

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 under Integrations — that page is the canonical home.

Still stuck?

File an issue against the relevant repo:
- opendatadiscovery/odd-platform — Platform bugs and feature requests
- opendatadiscovery/odd-collectors — Collector / adapter issues
- opendatadiscovery/charts — Helm chart bugs
Join the community Slack: https://go.opendatadiscovery.org/slack
Read the How to contribute guide for the contribution flow.

PreviousIntegration Wizard NextTry locally

Last updated 12 days ago

Choose your option

Option 1: Docker Compose (local / demo)

When to use it

Prerequisites

Install

Verify

Deep dive

Known gotchas

Option 2: Helm on self-managed Kubernetes

When to use it

Prerequisites

Install

Minimal example: external PostgreSQL

Verify

Deep dive

Known gotchas

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

When to use it

Prerequisites

Install

Verify

Deep dive

Known gotchas

Option 4: AWS EKS via CloudFormation Quick Launch

When to use it

Prerequisites

Install

Verify

Deep dive

Known gotchas

Option 5: Build from source / developer deployment

When to use it

Prerequisites

Install

Deep dive

Known gotchas

Optional companion: odd-tracing-gateway

Still stuck?

Optional companion: `odd-tracing-gateway`