Configuration
Orchard reads instance settings from three places: environment variables on the server, chart values, and the database. Most settings that superadmins change day to day live in the database, so you can edit them in the dashboard without a restart. Environment variables and chart values suit settings that you manage as code or that the cluster depends on. When an environment variable and the database both set a value, the environment variable takes precedence.
Environment variables
Section titled “Environment variables”The server reads environment variables at boot. These cover the database URL, registry, app domain, cluster access, object storage, and email. For the full list, refer to the configuration reference.
To change a variable on an installer host, use orchardctl env:
sudo orchardctl env set SMTP_HOST smtp.example.com --applyOn a Helm install, set the variable in server.env in your values file.
Chart values
Section titled “Chart values”Chart values control what the chart deploys, such as metrics, logs, and the MCP server.
On an installer host, the values file is /etc/orchard/values.yaml. To change a value, use orchardctl config:
sudo orchardctl config set logs.retention 30d --applyOn a Helm install, change your values file and run helm upgrade.
When you run the installer again, it keeps the values in this file, including a value such as signupMode. A value changes only when you change an answer that it depends on. To change one setting, use the commands in Change settings that Instance admin cannot edit.
Set cluster-specific values, such as storage class, ingress class, and registry, in the values file. These values differ for each cluster.
Settings stored in the database
Section titled “Settings stored in the database”To change settings without a restart, go to Instance admin > Configuration. This page has the following sections:
- Object storage
- Custom domains
- Wildcard certificate
- Public exposure
- Resource limits
- GitLab sign-in and Bitbucket sign-in
- Bot protection
- New organization limits
- Image scanning
- Model Context Protocol
- Databases
- Anonymous usage reports
Grafts can add sections to this page. A saved setting reaches every server replica within 30 seconds.
When an environment variable sets a field, the field is read-only and shows Set by the environment. Secret fields show Unchanged when a value is stored. Leave them blank to keep the value.
SIGNUP_MODE is not on this page. To change it, set the signupMode chart value to open, invite_only, or closed.
Change settings that Instance admin cannot edit
Section titled “Change settings that Instance admin cannot edit”Some settings are on the server or in your Helm values, so Instance admin cannot save them. Instance admin > Networking > Addresses and the last page of instance setup show what to change, in the form that matches how you installed Orchard. An instance that the installer manages has the INSTALL_INGRESS_MODE variable. Orchard treats any other instance as a Helm install.
On an installer host, --apply runs sudo orchardctl update, which also upgrades Orchard to the latest release. To make several changes and deploy once, leave out --apply, and run sudo orchardctl update after the last change.
On a Helm install, apply your values with your usual helm upgrade or GitOps process.
Dashboard domain
Section titled “Dashboard domain”The dashboard domain is where people sign in, and the address in the links that Orchard generates.
Before you change it, point the new name at this instance. In public mode, create an A record. In tunnel mode, add a public hostname to your tunnel. In lan mode, make sure the name resolves on your network.
sudo orchardctl hostname set orchard.example.com --applyThe command changes ingress.host and FRONTEND_URL together, and keeps the scheme and port that the instance serves on.
Set both values. Keep the other entries in server.env. If a Secret sets FRONTEND_URL, change it there instead.
ingress: host: orchard.example.comserver: env: - name: FRONTEND_URL value: https://orchard.example.comThe change has these effects:
- Everyone signs in again.
- Passkeys stop working, because they belong to the old name. Use a password or a one-time sign-in link.
- The GitHub App and any SSO provider keep the old URL until you update them.
- The old name stops answering. On an installer host, to keep it, run
sudo orchardctl hostname add <old-name> --apply. - The custom domains target does not change.
Apps domain
Section titled “Apps domain”Orchard gives a new app an address under the apps domain.
Before you change it, create a wildcard record, such as *.apps.example.com, that points at this instance. In tunnel mode, add the wildcard to your tunnel.
sudo orchardctl apps-domain set apps.example.com --applyThe command changes gateway.http.appDomain and APP_DOMAIN together. Do not set APP_DOMAIN alone. The chart uses gateway.http.appDomain to set the suffix for new apps, and that suffix takes precedence over APP_DOMAIN.
Set the value. If you also set APP_DOMAIN or tenant.wildcardDomains, change them to match. tenant.wildcardDomains takes precedence for new apps.
gateway: http: appDomain: apps.example.comOnly new apps use the new domain. Deployed apps keep their addresses, including after a redeploy, while DNS for the old name points at this instance. To move an app, add a domain to it.
MCP hostname
Section titled “MCP hostname”The MCP hostname is where AI agents connect.
A name directly under the apps domain needs no DNS record of its own. For any other name, create a record first.
sudo orchardctl mcp enable mcp.example.com --applySet both values. If a Secret sets MCP_BASE_URL, change it there too.
mcp: url: https://mcp.example.com ingress: host: mcp.example.comAgents must reconnect at the new URL.
Certificate issuer email
Section titled “Certificate issuer email”This is the address where Let’s Encrypt sends notices about your account. Certificates are not affected, and they issue and renew with no address.
The command changes the letsencrypt ClusterIssuer directly, so you do not need --apply. To read the address, run sudo orchardctl letsencrypt-email. Only public mode uses Let’s Encrypt.
The chart has no value for this address, because it does not create the issuer. Set spec.acme.email on your ClusterIssuer, where you manage cert-manager. tenant.certClusterIssuer and ingress.tls.issuerRef name the issuer.
apiVersion: cert-manager.io/v1kind: ClusterIssuermetadata: name: letsencryptspec: acme:Pinned settings
Section titled “Pinned settings”Instance admin can edit these settings until a value pins them. The field then shows Cannot be edited here or Set by the environment.
| Setting | Change the pinned value | Edit it in Instance admin again |
|---|---|---|
| Public IP | sudo orchardctl public-ip set <ip> --apply | sudo orchardctl public-ip unset --apply |
| Custom domains target | sudo orchardctl env set INGRESS_CNAME <host> --apply | sudo orchardctl env unset INGRESS_CNAME --apply |
| Resource limits | sudo orchardctl env set INSTANCE_RESOURCE_LIMITS on --apply | sudo orchardctl env unset INSTANCE_RESOURCE_LIMITS --apply |
| Any other field | sudo orchardctl env set <NAME> <value> --apply | sudo orchardctl env unset <NAME> --apply |
| Setting | Value | Edit it in Instance admin again |
|---|---|---|
| Public IP | tenant.publicIp | Remove the value. |
| Custom domains target | INGRESS_CNAME in server.env | Remove the entry. |
| Resource limits | INSTANCE_RESOURCE_LIMITS in server.env | Remove the entry. |
| Any other field | The variable in server.env | Remove the entry. |
For the name of each variable, refer to the configuration reference.
A change to the public IP does not move ports and databases that are already public. They stay on the old address until you turn public access off and on again. A change to the custom domains target does not affect domains that you already added, while their CNAME reaches this instance.
Other settings
Section titled “Other settings”| Setting | Command |
|---|---|
| Signup mode | sudo orchardctl config set signupMode open --apply |
| MCP endpoint, if it is not deployed | sudo orchardctl mcp enable --apply |
| Updates | curl -fsSL https://assets.orchard.my/install.sh | sudo bash -s -- --yes --updates automatic |
| Ingress mode | curl -fsSL https://assets.orchard.my/install.sh | sudo bash -s -- --yes --mode public |
Updates and ingress mode have no separate command, so these commands run the installer again.
| Setting | Value |
|---|---|
| Signup mode | signupMode |
| MCP endpoint, if it is not deployed | mcp.enabled and mcp.ingress.host. Also set JWT_SECRET and MCP_SERVICE_TOKEN in mcp.env, and the same MCP_SERVICE_TOKEN in server.env. |
Secrets
Section titled “Secrets”Store secrets in Kubernetes Secrets. Do not commit them to a values file in a repository. The installer generates the secrets it needs and writes them to /etc/orchard/values.yaml, which only root can read.
Base domain
Section titled “Base domain”BASE_DOMAIN is the parent domain for organization vanity addresses and status pages, such as acme.example.com. It is independent of the dashboard host and the app domain. Each needs its own DNS records.
When BASE_DOMAIN is set, Orchard creates an Ingress and a certificate for each vanity address and status page. The following settings apply to these hosts:
| Setting | Purpose |
|---|---|
PLATFORM_NAMESPACE | The namespace for the Ingress. The chart sets this to the release namespace. |
PLATFORM_SERVICE_NAME | The Service that the Ingress points at. The chart sets this to frontend. |
PLATFORM_SERVICE_PORT | The Service port. The chart sets this to the frontend port. |
CERT_CLUSTER_ISSUER | The ClusterIssuer for the certificate. Set this with tenant.certClusterIssuer. The default is letsencrypt-prod. |
The chart does not set these values if you use server.envFrom. In that case, add them to your Secret. Without them, the server uses default/leaf-frontend:3000. With server.envFrom, the chart also does not pass BASE_DOMAIN to the dashboard, so set PUBLIC_BASE_DOMAIN to the same domain in frontend.env. Without it, the dashboard does not show the Vanity address section or the Host field of a status page.
A vanity address sends visitors to the organization’s SSO sign-in page. If the organization has no working SSO connection, visitors go to the default sign-in page. The dashboard host keeps working if it is a subdomain of BASE_DOMAIN.
Changing BASE_DOMAIN does not move existing hosts. Each host keeps its Ingress and certificate on the old domain, while the API reports the new one. To move a host:
- Point DNS for the new domain at the cluster.
- Clear the subdomain in the organization’s settings.
- Set the subdomain again.
Reserved hosts
Section titled “Reserved hosts”Vanity addresses, status page hosts and custom domains cannot take hostnames that the platform uses. Orchard reserves the hosts in FRONTEND_URL, MCP_BASE_URL, BACKEND_URL, ORCHARD_API_URL, ORCHARD_DOCS_URL, SCIM_BASE_URL, EMAIL_ASSET_BASE_URL, TEMPLATE_REGISTRY_URL, ORCHARD_GRAFT_MARKETPLACE_URL and REGISTRY_HTTP_HOSTS, plus common names such as www, api, admin and status.
| Setting | Purpose |
|---|---|
RESERVED_HOSTS | A comma-separated list of extra hostnames that nobody can claim. |
RESERVED_HOST_SUFFIXES | A comma-separated list of domains. Custom domains cannot use the domain or anything under it. A vanity address or status page inside BASE_DOMAIN is still allowed when it is under that domain. |
When BASE_DOMAIN is the same domain as APP_DOMAIN, a platform wildcard domain, PUBLIC_DB_DOMAIN or SANDBOX_PREVIEW_DOMAIN, Orchard also refuses vanity and status labels that could collide with generated hosts. In the app domain, this means labels that end in a dash and six hex characters, such as shop-web-a1b2c3 or an opaque 3f9a1c07d2-a1b2c3. In the database and preview domains, every label is refused. Use a separate BASE_DOMAIN to avoid these limits.
With the chart, set RESERVED_HOSTS and RESERVED_HOST_SUFFIXES in server.env.
Generated hostname style
Section titled “Generated hostname style”Every certificate that a public CA issues is published in Certificate Transparency logs, and anyone can read those logs. If hosts are named after the app and project, the logs list every app on your instance, including apps that are protected. Orchard therefore generates opaque hostnames by default, such as 3f9a1c07d2-a1b2c3.apps.example.com. The label is derived from a server secret and the deployment ID, stays the same for that app, and cannot be turned back into an organization, project or namespace. The same applies to the hostname of a public database in perDatabase TLS mode.
The trade-off is that the URLs are harder to read and to recognize in logs and DNS tooling. On an instance that one company runs and where names are not sensitive, set HOSTNAME_STYLE=readable to get hostnames in the form <app>-<project>-<hash>. With the chart, set it in server.env. The setting applies to new hosts only. Existing hosts, custom domains and vanity addresses are never renamed. A wildcard certificate keeps individual hostnames out of the logs altogether.
Resource limits
Section titled “Resource limits”INSTANCE_RESOURCE_LIMITS turns resource limits on or off for the whole instance, and locks the setting in Instance admin. Unset, the choice in Instance admin applies. If nobody has chosen, limits are on. If you unset the variable, Orchard keeps the value that it locked.
Database memory
Section titled “Database memory”DATABASE_DEFAULT_MEMORY_MB sets the memory request for a database that has no size of its own. The default is 1024 and the minimum is 512. The installer lowers the value on a machine with about 8 GB of memory or less.
App memory
Section titled “App memory”DEFAULT_APP_MEMORY_MB sets the memory limit for an app that has no size of its own and no organization default. The default is 128. The installer sets the value on a new install, based on the memory of the machine.
Namespace floor
Section titled “Namespace floor”TENANT_QUOTA_FLOOR_PODS, TENANT_QUOTA_FLOOR_SERVICES, TENANT_QUOTA_FLOOR_PVCS, and TENANT_QUOTA_FLOOR_STORAGE_BYTES set the most that a project without a cap can create when limits are on. The installer sets high values on a new install, so that the floor does not stop a small instance.
Every tenant namespace also gets an orchard-abuse-quota that applies whatever the limits mode. TENANT_QUOTA_FLOOR_LOADBALANCERS (default 20) and TENANT_QUOTA_FLOOR_NODEPORTS (default 10) cap the Services that publish ports and databases. TENANT_EPHEMERAL_STORAGE_LIMIT_GIB (default 20) is the ephemeral-storage limit each container gets when it sets none, so a pod cannot fill a node’s disk. Set it to 0 to turn the ephemeral-storage part off.
Organization limits
Section titled “Organization limits”A new organization is created uncapped: no CPU cap, no memory cap, and no limit on how many projects, environments and deployments it can hold. On an instance with open sign-up that means anyone who can create an organization can use as much compute as the server has, so set limits before you open sign-up.
A superadmin sets the limits that new organizations start with under Instance admin > Configuration > New organization limits: CPU, memory, projects, environments and deployments, each blank for no limit. The values are copied into the organization when it is created. Changing them later never touches an organization that already exists. A superadmin changes one organization from the Resource quotas icon in Instance admin > Organizations, where blank again means no limit; every change is recorded in the audit log (admin.new_org_defaults_updated and admin.org.quota_updated). Organizations created by an administrator, by an SSO auto-create rule or through sign-up all get the instance default. The first organization that the setup flow creates is never capped.
NEW_ORG_CPU and NEW_ORG_MEMORY (tenant.newOrgCpu and tenant.newOrgMemory in the chart) seed the compute caps for new organizations when no instance default has been saved in the admin panel; 0 or unlimited means no cap. MAX_PROJECTS_PER_ORG, MAX_ENVIRONMENTS_PER_ORG and MAX_DEPLOYMENTS_PER_ORG (tenant.maxProjectsPerOrg, tenant.maxEnvironmentsPerOrg and tenant.maxDeploymentsPerOrg) are optional hard ceilings that apply to every organization on top of its own limit; unset or 0 means no ceiling. Superadmins can also set these ceilings in Instance admin > Limits > Organization size. An organization that is already above a limit keeps everything it has and cannot create more.
Custom domains
Section titled “Custom domains”When SIGNUP_MODE is open, adding a custom domain needs a TXT record that proves ownership, unless Require proof of domain ownership in Instance admin > Networking or CUSTOM_DOMAIN_VERIFICATION says otherwise. Domains that a project already serves are never checked again. An organization can hold 250 custom hostnames and add 30 new ones an hour (MAX_CUSTOM_DOMAINS_PER_ORG and MAX_CUSTOM_DOMAIN_CREATES_PER_HOUR; 0 is unlimited). Superadmins can also change both in Instance admin > Limits > Custom domains. After five failed proofs, the organization has to wait a minute before it can add another domain, and the wait doubles with each further failure, up to a day. This keeps one tenant from using up the certificate authority’s limits for everyone.
Platform priority
Section titled “Platform priority”The chart creates a PriorityClass named orchard-platform (value 100000) and sets it on the platform pods: the server, worker, frontend, MCP, Redis, the platform Postgres and its pooler, the logs and metrics stores, Vector, and the other monitoring pods. Tenant workloads keep the default priority, so on a busy cluster the scheduler places the platform first and the kubelet evicts it last. Tenants cannot choose a class. Orchard sets none on tenant pods, and the tenant admission policy refuses names that start with system- or orchard-. Set priorityClasses.enabled: false to turn this off. Turning it on or off changes the platform pod templates, so the platform pods restart once.
Egress bandwidth
Section titled “Egress bandwidth”TENANT_EGRESS_BANDWIDTH (tenant.egressBandwidth in the chart), for example 50M, makes Orchard set the standard kubernetes.io/egress-bandwidth annotation on app and job pods. It is off by default. The annotation limits the pod’s outbound traffic only where the CNI enforces it: Cilium with bandwidthManager.enabled=true, or a CNI chain that includes the bandwidth plugin, which k3s and installer hosts include. On other clusters it has no effect, so the cluster side is yours to set up. Running pods pick the annotation up on their next rollout.
Log rate limit
Section titled “Log rate limit”Vector ships every tenant’s logs to one VictoriaLogs store, which drops the oldest days for everyone once it is full. To stop one app from filling it, Vector limits each tenant namespace to 2000 log lines per second. Lines above the rate are dropped for that namespace only, and Vector counts them in component_discarded_events_total. Change the rate with logs.vector.throttle.eventsPerSecond; 0 turns the limit off.
The What’s new sheet
Section titled “The What’s new sheet”The dashboard shows each person the latest release notes once. The server reads the notes from a folder that holds latest.json and one Markdown file for each release.
| Setting | Default |
|---|---|
UPDATES_URL | https://assets.orchard.my/updates/ui |
updates.url in chart | Empty, which keeps the server default. |
A value in server.env takes precedence over updates.url.
To hide the sheet, run the following command:
sudo orchardctl config set updates.url off --applyTo publish your own notes, point the setting at your own folder. latest.json needs a version, such as 2.70.0. It can also have file, url, and publishedAt. The default file is <version>.md. A note shows only when its version is at or below the running version of the dashboard.
Related resources
Section titled “Related resources”- Finish instance setup - Set up email, DNS, backups, and the other settings a new instance needs.
- Instance admin - Find each page of the superadmin dashboard.