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
1
Docker Compose
Local evaluation / demo on a workstation
Platform + Collector + sample PostgreSQL
Container-local volumes
No — evaluation only
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
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
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
5
Build from source
Contributors and deep customisation
Platform + Collector built locally
Operator's choice
Yes — when paired with a production runtime
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) and5432(sample PostgreSQL)
Install
Clone the platform repo:
git clone https://github.com/opendatadiscovery/odd-platform.gitFrom the project root, start the demo stack with the bundled 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.yamlworkflow for connecting your own data source.
Known gotchas
Data persists only as long as the named Docker volumes do;
docker-compose down -vwipes 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 nodessucceeds).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:
Install the Platform with your PostgreSQL connection details:
Create a Collector entity in the Platform UI (Management → Collectors) and copy the issued token.
Install the Collector with that token wired into
collectorConfig:Replace
./your-collector-config.yamlwith acollector_config.yamlmatching the per-adapter reference for the data sources you want to ingest. Mount sensitive values viapasswordSecretsEnvsrather than baking them into the YAML.
Minimal example: external PostgreSQL
Apply with helm install odd-platform opendatadiscovery/odd-platform -f odd-platform-values.yaml.
Verify
kubectl get pods— every Platform pod isRunning.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-platformchart values — fullvalues.yamlreference.odd-collectorchart values — Collector chart reference (image,collectorConfig,envoverrides, secret-env injection viapasswordSecretsEnvs).Configure ODD Platform — every Platform-side
application.ymlkey and how it maps toconfig.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-platformchart 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
--versionto a stale release.helm repo updateand let Helm pick the latest unless you have a reason to lock — the charts are versioned inChart.yaml(odd-platform0.1.10 at the time of writing).Image tag defaults to
latestper the chart'sappVersion— pinimage.tagexplicitly 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.yamlfor upgrades,helm rollback odd-platform <revision>for rollback. Always runhelm 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
The single command installs:
odd-platform— the Platform application.postgresql(Bitnami sub-chart, version13.2.9) — bundled database.
Verify
kubectl get pods— bothodd-quicklaunch-odd-platform-*andodd-quicklaunch-postgresql-*pods areRunning.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-quicklaunchchart — chart source, including the AWS Marketplace QuickLaunch override-parameter mapping.
Known gotchas
PostgreSQL is non-persistent by default (
postgresql.primary.persistence.enabled: falsein the chart'svalues.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-collectorinstall (Option 2) to actually ingest metadata.Chart version drift. The Quick Launch chart bundles a pinned
odd-platformsub-chart version — when youhelm 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 podsshowsodd-platform-*,postgresql-*, andodd-collector-*pods allRunning.kubectl get svc odd-platform -o=custom-columns=EXTERNAL-IP:.status.loadBalancer.ingress[0].hostnamereturns 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.yamlpattern.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-1are 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-platformthen 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, andgrpcio— see the build-and-run troubleshooting section.
Optional companion: odd-tracing-gateway
odd-tracing-gatewayodd-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.
Last updated