--- title: "Self-hosted setup" description: "Run the Norcaster API, portal, orchestrator, and supporting infrastructure in your own environment. Platform setup, deployment build path, revisions, readiness, and storage boundaries." canonical: https://www.norcaster.com/docs/self-hosted-setup --- Deploy # Self-hosted setup Run the Norcaster control plane and runtime infrastructure in your own environment when data residency and network boundaries require it. This guide covers the platform stack and how workload deployments are built and run inside your cluster. ## When to self-host Choose self-hosted when you need the API, portal, orchestrator, database, and supporting infrastructure to run inside your own environment — for example strict data residency, private networking, or operating the full stack on your Kubernetes cluster. ### Managed Norcaster hosts the control plane. You configure providers, deployments, workflows, policies, users, and audit exports through the portal and API. ### Self-hosted You run the API, portal, orchestrator, database, and supporting infrastructure in your own environment. Inference for container workloads executes in your cluster; provider-backed routes still call external model APIs from your API layer. Self-hosting the platform is separate from **bring-your-own external models**. The `external_model` workflow node keeps Norcaster policy, tracing, and output validation in the request path while HTTP calls go to a model you host elsewhere — without running the full Norcaster stack yourself. See [Runtime Layer Extraction (BYO model)](https://www.norcaster.com/docs/runtime-layer-extraction). Provider-backed deployments are another distinct path: bind a deployment to an OpenAI, Anthropic, or other provider model via an inference target. Norcaster routes `/run` through policy, then to the provider — no container build in your cluster. See [Provider integrations](https://www.norcaster.com/docs/providers). ## What gets deployed Self-hosting has two layers: the **platform** (Norcaster services in Kubernetes) and **workload deployments** (models and workflows you register through the API). ### Platform stack #### API Control plane and runtime entry point. Handles deploy, run, policies, providers, workflows, and audit exports. #### Portal Dashboard for deployments, policies, providers, observability, and governance. Self-host with Docker or host separately (for example Vercel with NEXT\_PUBLIC\_API\_URL). #### Orchestrator Consumes build and inference tasks from Redis. Builds GitHub-sourced artifacts, schedules inference jobs, and updates deployment status. #### Inference Runs container\_image workloads in the cluster. GPU jobs schedule on nodes labeled norcaster.com/gpu=true when config.gpu is set. #### PostgreSQL, Redis, MinIO Database, task queue, and object storage. Required for API and orchestrator operation. Production images are built and pushed for `api`, `orchestrator`, and `inference`, then applied via Kustomize overlays (`infra/kubernetes/overlays/prod` or `dev` for local k3d). The orchestrator patch sets the inference image your cluster uses for scheduled jobs. ### Workload build path (GitHub source) When you deploy from GitHub, the API enqueues a build task. The orchestrator worker detects build mode from the repository Dockerfile, then either: - **container\_image** — Kaniko builds and pushes an image; `runtime_image` is set to that reference. - **model\_bundle** — source archive is stored in MinIO; `artifact_uri` points at the bundle location. On success, deployment and revision records are updated and the deployment is marked ready. On failure, tasks retry with backoff; exhausted retries land in the build dead-letter queue. Artifact fields on deployment / revision - artifact\_type — container\_image (Kaniko build) or model\_bundle (archive to MinIO) - artifact\_uri — registry image reference or s3:// bundle location after a successful build - artifact\_digest — git commit digest or sha256 bundle digest - runtime\_image — digest-pinned image used for container\_image deployments - build\_status — queued, running, succeeded, or failed (GitHub-sourced deployments) - build\_error and build\_logs\_ref — failure detail and Kaniko job reference when applicable - source\_commit\_sha — pinned commit from GitHub source GPU inference: set `gpu` in deployment config. Join dedicated GPU nodes to the cluster (for example Hetzner GEX44) with the `norcaster.com/gpu=true` label so jobs schedule correctly. The inference image must support CUDA when running GPU workloads. ## Setup steps ### 1\. Stand up the platform 1. Provision Kubernetes (Terraform on Hetzner, an existing cluster, or local k3d per `docs/API_BUILD_DEPLOY.md`). 2. Build and push `norcaster-api`, `norcaster-orchestrator`, and `norcaster-inference` images; update the Kustomize overlay for your registry. 3. Create namespace secrets (postgres, minio, api with jwt-secret and optional billing/email keys) and apply the overlay: `kubectl apply -k infra/kubernetes/overlays/prod`. 4. Deploy the portal with `NEXT_PUBLIC_API_URL` pointing at your API (Docker self-host or external host per `docs/GO_LIVE.md`). 5. Verify: `curl https://api.yourdomain.com/health`, sign up, and confirm orchestrator and Redis pods are healthy. ### 2\. Register workload deployments 1. Create or update a deployment via POST /deploy (portal Dashboard → Deploy or norcaster deploy). Pass deployment\_id to update an existing deployment and create a new revision. 2. For GitHub-sourced deployments (source.provider == github): the API queues a build task, sets build\_status to queued, and creates a DeploymentRevision. The orchestrator builds container\_image (Kaniko) or model\_bundle (MinIO), then writes artifact\_uri, runtime\_image, and related fields. 3. Wait for build\_status succeeded before calling /run on GitHub deployments — the run route returns 409 while the build is incomplete. 4. Provider-backed deployments (InferenceTarget target\_type provider\_model) skip container builds and can reach READY without a GitHub artifact. 5. Demo models (qx-example) and MOCK\_K8S environments mark deployments READY immediately; other custom container workloads may stay PENDING until the orchestrator processes the first run. 6. Revisions snapshot model\_id, config, source, and artifact metadata. Rollout strategies (immediate, canary, shadow) control how config updates apply. 7. Assign deployments to projects and set registry metadata (purpose, data\_classification, lifecycle\_stage) as part of deploy or deployment settings. 8. Policy, contracts, redaction, and budget gates still run on every /run request before provider inference or orchestrator-scheduled inference. For GitHub auto-redeploy: connect GitHub in the portal, configure `source` with owner, repo, branch, and optional `auto_redeploy`. Pushes that match create a new revision, update `source.commit_sha`, and re-queue the build worker. ## What Norcaster stores vs what stays in your environment In self-hosted mode you operate the infrastructure, but Norcaster still persists the same categories of control-plane data in *your* PostgreSQL (and object storage where applicable): - Organizations, teams, projects, deployments, providers, and workflow definitions. - Execution records, node executions, trace IDs, timing, status, and error payloads. - Policy decisions, enforcement events, budget outcomes, and audit export metadata. - Provider credentials encrypted before storage. What stays in your environment: the Kubernetes cluster, inference containers built from your GitHub source, model bundles in your MinIO, and network paths between your applications and the API. Provider-backed and `external_model` calls still leave your boundary to reach third-party or separately hosted model endpoints — policy and traces are captured in Norcaster regardless. Self-hosting shifts *where* data is stored and which network paths you control; it does not by itself guarantee a specific regulatory outcome. Map residency and subprocessors to your deployment configuration and provider choices. ## Next steps - [Architecture](https://www.norcaster.com/docs/architecture) — request lifecycle, managed vs self-hosted, and data flow. - [Provider integrations](https://www.norcaster.com/docs/providers) — connect OpenAI, Anthropic, Azure, and bind provider-backed inference targets. - [Runtime Layer Extraction (BYO model)](https://www.norcaster.com/docs/runtime-layer-extraction) — run policy and tracing around a model you host elsewhere via the `external_model` node.