# Configuration > Find where Orchard instance settings are stored, which value takes precedence, and how to change them on an installer host or a Helm install. Source: https://docs.orchard.hackclub.com/operate/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 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](/reference/configuration/). To change a variable on an installer host, use [`orchardctl env`](/operate/host-commands/#env): ```bash 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 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`](/operate/host-commands/#config): ```bash 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](/start/install/#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](#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 To change settings without a restart, go to **Instance admin** > **Configuration**. This page has the following sections: - [**Object storage**](/operate/storage/) - [**Email**](/operate/finishing-setup/#set-up-email) - [**Custom domains**](/operate/finishing-setup/#set-the-custom-domains-target) - [**Wildcard certificate**](/operate/wildcard-certificates/) - [**Public exposure**](/operate/finishing-setup/#set-a-default-public-ip) - [**Resource limits**](/operate/resource-limits/) - [**GitLab sign-in** and **Bitbucket sign-in**](/deploy/git-providers/) - [**Bot protection**](/operate/bot-protection/) - [**New organization limits**](#organization-limits) - [**Image scanning**](/operate/image-scanning/) - [**Model Context Protocol**](/mcp/) - **Databases** - [**Anonymous usage reports**](/operate/telemetry/) [Grafts](/grafts/overview/) 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 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 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. **Script install** ```bash 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. **Helm** Set both values. Keep the other entries in `server.env`. If a Secret sets `FRONTEND_URL`, change it there instead. ```yaml ingress: host: orchard.example.com server: env: - name: FRONTEND_URL value: https://orchard.example.com ``` The change has these effects: - Everyone signs in again. - [Passkeys](/account/security/#add-a-passkey) 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 --apply`. - The custom domains target does not change. ### 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. **Script install** ```bash 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`. **Helm** Set the value. If you also set `APP_DOMAIN` or `tenant.wildcardDomains`, change them to match. `tenant.wildcardDomains` takes precedence for new apps. ```yaml gateway: http: appDomain: apps.example.com ``` 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](/deploy/domains/#add-a-custom-domain) to it. ### 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. **Script install** ```bash sudo orchardctl mcp enable mcp.example.com --apply ``` **Helm** Set both values. If a Secret sets `MCP_BASE_URL`, change it there too. ```yaml mcp: url: https://mcp.example.com ingress: host: mcp.example.com ``` Agents must reconnect at the new URL. ### 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. **Script install** ```bash sudo orchardctl letsencrypt-email set you@example.com ``` 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. **Helm** 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. ```yaml apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: letsencrypt spec: acme: email: you@example.com ``` ### 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`. **Script install** | Setting | Change the pinned value | Edit it in Instance admin again | | --------------------- | ------------------------------------------------------------- | ------------------------------------------------------------ | | Public IP | `sudo orchardctl public-ip set --apply` | `sudo orchardctl public-ip unset --apply` | | Custom domains target | `sudo orchardctl env set INGRESS_CNAME --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 --apply` | `sudo orchardctl env unset --apply` | **Helm** | 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](/reference/configuration/). 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 **Script install** | 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](/start/install/#run-the-installer-again). **Helm** | 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 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 `BASE_DOMAIN` is the parent domain for [organization vanity addresses](/teams/sso/#set-a-vanity-address) and [status pages](/run/status-pages/#add-a-host), 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: 1. Point DNS for the new domain at the cluster. 2. Clear the subdomain in the organization's settings. 3. Set the subdomain again. ### 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 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 `--`. 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](/operate/wildcard-certificates/) keeps individual hostnames out of the logs altogether. ## Resource limits `INSTANCE_RESOURCE_LIMITS` turns [resource limits](/operate/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 `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 `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 `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 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 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 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 `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 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 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: ```bash 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 `.md`. A note shows only when its version is at or below the running version of the dashboard. ## Related resources - [Finish instance setup](/operate/finishing-setup/) - Set up email, DNS, backups, and the other settings a new instance needs. - [Instance admin](/operate/instance-admin/) - Find each page of the superadmin dashboard.