Skip to content
Install

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.

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 --apply

On a Helm install, set the variable in server.env in your values file.

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 --apply

On 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.

To change settings without a restart, go to Instance admin > Configuration. This page has the following sections:

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.

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 --apply

The command changes ingress.host and FRONTEND_URL together, and keeps the scheme and port that the instance serves on.

The 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.

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 --apply

The 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.

Only 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.

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 --apply

Agents must reconnect at the new URL.

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.

sudo orchardctl letsencrypt-email set [email protected]

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.

Instance admin can edit these settings until a value pins them. The field then shows Cannot be edited here or Set by the environment.

SettingChange the pinned valueEdit it in Instance admin again
Public IPsudo orchardctl public-ip set <ip> --applysudo orchardctl public-ip unset --apply
Custom domains targetsudo orchardctl env set INGRESS_CNAME <host> --applysudo orchardctl env unset INGRESS_CNAME --apply
Resource limitssudo orchardctl env set INSTANCE_RESOURCE_LIMITS on --applysudo orchardctl env unset INSTANCE_RESOURCE_LIMITS --apply
Any other fieldsudo orchardctl env set <NAME> <value> --applysudo orchardctl env unset <NAME> --apply

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.

SettingCommand
Signup modesudo orchardctl config set signupMode open --apply
MCP endpoint, if it is not deployedsudo orchardctl mcp enable --apply
Updatescurl -fsSL https://assets.orchard.my/install.sh | sudo bash -s -- --yes --updates automatic
Ingress modecurl -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.

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 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:

SettingPurpose
PLATFORM_NAMESPACEThe namespace for the Ingress. The chart sets this to the release namespace.
PLATFORM_SERVICE_NAMEThe Service that the Ingress points at. The chart sets this to frontend.
PLATFORM_SERVICE_PORTThe Service port. The chart sets this to the frontend port.
CERT_CLUSTER_ISSUERThe 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:

  1. Point DNS for the new domain at the cluster.
  2. Clear the subdomain in the organization’s settings.
  3. Set the subdomain again.

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.

SettingPurpose
RESERVED_HOSTSA comma-separated list of extra hostnames that nobody can claim.
RESERVED_HOST_SUFFIXESA 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.

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.

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_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.

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.

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.

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.

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.

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.

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.

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 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.

SettingDefault
UPDATES_URLhttps://assets.orchard.my/updates/ui
updates.url in chartEmpty, 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 --apply

To 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.