Before you begin
- A Private Deployment plan confirmed with Orchestris
- A named infrastructure owner and security owner
- The release-specific delivery bundle or managed-environment handoff
- Access to the Orchestris account portal for the applicable license
Confirm the operating model
| Model | Infrastructure owner | Configuration boundary |
|---|---|---|
| Licensed self-hosted | Your organization operates the server environment, storage, networking, secrets, providers, backups, upgrades, and monitoring. | Orchestris supplies the contracted release and licensing values. Your team applies them to the customer-controlled environment. |
| Dedicated managed | Orchestris operates the dedicated environment according to the order and handoff. | Do not apply self-hosted image or environment-variable instructions unless the handoff explicitly assigns that responsibility to your team. |
- Model
- Licensed self-hosted
- Infrastructure owner
- Your organization operates the server environment, storage, networking, secrets, providers, backups, upgrades, and monitoring.
- Configuration boundary
- Orchestris supplies the contracted release and licensing values. Your team applies them to the customer-controlled environment.
- Model
- Dedicated managed
- Infrastructure owner
- Orchestris operates the dedicated environment according to the order and handoff.
- Configuration boundary
- Do not apply self-hosted image or environment-variable instructions unless the handoff explicitly assigns that responsibility to your team.
Create and protect the portal deployment record
- 1
Open the applicable license
Sign in to the Orchestris account portal and open the license supplied for the Private Deployment.
- 2
Create a deployment
Enter a deployment name in the portal. The portal provides a one-time deployment secret and the exact licensing-portal origin.
- 3
Store the portal values
Transfer the deployment secret directly into the deployment secret manager; it is not sent by email. Record the exact credential-free HTTPS portal origin without adding a path, query, or fragment.
- 4
Collect the organization UUID from the handoff
Use the ORCHESTRIS_LICENSE__SELF_HOSTED_ORG_ID value supplied in the Private Deployment handoff. It is not the deployment name and is not created by the portal form.
- 5
Choose a stable cluster ID and rotation owner
Your deployment team chooses ORCHESTRIS_CLUSTER__CLUSTER_ID once and keeps it stable across node replacements. Record who owns deployment-secret rotation, the maintenance window, validation, and rollback.
Supply the licensed deployment values
| Environment name | Purpose | Source |
|---|---|---|
| ORCHESTRIS_LICENSE__DEPLOYMENT_MODE | Set to self_hosted for a customer-operated licensed deployment. | Deployment operating model. |
| ORCHESTRIS_LICENSE__PORTAL_URL | Canonical Orchestris licensing-portal origin used for validation. | Portal deployment instructions. |
| ORCHESTRIS_LICENSE__DEPLOYMENT_SECRET | Authenticates this deployment to the licensing portal. | One-time portal display; store as a secret. |
| ORCHESTRIS_LICENSE__SELF_HOSTED_ORG_ID | Locks license validation to the organization UUID served by this deployment. | Private Deployment handoff. |
| ORCHESTRIS_CLUSTER__CLUSTER_ID | Stable lowercase cluster identifier used by self-hosted license validation. | Choose once with the deployment owner; use 3–64 lowercase letters, digits, and hyphens, starting and ending with a lowercase letter or digit. |
| ORCHESTRIS_SERVER__PUBLIC_BASE_URL | Externally reachable HTTP(S) API origin used for generated URLs and organization bootstrap. | Customer DNS and TLS plan. |
| ORCHESTRIS_ENCRYPTION__MASTER_KEY | 32-byte key represented as exactly 64 hexadecimal characters for encrypted server data. | Customer secret manager; generate uniquely for the deployment. |
| ORCHESTRIS_DATABASE__URL | SQLite or PostgreSQL connection selected by the delivered topology. | Customer database secret or managed database integration. |
- Environment name
- ORCHESTRIS_LICENSE__DEPLOYMENT_MODE
- Purpose
- Set to self_hosted for a customer-operated licensed deployment.
- Source
- Deployment operating model.
- Environment name
- ORCHESTRIS_LICENSE__PORTAL_URL
- Purpose
- Canonical Orchestris licensing-portal origin used for validation.
- Source
- Portal deployment instructions.
- Environment name
- ORCHESTRIS_LICENSE__DEPLOYMENT_SECRET
- Purpose
- Authenticates this deployment to the licensing portal.
- Source
- One-time portal display; store as a secret.
- Environment name
- ORCHESTRIS_LICENSE__SELF_HOSTED_ORG_ID
- Purpose
- Locks license validation to the organization UUID served by this deployment.
- Source
- Private Deployment handoff.
- Environment name
- ORCHESTRIS_CLUSTER__CLUSTER_ID
- Purpose
- Stable lowercase cluster identifier used by self-hosted license validation.
- Source
- Choose once with the deployment owner; use 3–64 lowercase letters, digits, and hyphens, starting and ending with a lowercase letter or digit.
- Environment name
- ORCHESTRIS_SERVER__PUBLIC_BASE_URL
- Purpose
- Externally reachable HTTP(S) API origin used for generated URLs and organization bootstrap.
- Source
- Customer DNS and TLS plan.
- Environment name
- ORCHESTRIS_ENCRYPTION__MASTER_KEY
- Purpose
- 32-byte key represented as exactly 64 hexadecimal characters for encrypted server data.
- Source
- Customer secret manager; generate uniquely for the deployment.
- Environment name
- ORCHESTRIS_DATABASE__URL
- Purpose
- SQLite or PostgreSQL connection selected by the delivered topology.
- Source
- Customer database secret or managed database integration.
Confirm the topology before rollout
| Decision | Single-node | Multi-node |
|---|---|---|
| Database | SQLite or PostgreSQL as approved by the delivery plan. | PostgreSQL; do not share a SQLite file between nodes. |
| Rate limits and conversation locks | In-memory backends are process-local. | Redis-backed shared rate limiting and conversation locking are required. |
| Node identity | A stable cluster ID is still required for self-hosted license validation. | Stable cluster ID and stable per-node IDs; include node lifecycle in operations. |
| TLS and ingress | One public origin terminating TLS at the process or trusted proxy. | One canonical public origin with health checks, compatible streaming timeouts, and the forwarding/trust policy in the deployment plan. |
| Backup | Quiescent SQLite/full-state backup or database-native PostgreSQL backup plus secrets and keys. | Database-native backup, Redis recovery policy where applicable, and independent backup of deployment secrets, encryption material, and JWT keys. |
- Decision
- Database
- Single-node
- SQLite or PostgreSQL as approved by the delivery plan.
- Multi-node
- PostgreSQL; do not share a SQLite file between nodes.
- Decision
- Rate limits and conversation locks
- Single-node
- In-memory backends are process-local.
- Multi-node
- Redis-backed shared rate limiting and conversation locking are required.
- Decision
- Node identity
- Single-node
- A stable cluster ID is still required for self-hosted license validation.
- Multi-node
- Stable cluster ID and stable per-node IDs; include node lifecycle in operations.
- Decision
- TLS and ingress
- Single-node
- One public origin terminating TLS at the process or trusted proxy.
- Multi-node
- One canonical public origin with health checks, compatible streaming timeouts, and the forwarding/trust policy in the deployment plan.
- Decision
- Backup
- Single-node
- Quiescent SQLite/full-state backup or database-native PostgreSQL backup plus secrets and keys.
- Multi-node
- Database-native backup, Redis recovery policy where applicable, and independent backup of deployment secrets, encryption material, and JWT keys.
Validate before user rollout
Run the configuration-check command supplied by the release bundle with the same environment and secret versions intended for production. The direct-binary example below applies only when the handoff installs orchestris-api on the command path; container and service bundles must use their supplied equivalent.
Direct-binary example from a matching handoff
orchestris-api --config-checkA successful check prints orchestris-api configuration check passed and exits without starting the HTTP server. It validates the effective settings and required relationships; it does not prove that external services are reachable.
- The configuration check runs with the exact environment and secret versions intended for production.
- GET /health succeeds through the same ingress origin clients use.
- The server can validate its entitlement with the portal without redirects or certificate errors.
- Administrators can sign in and reach the intended organization context.
- Provider credentials are stored, provider/model checks succeed, and group grants expose only the intended models.
- Backups include the database plus matching encryption, hashing, cursor, and JWT key material, and a restore has been tested.
- Chat can connect through Servers → Add Server, and hosted Chat loads from /app/ when it is included in the delivery.