Deployments and environments
Cortex runs as one Kubernetes namespace per environment. A project leaves the platform in three ways: a standalone deployment on the cluster, a git export to the project's own repository, or an archive a customer runs on their own infrastructure. All three start from the same export of the project's engine fork, configured on the Deployments page (Operations group). A project copy can also be moved between environments with its stores intact, gated by its own tests.
Environments
An environment is a Kubernetes namespace with the platform's services, its stores and its agent fleet. It answers at a main hostname and publishes every app service at its own hostname under an applications domain. An operator typically runs development and production side by side on one cluster, each built from its own branch by the CI pipeline.
An environment can answer under more than one domain: the same load balancers carry an extra host rule and certificate per domain, and every app service gets the matching twin hostname. Share links live on the main hostname, and every service link the UI hands out is rewritten to the domain the page was opened on.
Publishing app services
App services are published per environment through one ingress group with a wildcard certificate for the applications domain.
| Setting | Effect |
|---|---|
| Public | An ingress and a hostname generated from the service name and the project; the service becomes an app on the Apps page |
| Not public | No ingress; reachable only on the project's network |
| Subdomain | Replaces the generated label under the applications domain |
| Custom domain | The customer's own hostname; the customer points it at the environment's applications host and the platform picks up the certificate issued for it |
See Applications and Independent applications.
App service builds
On Kubernetes an app service is written to the shared services volume, built by the in-cluster image builder and run as a deployment plus a cluster service with the image's own entrypoint, port and probes, a writable data volume, resource limits and the project's environment only. A failed image build fails the service's build: the service manager reads the build job's verdict after the log stream ends, so a service never reports running on its previous image. On a laptop the same five operations (create, update, build, status, logs) run through the local container engine.
The Deployments page
The page lists a project's deployments and offers Deploy project. The dialog has two paths.
| Path | What happens |
|---|---|
| Deploy to the cluster | The exporter compiles the fork (flattened endpoints including the workflow engine and pipelines, service containers, application screens, the endpoints dashboard) into a git commit, builds images tagged with that commit and deploys them in their own namespace at a hostname derived from the project. Options: the login page on or off, seed data (off by default; fills only missing or empty databases), extra subdomains. A deploy enqueues the test suite a few minutes later (Tests and health). Redeploy and teardown are on the detail pane |
| Download for local run | An archive run with Docker Compose. Ticking Customer archive produces the delivery described below |
Every export is a git commit in the fork's export repository. When git hosting is configured for the installation, every new project gets a private repository and exports are pushed there; see Integrations and API.
The Delivery card
The delivery options are stored on the fork, edited on the Delivery card, normalised by the engine and validated strictly by the platform before they are saved. They drive every export.
| Option | Default | Meaning |
|---|---|---|
| App services | On | The fork's app services: image definition and tree verbatim, a service description, an example environment file |
| Compose | Always on | Docker Compose entries in the root compose file and in the archive |
| Kubernetes | Off | A deployment with probes, a persistent volume, a cluster service, an ingress for public HTTP surfaces, an example secret per service, a kustomization |
| Azure Container Apps | Off | Templates with an example parameter file and a deploy script |
| CI | None | GitHub Actions (a build matrix over every image definition, deploy jobs gated on repository variables) or Azure Pipelines (build-and-push matrix, deploy stages gated on a service connection) |
| Registry | Empty | Image registry prefix; empty leaves a placeholder the customer fills |
| Runbook | On | The generated runbook, and the root README in a git export |
| Development stand-ins | None | App services shipped as stand-ins (a sample database) in a separate development compose file only |
| Distribute | All off | Which companions the customer receives: chat, workflows, guides, models, pipeline, governance, docs |
Exported service names are DNS labels, the same in Compose, Kubernetes and Container Apps; environment values naming a sibling's platform container are rewritten to the exported name. Secrets are detected by key shape and by a password segment in a value, and are blank in every committed file of a git export.
The customer archive
The customer archive is the delivery a customer deploys themselves. It is self-contained and carries nothing the applications do not use.
| Aspect | In the archive |
|---|---|
| Shape from usage | The app services always; the engine runtime, the chromeless operations pages and the agent chat only when a distributed companion needs them, with endpoints pruned to match. A companion that is off is absent even if the platform shows it: the speed dial is filtered, workflow tables are dropped from the data dump, the operations layer is left unconfigured |
| Per-archive secrets | One generated operator credential, the session signing secrets, the store password and each governed target's role password are minted for the archive; the seed re-keys the database roles and the configuration dump is scrubbed of platform passwords. No platform people, no model token |
| Files | A customer README (glossary, required versus optional services, the two sign-ins), a run script with a development mode for the stand-ins, a test script, the runbook, the knowledge pages and guides, a compose file with an acyclic start order plus a development compose file, and environment files whose defaults come from each service tree's own example file (the comment above a key is its description; keys are marked required, secret or optional) |
| App SDK offline | The archive's portal serves the SDK, the application registry and the data call inside the bundle |
Before handover a fresh archive is checked for the shapes of known keys (API keys, cloud credentials, signed tokens, private keys, password segments) and for the platform's own names.
The generated runbook
The runbook is derived from the service definitions the service manager runs (ports, health paths, environment keys), never typed by hand.
| Section | Contents |
|---|---|
| 1. What this delivers | Component table: kind, path, port, health |
| 2. Setup | Prerequisites per target; one variable table per service with descriptions; the stand-ins |
| 3. Deployment | Compose commands; Kubernetes, Container Apps and CI sections only when enabled |
| 4. Health and monitoring | A health URL per service, log and restart commands |
| 5. Support | A fixed triage order |
| 6. Rollback | Two layers, below |
| 7. Project documentation | The index of the knowledge pages |
| 8. Where this ran before you | The platform URLs |
| 9. Not in this delivery, and what we need from you | Open requirements, non-goals and the Summary notes |
Rollback in two layers
| Layer | Mechanism |
|---|---|
| Platform | Return to the previous commit or image tag: a rollout undo on Kubernetes, revision traffic on Container Apps, Compose with the previous tag. Git is the record of what ran |
| Business | Per-consumer flags in the project's own data, documented in the knowledge pages, so a change can be switched off for one consumer without redeploying |
Moving a project between environments
A project copy is moved whole: the destination copy is replaced and the source is only read. The move runs in phases (discover, extract, remove, restore, operations data, screens, verify, tests).
| Store | What moves |
|---|---|
| Versioned configuration store | The project's whole configuration database, commit history included |
| Project registry row | Re-inserted with the engine address and the owner rewritten for the destination |
| Engine fork | A dump of the fork: endpoints, services, the vault (requirements, knowledge pages, guides), screen builds, app services |
| Fork environment | The source's values with the destination's store and object-storage settings merged in |
| Target databases | Dumped and restored, workflow tables included |
| Object storage | Sources, approved screen pictures, evidence, pipeline output and fleet transcripts, under the same keys |
| Platform database rows | Apps, agents, models, Board cards, Docs (sources, previews, requirements, tasks, evidence, tests) and fleet sessions; people matched by email, organisations by slug; password hashes are not copied |
| Screen bundles | Rebuilt on the destination by running each screen once |
The promotion loop is local-first: pull the environment's copy to a local installation, snapshot it, make the change through the product, verify against the requirement's acceptance checklist, revert from the snapshot if it falls short, then back up the cluster copy, push, and compare the two copies through the Docs API. The push ends with the test gate: the suite runs on the destination and a red copy is refused. A release is done when the suite is green on the target, whatever the store counts say.