# Install > Install Orchard on a Linux machine with the one-command installer, or on an existing Kubernetes cluster with the Helm chart. Source: https://docs.orchard.hackclub.com/start/install/ You can install Orchard on a single Linux machine with one command, or on a Kubernetes cluster that you operate with the Helm chart. Both give you the same Orchard. They differ in what runs underneath it and who looks after that part. ## Choose how to run Orchard The one-command installer builds a single-node k3s cluster on one machine. It puts app data on `local-path` disks, runs a zot registry that only that machine can pull from, and keeps backups in an S3 store on the same disk. You answer a few questions and the installer configures the cluster and Orchard, which makes it the fastest way to a working instance. Some items, such as kernel sandboxing and off-server backups, stay with you. For the list, refer to [What the installer does not configure](#what-the-installer-does-not-configure). It suits a home lab, a side project, a small team, or a trial. Because everything runs on one machine, that machine is a single point of failure. For production, Orchard recommends the Helm chart on a multi-node cluster built for it, such as [Talos Linux](https://docs.siderolabs.com/talos). You operate the cluster and can replace the bundled components with ones that you run yourself. For the differences, refer to [Choose a layout](/operate/production/#choose-a-layout). | Environment | Method | | ---------------------------------------------------------- | ---------------------------------------------------- | | A Linux machine with no cluster on it | [One-command installer](#install-on-a-linux-machine) | | A Kubernetes cluster you operate, such as a production one | [Helm chart](#install-on-an-existing-cluster) | | A laptop, for a local trial | [Quickstart script](#try-orchard-on-a-laptop) | An installer host cannot take more nodes yet. To run on more than one machine, use the Helm chart. Refer to [Add and remove nodes](/operate/nodes/#on-an-installer-host). After you install Orchard, [claim the instance](#claim-the-instance). ## Install on a Linux machine The installer creates a single-node k3s cluster. It then installs Traefik, CloudNativePG with the Barman Cloud plugin, cert-manager (except in `tunnel` mode), a zot registry, and Orchard. If the machine can already reach another Kubernetes cluster, the installer warns you and leaves that cluster alone. ### Prerequisites - A physical machine or a virtual machine (VM) with an amd64 or arm64 CPU. The installer refuses other architectures. - A Linux distribution that uses systemd. Continuous integration (CI) tests the installer on Ubuntu 24.04 (amd64 and arm64) and Ubuntu 26.04 (amd64). Other distributions with systemd can work, but they are not tested. - An IPv4 address. IPv6-only servers are not supported yet. For more information, refer to [The installer stops on an IPv6-only server](/operate/troubleshooting/#the-installer-stops-on-an-ipv6-only-server). - Root access. - OpenSSL 3 or newer, which the published installer uses to check release signatures. Without it, the installer stops, unless you set `ORCHARD_ALLOW_UNSIGNED_COMMANDS=true` to install without the check. The installer also uses OpenSSL to create the [Barman Cloud plugin certificates](/operate/backup-and-restore/#plugin-certificates), so it needs OpenSSL even with that setting. - At least 20 GB of free disk on `/var/lib`. The installer refuses less, and it warns below 60 GB. For real use, plan for at least 40 GB of disk. - 2 GiB of RAM. 8 GiB is recommended. The installer warns below 2 GiB but does not refuse, and it trims Orchard on smaller machines. Refer to [Run on a small server](/operate/small-servers/). - For `public` mode, ports 80 and 443 free and reachable from the internet. A domain is optional. To try Orchard without one, refer to [Try Orchard without a domain](#try-orchard-without-a-domain). - For `tunnel` mode, a domain and a Cloudflare Tunnel token. - Outbound internet access. For the hosts the installer contacts, refer to [Outbound connections](/operate/outbound-connections/). Do not run the installer inside a Docker container. k3s cannot nest its overlayfs snapshotter there. ### Choose an ingress mode The ingress mode sets how traffic reaches the machine. | Mode | Use for | TLS | | -------- | -------------------------------------------------------- | ----------------------------------------------------------------- | | `public` | A routable IP address with DNS pointed at it | Let's Encrypt over HTTP-01 | | `tunnel` | A machine behind NAT or CGNAT, through Cloudflare Tunnel | Cloudflare terminates TLS and the installer skips cert-manager | | `lan` | A LAN or Tailscale network, reached by address | Self-signed certificates for apps. The dashboard uses plain HTTP. | The mode also decides which host ports Orchard binds. | Mode | Port 80 | Port 443 | | -------- | ------------------------------------------------------------------------------ | ------------- | | `public` | HTTP-01 challenges for the dashboard, the MCP endpoint, and every app hostname | All traffic | | `lan` | The dashboard and the MCP endpoint, in plain HTTP | Deployed apps | | `tunnel` | Not bound | Not bound | In every mode, Flannel listens on port `8472/udp`, and node-exporter listens on port `9100` while metrics are on. Only the cluster needs these ports. With `ufw` or `firewalld` active, the installer closes both to everything outside the pod and service networks. Without a host firewall, close them in your provider's firewall. For details, refer to [Host firewalls](/operate/security/#host-firewalls). > **Caution** > > In `public` mode, port 80 must stay open after the install. Let's Encrypt uses it for every new app hostname and every certificate renewal. If another process owns port 80 or 443, use `tunnel` mode. ### Run the installer To install Orchard on the machine: 1. Run the installer: ```bash curl -fsSL https://assets.orchard.my/install.sh -o orchard-install.sh && sudo bash orchard-install.sh ``` 2. Answer the questions. Each question shows a default in brackets. To accept it, press Enter. For the full list, refer to [Installer questions](#installer-questions). 3. Review your answers. To install, press Enter. To change an answer, type its number. To cancel, type `c`. The installer checks the machine before it asks anything, and it installs nothing before you confirm this screen. 4. Create the DNS records that the installer prints, then select **Check again**. For more information, refer to [Add DNS records](#add-dns-records). 5. Copy the claim link that the installer prints when it finishes. The installer writes its settings to `/etc/orchard/values.yaml` and to the Orchard database. Next, [claim the instance](#claim-the-instance). > **Note** > > Download the script to a file and run it, as shown. If you pipe the script into `sudo bash` with no flags, the installer cannot read your answers, so it stops before it installs anything. Do not pass the script to `bash -c`, because it is too long for a single command-line argument. To read the script before you run it: ```bash curl -fsSL https://assets.orchard.my/install.sh -o orchard-install.sh less orchard-install.sh sudo bash orchard-install.sh ``` ### Installer questions The installer asks these questions in order. A flag or an environment variable answers a question in advance, so the installer does not ask it. The answer still appears on the review screen. | Question | Default | Flag | Environment variable | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------- | | Ingress mode | Based on the machine's network | `--mode` | `ORCHARD_INGRESS_MODE` | | Cloudflare Tunnel token, in `tunnel` mode | None. Required in `tunnel` mode. | `--tunnel-token` | `ORCHARD_TUNNEL_TOKEN` | | Public IP | The detected address. In `lan` mode, the local address. In `tunnel` mode, none. | `--public-ip` | `ORCHARD_PUBLIC_IP` | | Dashboard domain | An `sslip.io` name. In `lan` mode, the local address. Required in `tunnel` mode. | `--domain` | `ORCHARD_DOMAIN` | | Apps domain | `apps.`. In `tunnel` mode, the parent of your domain. | `--app-domain` | `ORCHARD_APP_DOMAIN` | | Custom domains target | The dashboard domain. In `tunnel` mode, `.cfargotunnel.com`. In `lan` mode, an `sslip.io` name. | `--ingress-cname` | `ORCHARD_INGRESS_CNAME` | | MCP endpoint, and its hostname | On, at `mcp.` | `--mcp`, `--mcp-domain` | `ORCHARD_MCP`, `ORCHARD_MCP_DOMAIN` | | Let's Encrypt email, in `public` mode | None | `--email` | `ORCHARD_ACME_EMAIL` | | Updates | `manual` | `--updates` | `ORCHARD_UPDATE_POLICY` | | S3 storage | None | `--s3-*`, `--no-s3` | `ORCHARD_S3_*` | The review screen also has one answer that the installer does not ask for: [resource limits](/operate/resource-limits/#choose-at-install). By default, you choose them during setup in the dashboard. To set them from the installer, change this answer on the review screen or use `--limits`. You can still change the value in the dashboard. To leave the public IP, the custom domains target, or the email blank, type `none`. The result of each blank answer is: - **Public IP:** Raw TCP and UDP ports and public databases are unavailable until you set an address. - **Custom domains target:** Custom domains still work, but Orchard does not check their DNS before it requests a certificate. - **Email:** Let's Encrypt has no address for notices about your account. Certificates still issue and renew. The MCP hostname can be any name. A name directly under your apps domain, such as `mcp.apps.example.com`, needs no DNS record of its own, because the wildcard record covers it. Orchard reserves this name, so no app can take it. ### Add DNS records For `public` mode with your own domain, the installer prints the records to create, computed from your answers. For example: ```txt Type Name Value A orchard.example.com 203.0.113.10 A *.apps.example.com 203.0.113.10 A mcp.example.com 203.0.113.10 ``` To find the machine's public address, the installer asks `api.ipify.org`, `ipv4.icanhazip.com`, and `api6.ipify.org`. It then queries public DNS resolvers, `1.1.1.1` and `8.8.8.8` directly or `cloudflare-dns.com` and `dns.google` over HTTPS, and shows the status of each record. It does not wait in silence, and it does not stop the install. You can choose **Check again**, **Continue anyway**, **Skip DNS for now**, or **Change an answer**. | Status | Meaning | What to do | | ------------- | ----------------------------------------------- | --------------------------------------------------------------------------- | | `resolves` | The record points at this machine. | Nothing. | | `waiting` | Public DNS has no answer yet. | Create the record, or wait for it to propagate. | | `wrong value` | The record points somewhere else. | Change the record. The old value can stay in caches for as long as its TTL. | | `proxied` | The record answers with a Cloudflare address. | Refer to the following table. | | `not checked` | This machine could not reach a public resolver. | Check the record from another machine. | If you skip DNS or continue without it, Orchard installs. The dashboard, the claim link, and certificates do not work until the records are right. cert-manager retries on its own, first after about an hour. The summary at the end of the install lists what is still pending. These cases need more than a new record: | Case | What the installer reports | What to do | | ---------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Cloudflare proxy (orange cloud) | `proxied`, with the Cloudflare address it found | Set the record to **DNS only**. If you keep the proxy, turn off **Always Use HTTPS** so that Let's Encrypt can reach port 80, and set SSL mode to **Full (strict)**. Raw ports and databases do not pass through the proxy, and the free Cloudflare certificate does not cover names such as `*.apps.example.com`. | | No wildcard records at your DNS provider | `waiting` on the wildcard line | Add one record for each app as you deploy it, or move the domain to a provider that supports wildcards. | | Subdomain delegated to other nameservers | The zone, its nameservers, and the parent it was delegated from | Create the records at the provider for the delegated zone. | | A website already on the top of the zone | `wrong value`, and a warning about that site | Use a subdomain for the dashboard, such as `orchard.example.com`, to keep the site where it is. | | Split-horizon DNS, or an entry in `/etc/hosts` | Both the answer on this machine and the public answer | Create the public record. Let's Encrypt only uses public DNS. | | A private address in public DNS | `wrong value`, and the address | Point the record at the public address, or use `lan` mode. | | Ports 80 or 443 blocked by a provider firewall | A warning that names the firewall to open | Allow both ports. A test from the machine can only find this behind 1:1 NAT. On a machine that has the public address itself, the summary reports it when Let's Encrypt fails. | | Machine with both IPv4 and IPv6 addresses | A note not to add `AAAA` records | Create `A` records only. Orchard listens on IPv4 only. | | CAA records that exclude Let's Encrypt | A warning with the record to add | Add `0 issue "letsencrypt.org"` to the zone. | For `tunnel` mode, the installer prints the hostnames to add to your tunnel: ```txt Type Name Value CNAME orchard.example.com .cfargotunnel.com CNAME *.example.com .cfargotunnel.com ``` 1. In Cloudflare, go to **Zero Trust** > **Networks** > **Tunnels**, and select your tunnel. 2. Select **Public Hostname**. 3. Add each name, with the service `http://traefik.traefik.svc.cluster.local:80`. Cloudflare creates the CNAME for each name except the wildcard. 4. Go to **DNS** > **Records**, and add the wildcard as a proxied CNAME to the value that the installer printed. Cloudflare's free certificate covers your domain and one level under it. For this reason, the apps domain defaults to the parent of your dashboard name in `tunnel` mode, so that apps are at `*.example.com`. A name deeper than one level, such as `*.apps.example.com` or `orchard.dev.example.com`, needs Advanced Certificate Manager. Without it, HTTPS fails at Cloudflare with a handshake error, even when the tunnel is healthy. The installer warns you about these names, and the summary reports a failed connection. For `lan` mode, you do not need public DNS. For more information, refer to [Use `lan` mode](#use-lan-mode) and [Use Tailscale](#use-tailscale). ### Try Orchard without a domain In `public` mode, you can try Orchard before you point a domain at the machine. The installer offers a name from [sslip.io](https://sslip.io), a public DNS service that answers with the IP address in the name. 1. Run the installer and select `public` mode. 2. At the dashboard domain question, press Enter. The dashboard is then at `https://orchard..sslip.io`, with dashes in the IP address. You do not need to add DNS records. Let's Encrypt issues the certificates over HTTP-01, so ports 80 and 443 must be reachable from the internet. > **Caution** > > Use `sslip.io` for trials only. Let's Encrypt limits the certificates issued for each registered domain, and `sslip.io` is not on the Public Suffix List, so all its users share one limit. Its operators report a raised limit of 250,000 certificates, and they also say that requests can be rate limited. If the limit applies, the dashboard shows a browser warning until cert-manager succeeds on a later retry. The installer reports this when it finishes. ### Move to your own domain To move an instance from `sslip.io` to a domain you own: 1. Run the installer again: ```bash curl -fsSL https://assets.orchard.my/install.sh -o orchard-install.sh && sudo bash orchard-install.sh ``` 2. On the review screen, type the number of **Dashboard**, and enter your domain. The apps domain, the MCP hostname, and the custom domains target follow it. 3. Press Enter to apply, and create the DNS records that the installer prints. Apps that you already deployed keep their `sslip.io` URLs. To give an app a new URL, add a domain to the app. ### Run the installer again To pick up new host commands or change a setting, run the installer again. It reads your current settings first and goes straight to the review screen, with each setting as the current answer. Anything that you leave alone does not change. With `--yes`, it keeps every setting that no flag names. It does not rotate secrets. This includes everything in `/etc/orchard/values.yaml`, such as values that you set with [`orchardctl config set`](/operate/host-commands/#config) or [`orchardctl env set`](/operate/host-commands/#env), or edited by hand. A value changes only when you change an answer that it depends on. For example, a new dashboard domain updates `ingress.host` and `FRONTEND_URL`, and `signupMode` stays as it is. When you change an answer, the installer states what the change affects: | Change | What it affects | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Dashboard domain | Everyone signs in again. Passkeys belong to the old name and stop working, so use a password or `sudo orchardctl login`. The GitHub App and any SSO provider keep the old URL until you update them. | | Apps domain | Only new apps use it. Deployed apps keep their URLs, including after a redeploy, while DNS for the old name points at the machine. To move an app, add a domain to it. | | MCP hostname | Agents must reconnect at the new URL. | | Custom domains target | Domains already added keep working while their CNAME still reaches the machine. Orchard checks new domains against the new target. | | Public IP | Ports and databases that are already public stay on the old address until you turn public access off and on again. | Before the installer changes the values file, it does the following: - It prints each setting that changes. It hides the values of secrets. - It saves a copy of the file as `/etc/orchard/values.yaml.-