Skip to content
OrigamyOrigamy Developers

Self-hosting overview

Origamy splits into two planes. The control plane (dashboard, configuration, the app at app.origamy.io) is always hosted by Origamy. The data plane — the event pipeline that ingests, transforms, stores, and routes your customer data — can run either in Origamy Cloud or in your own infrastructure. Self-hosting means your telemetry never leaves your network.

How it connects

Section titled “How it connects”

The data plane opens one outbound TLS connection to Origamy (tunnel.origamy.io:443). No inbound ports are required — your firewall only needs to allow egress on TCP 443. The dashboard reaches your data (live events, profiles, analytics) back through that same tunnel.

Your infrastructure
├── nats               (event bus)
├── clickhouse         (analytics store)
├── redis              (identity and session cache)
├── ingestion-gateway  (receives events from your SDKs)
├── transformer-engine (JS transform pipeline)
├── identity-resolver  (user/device stitching)
├── segment-evaluator  (real-time segments)
├── bulker-worker      (writes events into ClickHouse)
├── config-sync        (pulls config from Origamy, reports health)
├── portal-agent  ──── outbound TLS ──────▶ Origamy control plane
│                                            (dashboard, config, queries)
│
├── postgres + workflow-engine  (journeys, broadcasts, human tasks — on by default)
├── orchestrator-engine         (AI engine — opt-in, gated package)
├── predictor                   (churn / propensity / LTV — opt-in, Kubernetes)
└── caddy                       (HTTPS for your event endpoint — Docker, opt-in)

The fast path: the Origamy CLI

Section titled “The fast path: the Origamy CLI”

The Connections page in your dashboard prints one line with your enrollment token already filled in. Run it on the host that will run the data plane, or on a workstation whose kubectl points at your cluster:

Terminal window
sh -c "$(curl -fsSL https://v1.origamy.io/install.sh)" deploy --token dpe_xxx

install.sh downloads the latest origamy release for your OS and architecture, checks the binary against the release’s SHA256SUMS, and verifies that file’s Ed25519 signature with the public keys embedded in the script (on macOS this needs Homebrew’s openssl@3; otherwise the script continues checksum-only and says so). A mismatch aborts the install. (You can also download the binary yourself from GitHub releases and run origamy deploy --token dpe_xxx.)

What the CLI does:

  1. Enrolls. It generates a keypair on your machine and sends only a certificate signing request; the private key never leaves. Enrollment tokens are single-use and expire after 72 hours — get a fresh one from the Connections page if yours has lapsed, or if a deploy failed after enrolling.
  2. Detects the target. A reachable Kubernetes cluster gets a Helm release named odp in the origamy-dp namespace. Otherwise it writes a Docker Compose project into ./origamy-dp-<id>/.
  3. Asks a few questions. Deployment size on both. On Kubernetes: embedded or external ClickHouse, and how to expose the event endpoint (cloud load balancer, Ingress on your domain, or internal only). On Docker: whether to run the engagement services (journeys, broadcasts, human tasks) and an HTTPS domain for your event endpoint. On both: whether to enable the AI engine.
  4. Generates secrets locally. Datastore passwords, the AI engine’s encryption key, and the mTLS identity are created on your side and stored in Kubernetes Secrets or a 0600 .env file. Nothing generated here is sent to Origamy.
  5. Pins a release. A fresh install runs data-plane release 0.1.17 — the Helm chart version on Kubernetes and the image tag on Docker (chart and images share one version).

Once the deploy finishes, the Connections page shows your data plane as connected, and the dashboard works exactly as it does for cloud workspaces.

Flag What it does
--enable-ai Enable the AI engine without being asked (adds a pod on Kubernetes, the agentic compose profile on Docker). It stays inert until you enable AI and add an LLM credential in the dashboard.
--datastore-auth Kubernetes: password-protect the bundled Redis, NATS and ClickHouse. The chart generates the passwords in-cluster. Docker installs always get generated passwords.
--version X.Y.Z Install a specific release instead of the CLI’s pin.

Later: origamy status, origamy upgrade (also how you turn the AI engine or predictor on and off), origamy rollback, and origamy uninstall. Every command and flag is in the CLI reference.

Manual installs

Section titled “Manual installs”

If you want full control over the deployment, follow the platform guide:

  • Docker Compose — a single Linux host, ideal for evaluation and small production workloads.
  • Kubernetes (Helm) — the published chart runs the full pipeline, including its datastores, and scales the workers independently.

Where events go

Section titled “Where events go”

With a self-hosted data plane, your SDKs send events to your gateway, not events.origamy.io. Each guide covers exposing the ingestion endpoint; once it’s public, paste its URL into your source’s Setup tab in the dashboard so the copy-paste SDK snippets use it automatically.