# Hack Club Orchard documentation Orchard is a self-hosted platform. It installs on a Linux server or a Kubernetes cluster and deploys apps from a repository or an image. --- # Agent setup > Connect your coding agent to Orchard, then deploy and debug from your editor or terminal. Source: https://docs.orchard.hackclub.com/agent-setup/ Paste this prompt into your coding agent: ```text Connect to my Orchard instance over MCP. Follow https://docs.orchard.hackclub.com/agent-setup.md. Ask me for my Orchard domain first. ``` ## Find your MCP URL Replace `your-orchard-domain` in the examples with your domain. To get the exact URL, select **Account settings** > **MCP** from the account menu. ```text https://mcp.your-orchard-domain/ ``` ## Pick your client ### Claude Code 1. Add the server: ```sh claude mcp add --transport http orchard https://mcp.your-orchard-domain/ ``` 2. Run `/mcp` in Claude Code. Sign in to Orchard and approve the connection. 3. To share the server with a project, add `.mcp.json` instead: ```json { "mcpServers": { "orchard": { "type": "http", "url": "https://mcp.your-orchard-domain/" } } } ``` ### Codex 1. Add the server: ```sh codex mcp add orchard --url https://mcp.your-orchard-domain/ ``` 2. Sign in to Orchard and approve the connection: ```sh codex mcp login orchard ``` ### Cursor 1. Add `.cursor/mcp.json` to a project, or `~/.cursor/mcp.json` for every project: ```json { "mcpServers": { "orchard": { "url": "https://mcp.your-orchard-domain/" } } } ``` 2. Sign in to Orchard and approve the connection when Cursor asks. ### VS Code 1. Add `.vscode/mcp.json` to your project: ```json { "servers": { "orchard": { "type": "http", "url": "https://mcp.your-orchard-domain/" } } } ``` 2. Sign in to Orchard and approve the connection when VS Code asks. ### Claude.ai 1. In Claude, open **Settings** > **Connectors** and select **Add custom connector**. 2. Paste the server URL: ```sh https://mcp.your-orchard-domain/ ``` 3. Sign in to Orchard and approve the connection. ### Other clients - **Amp:** Run this command, then sign in to Orchard and approve the connection. ```sh amp mcp add orchard 'https://mcp.your-orchard-domain/' ``` - **Clients without OAuth:** Create an API token. ```sh orchard auth token create --name ci-agent --scope deploy ``` - Send the token as a bearer token. ```json { "mcpServers": { "orchard": { "type": "http", "url": "https://mcp.your-orchard-domain/", "headers": { "Authorization": "Bearer " } } } } ``` ## Limit what an agent can do Add parameters to the server URL. They can only lower what a connection gets. - Read-only tools: `https://mcp.your-orchard-domain/?scope=read` - No `exec_in_pod`: `https://mcp.your-orchard-domain/?scope=deploy` - Selected toolsets: `https://mcp.your-orchard-domain/?toolsets=databases,domains` - The whole API in three tools: `https://mcp.your-orchard-domain/compact` ## Example prompts Paste these into a connected agent. Each prompt names the tools it uses. ### Deploy a repository Requires a linked GitHub account. ```text Deploy https://github.com/owner/repo to Orchard. Check access with list_github_deploy_targets, deploy with deploy_from_github_url, then wait on get_deployment_rollout and give me the URL. ``` Tools: `list_github_deploy_targets`, `deploy_from_github_url`, `get_deployment_rollout` ### Find out why an app is failing Read-only. Works with `?scope=read`. ```text The api app is failing. Call diagnose_deployment, then read get_deployment_logs and get_killed_container_logs. Tell me the cause. Do not change anything. ``` Tools: `diagnose_deployment`, `get_deployment_logs`, `get_killed_container_logs` ### Create a database Stores the connection string as a secret variable. ```text Create a Postgres database named app-db with create_database. Get its connection string with get_database_connection, then add it to the api app as a secret DATABASE_URL with add_env_vars. ``` Tools: `create_database`, `get_database_connection`, `add_env_vars` ### Roll back a bad deploy Asks before it changes anything. ```text The latest release of the api app is failing. List recent releases with list_releases. Ask me before you run rollback_to_previous, then confirm with get_deployment_rollout. ``` Tools: `list_releases`, `rollback_to_previous`, `get_deployment_rollout` ### Check app resources Read-only. Works with `?scope=read`. ```text Check whether the api app has the right CPU and memory. Use get_resource_recommendation and get_deployment_metrics. Do not change anything. ``` Tools: `get_resource_recommendation`, `get_deployment_metrics` ### Check a domain Run this before you create an ingress. ```text Run validate_dns for app.example.com and tell me which records to create. ``` Tools: `validate_dns` ## More - [MCP for agents](/mcp.md) - [MCP tools](/reference/mcp-tools.md) - [Code mode for agents](/agents-code-mode.md) --- # Keyboard shortcuts and search > Use the Orchard command palette to find projects, apps, databases, and jobs, and to run common actions from the keyboard. Source: https://docs.orchard.hackclub.com/account/command-palette/ The command palette lets you reach anything in your organization without the mouse. It searches your projects, apps, databases, and jobs, and runs common actions such as creating an app or switching to dark mode. To open the command palette, press `CMD + K` on macOS or `CTRL + K` on other systems. ## Search Enter text to find these resources: - Projects - Apps - Databases - Jobs Select a result to open it. ## Actions The command palette includes these actions: - **New app** - **New database** - **New job** - **New project** - **Toggle dark mode** - **Usage** - **Invite a teammate** - **Organization settings** - **Account settings** - **Copy organization ID** - **Open docs** - **Sign out** ## Keyboard shortcuts | Action | macOS | | ---------------------------------------- | ----------------- | | Open or close the command palette | `CMD + K` | | Toggle the sidebar | `CMD + B` | | Toggle dark mode, in the command palette | `CMD + SHIFT + L` | | Open the docs, in the command palette | `CMD + /` | | Collapse the console on an app page | `ESC` | On other systems, use `CTRL` instead of `CMD`. The dark mode and docs shortcuts work only while the command palette is open. ## Related resources - [Set your preferences](/account/preferences/) - Change the theme, typeface, motion, and text size of the dashboard. - [Use the terminal dashboard](/run/terminal-dashboard/) - Work with Orchard from the keyboard in a terminal instead of a browser. - [Workspace keyboard shortcuts](/greenhouse/workspace/#keyboard-shortcuts) - Shortcuts for the Greenhouse workspace. --- # Set your preferences > Change the theme, typeface, motion, text size, contrast, and log timestamps of the Orchard dashboard in your browser. Source: https://docs.orchard.hackclub.com/account/preferences/ Preferences change how the dashboard looks and behaves for you: its colors, its typeface, how much it moves, and how log timestamps read. Orchard stores them in your browser instead of your account, so they do not follow you to another browser and do not affect other people. ## Change the theme 1. Go to **Account settings** > **Appearance**. 2. In **Theme**, drag the wheel to change all colors at the same time. 3. (Optional) In **Classic**, select a fixed theme from earlier versions of Orchard. 4. (Optional) Open **Advanced colors** to change individual colors. 5. To keep the theme, select **Save theme**. 6. Enter a name. Saved themes appear in **Saved themes**. To move a theme to another browser, select the more actions icon in **Theme**. Then select **Export** or **Import**. ## Change the interface Go to **Account settings** > **Appearance** > **Interface**. | Setting | Description | | ------------------------------- | ----------------------------------------------------------------------------------- | | **Typeface** | The interface font. **Hyperlegible** and **Dyslexic** are designed for readability. | | **Project background gradient** | The animated background on project pages. Turning it off uses less GPU. | ## Change accessibility settings Go to **Account settings** > **Accessibility**. | Setting | Options | Description | | ----------------------- | ---------------------------------------------- | -------------------------------------------------------- | | **Animation** | **System**, **Full**, **Reduced**, **Off** | **System** follows your system's reduced motion setting. | | **Sound** | On or off | Plays a sound when a build you are waiting on finishes. | | **Text size** | **Small**, **Default**, **Large**, **Largest** | The size of text and the interface. | | **Increase contrast** | On or off | Uses darker text and visible borders. | | **Reduce transparency** | On or off | Uses solid panels instead of glass and blur. | ## Change log timestamps Go to **Account settings** > **Logs**. | Setting | Options | Description | | ---------------- | ------------------------------------------ | --------------------------------------------------- | | **Clock** | **System**, **12 hour**, **24 hour** | The clock format. | | **Time zone** | **Local**, **UTC** | **UTC** matches the times that the cluster records. | | **Date** | **When it changes**, **Always**, **Never** | When a log line shows its date. | | **Milliseconds** | On or off | Shows milliseconds in timestamps. | To read the full timestamp of a log line, hover over its timestamp. ## Try early access features **Account settings** > **Early access** lists features that are in development. Use the switch next to a feature to turn it on or off. The list comes from the PostHog project that the instance is configured with. If the dashboard has no PostHog key (`PUBLIC_POSTHOG_KEY`), the list shows `Nothing to try right now.` ## Related resources - [Set up notifications](/run/notifications/) - Choose which events reach you and where they are delivered. - [Keyboard shortcuts and search](/account/command-palette/) - Find resources and run actions from the keyboard. --- # Update your profile > Change your Orchard name, username, and profile photo. Source: https://docs.orchard.hackclub.com/account/profile/ Your profile is how other people see you in Orchard: your name, your username, and your photo. The profile belongs to your account instead of an organization, so a change here appears in every organization you belong to. ## Change your name or username 1. Go to **Account settings**. 2. In the header, select **Edit**. 3. Update **First name**, **Last name**, or **Username**. 4. Select **Save**. Orchard uses your username in URLs and mentions. You can also run `orchard user profile update`. The [CLI reference](/reference/cli/#user) lists its flags. ## Change your profile photo 1. Go to **Account settings**. 2. In the header, select your photo. 3. Select an image file. To remove the photo, use the remove control on the photo. Orchard does not import another picture after you remove one. To manage your photo from a terminal, use `orchard user avatar set` and `orchard user avatar delete`. Orchard generates a mascot for every account. The mascot appears until you have a photo. If your email address has a picture on Libravatar or Gravatar, Orchard imports a copy. Orchard fetches the picture from its server, so these services do not receive requests from your browser. An imported picture does not replace a photo that you upload. ## Related resources - [Set your preferences](/account/preferences/) - Change the theme, typeface, motion, and text size of the dashboard. - [Manage sign-in and sessions](/account/security/) - Add passkeys and sign out devices that you no longer use. --- # Manage sign-in and sessions > Choose how you sign in to Orchard, add passkeys, and sign out devices you no longer use. Source: https://docs.orchard.hackclub.com/account/security/ Your account is the key to every organization you belong to, so it is worth controlling how you sign in and where you stay signed in. This page covers the sign-in methods an instance offers, how to add a passkey, and how to sign out a device that you no longer use or trust. ## Sign-in methods The methods available to you depend on how your instance is configured. | Method | Availability | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Email code | The instance has [email configured](/operate/finishing-setup/#set-up-email). Without email, Orchard hides this option. | | Passkey | The instance is served over HTTPS. Browsers do not offer passkeys over plain HTTP. | | Identity provider | [A superadmin](/operate/finishing-setup/#add-an-identity-provider) or [your organization](/teams/sso/) has added a provider. | | Password | Superadmin accounts. On an instance with no email, also people who joined by [invitation link](/teams/organizations/). An operator can reset a password on the host. | | One-time link | An operator prints the link on the host. The link works once and expires after 10 minutes. | If your organization [requires single sign-on](/teams/sso/#require-single-sign-on), other methods stop working for your account. ## Add a passkey A passkey lets you sign in with Touch ID, Face ID, Windows Hello, or a hardware key. A passkey only works on the site that created it, so a phishing page cannot use it. 1. Go to **Account settings** > **Passkeys and devices**. 2. Select **Add passkey**. 3. (Optional) Enter a name for the passkey, such as `MacBook`. 4. Follow the prompts from your browser. Add more than one passkey if passkeys are your only sign-in method. If you lose your only passkey and your instance has no email, a superadmin must help you sign in. To rename or remove a passkey, select **Rename** or **Remove** on its row. ## Sign in on an instance without email An instance without email has no email codes. If you operate the instance, use one of the following commands on the host: ```bash sudo orchardctl login # print a one-time sign-in link sudo orchardctl password set # set a password on the superadmin account ``` For the options of each command, refer to [`orchardctl login`](/operate/host-commands/#login) and [`orchardctl password`](/operate/host-commands/#password). ## Review your devices The **Devices** list shows each session on your account, with its device name, location, IP address, and last activity. A browser session expires after seven days. [MCP connections](/mcp/#revoke-access) also appear in this list, because each connection is a session on your account. 1. Go to **Account settings** > **Passkeys and devices**. 2. Review the **Devices** list. ## Sign out of a device **Dashboard** To sign out one device: 1. Go to **Account settings** > **Passkeys and devices**. 2. In **Devices**, select **Sign out** on the device row. 3. Confirm with **Sign out**. To sign out every device except this one: 1. In **Devices**, select **Sign out others**. 2. Confirm with **Sign out all**. **CLI** ```bash orchard auth session list orchard auth session revoke orchard auth session revoke-all ``` > **Caution** > > Signing out all other devices also deletes every [API token](/account/tokens/) on your account. Scripts and CI jobs that use those tokens stop working. Your current session stays signed in. Use this option if you lose a device or think that someone else has access to your account. ## Related resources - [Manage API tokens](/account/tokens/) - Create and revoke the tokens that scripts, CI jobs, and MCP clients use. - [Set up SSO](/teams/sso/) - Let people in your organization sign in through your identity provider. - [Manage SSH identities](/account/ssh-identities/) - Add the public keys that reach your Greenhouse machines. --- # Manage SSH identities > Add, import, rotate, and remove the public SSH keys that give you access to your Greenhouse machines. Source: https://docs.orchard.hackclub.com/account/ssh-identities/ An SSH identity is a named public key on your account. Add one to connect to a [Greenhouse machine](/greenhouse/) from your own terminal or a local editor, such as VS Code or Zed over SSH. Orchard stores only the public key and never receives your private key. ## Prerequisites - The Greenhouse graft [installed on your instance](/operate/greenhouse/#install-the-graft). ## Generate a key with the CLI Use this option if you do not need a specific key. The following command generates a key for Orchard and registers it as an identity: ```bash orchard sandbox ssh-config --install ``` The command also adds an `orchard-*` entry to `~/.ssh/config`, so `ssh orchard-` works. To connect an editor this way, refer to [Connect an editor over SSH](/greenhouse/editors/). ## Add an identity **Dashboard** 1. Go to **Account settings** > **Greenhouse**. 2. In **SSH identities**, select **Add identity**. 3. In **Name**, enter a name, such as `laptop`. 4. In **Public key**, paste your public key. 5. Select **Add identity**. **CLI** ```bash orchard ssh-identity add laptop --key ~/.ssh/id_ed25519.pub ``` ## Import keys from GitHub Orchard reads `https://github.com/.keys` for your linked GitHub account and creates one identity for each key. **Dashboard** 1. Go to **Account settings** > **Greenhouse**. 2. In **SSH identities**, select **Import from GitHub**. **CLI** ```bash orchard ssh-identity import-github ``` ## Remove an identity Orchard refuses to remove an identity that is attached to a machine. The error names the machine: ```txt Identity is attached to sandbox "my-machine"; detach it first ``` 1. Attach another identity to the machine: ```bash orchard sandbox update --identity ``` 2. Remove the identity: ```bash orchard ssh-identity remove ``` ## Rotate a key 1. Add the new key as a new identity. 2. Attach the new identity to your machines. 3. Confirm that you can connect with the new key. 4. Remove the old identity. ## Related resources - [Machines](/greenhouse/machines/) - Create, start, and stop Greenhouse machines and attach identities to them. - [`orchard ssh-identity` reference](/reference/cli/#ssh-identity) - Every flag of the `orchard ssh-identity` commands. --- # Manage API tokens > Create, use, rename, and revoke Orchard personal API tokens for scripts, CI jobs, and MCP clients. Source: https://docs.orchard.hackclub.com/account/tokens/ A personal API token lets a script, a CI job, or an MCP client call Orchard without a browser. The token acts as your account, so it can never do more than you can, and you can limit it further with an access level, a lifetime, and a list of projects. > **Note** > > Interactive use of the [CLI](/cli/) does not need a token. `orchard auth login` creates and stores one for you. ## Token access levels Each token has one access level. Each level includes the level before it. | Level | Allows | | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `read` | Most read requests. Some reads that return secrets require `deploy`. | | `deploy` | `read`, plus requests that create, update, delete, scale, or restart. | | `exec` | `deploy`, plus [shells in pods](/run/logs/#open-a-shell) and databases, commands inside containers, and creating or editing sandboxes. | At any access level, a token cannot register a passkey, set a password, or call instance setup and admin routes. Tokens cannot manage an organization's SSO or SCIM, or change passkeys. A token restricted to projects also cannot use account routes, such as sessions, tokens, GitHub, or invitations, apart from reading its own user. ## Tokens and single sign-on An organization that [requires single sign-on](/teams/sso/#require-single-sign-on) only accepts tokens created after signing in through its provider. Such a token works in that organization and nowhere else, and its row in the list says so. It also cannot create more tokens. A token created any other way gets a `403` with the error `org_sso_required` in that organization, and keeps working in your other organizations. To fix this, sign in through the organization's provider and create a new token at **Account settings** > **API tokens**. Owners of the organization are exempt. ## Create a token **Dashboard** 1. Go to **Account settings** > **API tokens**. 2. Select **New token**. 3. In **Name**, enter a name that describes where you use the token. 4. In **Access**, select **Read**, **Deploy**, or **Exec**. 5. Select **Create token**. 6. Copy the token. Orchard does not show it again. 7. Select **Done**. **CLI** Run the following command: ```bash orchard auth token create --name ci --scope deploy ``` The command prints the token once. Copy it before you close the terminal. | Flag | Description | | -------------- | --------------------------------------------------------------------- | | `--name` | Token name. Required. | | `--scope` | `read`, `deploy`, or `exec`. The default is `read`. | | `--expires-in` | Lifetime, such as `30d` or `12h`. The default and maximum are `90d`. | | `--project` | Restrict the token to a project ID or slug. You can repeat this flag. | A token expires after 90 days unless you set a shorter lifetime. The dashboard always uses 90 days. To set a shorter lifetime or restrict a token to specific projects, use the CLI. ## Use a token Send the token in the `Authorization` header: ```bash curl "https://orchard.example.com/apiv1/auth/me" \ --header "Authorization: Bearer " ``` To use a token with the CLI, set the `ORCHARD_API_URL` and `ORCHARD_API_TOKEN` environment variables: ```bash export ORCHARD_API_URL=https://orchard.example.com export ORCHARD_API_TOKEN= ``` To use a token with an MCP client, refer to [Connect an MCP client](/mcp/#connect-with-an-api-token). ## Rename a token 1. Go to **Account settings** > **API tokens**. 2. On the token row, select **Rename**. 3. Enter the new name. 4. Save the name. ## Revoke a token Requests that use a revoked token fail immediately. **Dashboard** 1. Go to **Account settings** > **API tokens**. 2. On the token row, select **Revoke**. 3. Select **Revoke token**. **CLI** 1. List your tokens to find the token ID: ```bash orchard auth token list ``` 2. Revoke the token: ```bash orchard auth token revoke ``` > **Caution** > > [Signing out all other devices](/account/security/#sign-out-of-a-device) also deletes every API token on your account. ## Rotate a token 1. Create a new token. 2. Update the script, job, or client to use the new token. 3. Revoke the old token. ## Related resources - [Update an app with a webhook](/run/webhooks/) - Redeploy an app from CI with a deploy webhook token instead of a personal token. - [Set up SCIM provisioning](/teams/scim/) - Sync people from your identity provider with an organization token. - [`orchard auth` reference](/reference/cli/#auth) - Every flag of the sign-in, session, and token commands. --- # Code mode for agents > Call the whole Orchard API from an agent with the orchard CLI or the compact MCP server, without loading every MCP tool into context. Source: https://docs.orchard.hackclub.com/agents-code-mode/ Code mode lets an agent reach every Orchard API operation without loading a tool definition for each one. Instead, the agent searches a spec, reads the contract for the operation it needs, and calls it by ID, either through the CLI or through the compact MCP server. Use code mode when a task needs an operation that the [full MCP server](/mcp/) does not cover, or when describing every operation to a model would use more context than the task has. | Your agent has | Use | | -------------------------------------------------- | ---------------------------------------------------------------------- | | A shell, such as Claude Code, Codex, Cursor, or CI | The CLI: `orchard api search`, `describe`, and calls by `operationId`. | | No shell, such as claude.ai or another chat app | The compact MCP server at `/compact`. | Neither option runs model-written code on Orchard. ## The agent spec Both options read the agent spec, a trimmed copy of the OpenAPI contract. For each operation, the spec has the `operationId`, parameters, request and response schemas, [required scope](/account/tokens/#token-access-levels), and two flags: - `x-orchard-destructive` marks deletes, whole-list replacements, and other operations that remove or overwrite state. - `x-orchard-sensitive` marks responses that contain a secret. Both spec files are public and served with an `ETag`: ```txt GET https://orchard.example.com/apiv1/agent-spec.json GET https://orchard.example.com/apiv1/openapi.json ``` `agent-spec.json` leaves out admin, setup, SCIM, SSO, and sign-in routes. `openapi.json` is the complete document. Operation IDs come from the route: the path words, then a verb. | Route | `operationId` | | ------------------------------- | -------------------------- | | `GET /deployments` | `deployments_list` | | `GET /deployments/:id` | `deployments_get` | | `GET /deployments/:id/rollout` | `deployments_rollout_get` | | `POST /deployments/:id/restart` | `deployments_restart` | | `PUT /deployments/:id/env` | `deployments_env_set` | | `GET /databases/:id/connection` | `databases_connection_get` | ## Call the API from a shell The CLI caches the spec for each instance in `~/.orchard/agent-spec..json` and revalidates it at most once an hour. To cache it somewhere else, set `ORCHARD_SPEC_CACHE_DIR`. Search works offline after the first fetch. ```bash orchard api search "deployment logs" orchard api describe deployments_rollout_get orchard api deployments_rollout_get -p id=$DEPLOYMENT -q wait=1 -q timeout=120 orchard api deployments_env_set -p id=$DEPLOYMENT -d @env.json --yes ``` | Flag | Purpose | | ------- | ---------------------------------------------------- | | `-p` | Fills a path parameter. | | `-q` | Adds a query parameter. | | `-d` | Sends a JSON body, a `@file`, or `-` for stdin. | | `--yes` | Confirms a destructive operation without a terminal. | `orchard api GET /path` also works, and does not use the spec. Output is JSON when stdout is not a terminal. ### Deploy and wait until the app is live ```bash since=$(orchard api deployments_rebuild -p id=$APP | jq -r .rolloutSince) orchard api deployments_rollout_get -p id=$APP -q wait=1 -q timeout=120 -q since=$since \ | jq '{phase, url, hint, error: .build.error}' ``` ### Find crashing apps in a project ```bash orchard api projects_deployments_list -p id=$PROJECT | jq -r '.[].id' | while read -r id; do orchard api deployments_rollout_get -p id=$id | jq -c --arg id "$id" 'select(.phase == "crashing" or .phase == "unhealthy" or .phase == "build_failed") | {id: $id, phase, hint, failing: [.pods.failing[]? | {pod, reason, exitCode}]}' done ``` ### Set one variable on every app in a project [Secret values](/run/environments/#secrets) read back as `null`. Sending `null` keeps the stored value, so this script does not need to know any secret. ```bash for id in $(orchard api projects_deployments_list -p id=$PROJECT | jq -r '.[].id'); do orchard api deployments_get -p id=$id | jq '{env: ([.envVars[] | {key, value, secret}] | map(select(.key != "LOG_LEVEL")) + [{key: "LOG_LEVEL", value: "info"}])}' | orchard api deployments_env_set -p id=$id -d - --yes done ``` ### Call the API from Node.js ```js const base = process.env.ORCHARD_API_URL; const headers = { Authorization: `Bearer ${process.env.ORCHARD_API_TOKEN}` }; const api = (path) => fetch(`${base}/apiv1${path}`, { headers }).then((r) => r.json()); const deployments = await api(`/projects/${process.env.PROJECT}/deployments`); for (const d of deployments) { const rollout = await api(`/deployments/${d.id}/rollout`); if (!['live', 'stopped'].includes(rollout.phase)) console.log(d.name, rollout.phase, rollout.hint); } ``` The API allows 600 requests a minute for each token. Use `wait=1` on the rollout endpoint instead of polling. ## Connect the compact MCP server Point the client at `/compact` on the MCP host: ```bash claude mcp add --transport http orchard-compact https://mcp.example.com/compact ``` Authentication works the same as on the full server. Use OAuth with `mcp:read`, `mcp:deploy`, or `mcp:exec`, or an `orch_` token, as described in [Connect an MCP client](/mcp/). The server has three tools: | Tool | Purpose | | -------------------- | ----------------------------------------------------------------------------- | | `search_api` | Finds operations by keyword. Returns IDs, paths, and flags, best match first. | | `describe_operation` | Returns the full contract for one `operationId` or `"METHOD /path"`. | | `call_api` | Runs one operation as you, with `pathParams`, `query`, `body`, and `fields`. | `call_api` has the following limits: - **Destructive operations:** The call fails unless `confirm` is set to the `operationId`. - **`fields`:** The response keeps only the dotted paths that you list, such as `["items.id","items.status"]`. - **Output size:** Orchard cuts output over 24,000 characters and adds a note to narrow the request. - **Scope:** Orchard refuses operations that need a higher scope than the connection has. The error names the required scope. Results from operations flagged `x-orchard-sensitive` carry `_meta: { "orchard/sensitive": true }`. Each call is one turn for the model. Scripts in a shell need fewer turns for work that chains several calls. ## Related resources - [Use the CLI](/cli/) - Install the CLI, sign in, and set the defaults that `orchard api` uses. - [Docs for agents](/for-agents/) - Give an agent this documentation as Markdown or `llms.txt`. - [`orchard api` reference](/reference/cli/#api) - Every flag of `orchard api`, `search`, and `describe`. --- # Use the CLI > Install the Orchard CLI, sign in to an instance, set a default project, and script commands with JSON output. Source: https://docs.orchard.hackclub.com/cli/ The `orchard` command-line interface (CLI) calls the same API as the dashboard. Use it to deploy apps, read logs, and manage databases from a terminal, a script, or a CI job. Output is a table in a terminal and JSON when piped, and exit codes are stable, so scripts can rely on both. This page covers installing the CLI, signing in, and choosing what a command acts on. For every command and flag, refer to the [CLI reference](/reference/cli/). To run commands on the machine that hosts Orchard, use [host commands](/operate/host-commands/) instead. ## Install the CLI To install with Homebrew, run the following command: ```bash brew install --cask leafdtk/tap/orchard-cli ``` The cask is named `orchard-cli`. The installed command is `orchard`. To install without Homebrew, run the following install script: ```bash curl -fsSL https://raw.githubusercontent.com/LeafdTK/orchard-releases/main/install.sh | sh ``` To confirm the installation, run the following command: ```bash orchard version ``` ## Sign in To sign in to an instance, run the following command: ```bash orchard auth login --api-url https://orchard.example.com ``` The command opens a browser. After you approve the request, the CLI stores a token in `~/.orchard/config.json`. The CLI has no default instance. If no instance is set up and you run `orchard auth login` without `--api-url`, the CLI asks for the URL of your instance. The CLI checks that the URL is an Orchard instance, adds a context for it, and continues to sign-in. The first command that needs an instance does the same. After the first sign-in, `orchard auth login` signs in to the current context. To add another instance, pass `--api-url`. Without a terminal or in CI, the CLI never asks. If no instance is set up, the command stops with an error. Pass `--api-url` to `orchard auth login` or set `ORCHARD_API_URL`. ## Work with several instances Each instance you sign in to becomes a context: its URL, your token for it, and the default organization, project and environment you set with `orchard use`. Signing in to another instance adds a context and switches to it. ```bash orchard auth login --api-url https://staging.example.com --name staging orchard context list orchard context use # pick from a list orchard context use staging ``` To run a single command against another instance, pass `--context ` or set `ORCHARD_CONTEXT`. To rename a context, run `orchard context rename`. To forget a context and its token, run `orchard context remove`. To sign in on a machine with no browser, add `--no-browser`. The CLI prints a URL and the local port that it listens on. Forward that port to your own machine with `ssh -L` before you open the URL. Without a terminal, the CLI cannot ask which instance to use, so also pass `--api-url` or set `ORCHARD_API_URL`. To authenticate a script, set the instance URL and a token in the environment. A token in the environment overrides a stored token. ```bash export ORCHARD_API_URL=https://orchard.example.com export ORCHARD_API_TOKEN= ``` To create a token, refer to [Manage API tokens](/account/tokens/). ## Choose an organization and project Most commands act on an organization, a project, or an environment. Orchard uses the first value it finds, in the following order: 1. The `--org`, `--project`, and `--env` flags. 2. The `ORCHARD_ORG`, `ORCHARD_PROJECT`, and `ORCHARD_ENV` environment variables. 3. The saved context from `orchard use`. To save a context, run the following commands: ```bash orchard use org my-org orchard use project my-app orchard context show ``` To link a directory to a project, run `orchard link --project my-app` in that directory. The command writes `.orchard/project.json`. Commands that you run from that directory then use the project. ## Common commands | Task | Command | | -------------------------------------------------------------------------------------- | ------------------------------------ | | List apps | `orchard deploy list` | | [Scale an app](/deploy/scaling/#change-replicas) | `orchard deploy scale 3` | | [Read or follow logs](/run/logs/) | `orchard logs -f` | | [Build and deploy the current directory](/deploy/deploy-from-terminal/) | `orchard up` | | [Write variables to `.env.orchard`](/run/environments/#pull-variables-to-a-local-file) | `orchard env pull` | | List databases | `orchard db list` | | [Run a job](/run/jobs/) | `orchard job run ` | | [Roll back an app](/deploy/rollbacks/) | `orchard deploy rollback --yes` | ## Use the CLI in scripts The CLI writes JSON to stdout when stdout is not a terminal. To request JSON in a terminal, add `-o json`. Status and warnings go to stderr. ```bash orchard deploy list -o json | jq -r '.[].name' ``` Destructive commands ask for confirmation in a terminal. Without a terminal, they fail with exit code `2` unless you pass `--yes`. To block until a deploy finishes, add `--wait`: ```bash orchard deploy rebuild --wait --timeout 15m ``` To list every command and flag as JSON, run the following command: ```bash orchard commands -o json ``` ### Exit codes | Code | Meaning | | ----- | ---------------------------------------------------------------------------------------------------- | | `0` | Success | | `1` | General or network error, or no token configured | | `2` | Usage error, or a refused confirmation | | `3` | Authentication rejected (HTTP 401) | | `4` | Not found (HTTP 404) | | `5` | Request rejected (other HTTP 4xx, including a missing scope) | | `6` | Rate limited (HTTP 429) | | `7` | Server error (HTTP 5xx) | | `8` | The request deadline passed, or `--wait` reached `--timeout` | | `9` | The build failed during a wait | | `10` | Pods are crash-looping or the rollout is unhealthy, or `orchard db diagnose` found the database down | | `11` | `orchard doctor` found at least one failing check | | `130` | Interrupted | ## Related resources - [Code mode for agents](/agents-code-mode/) - Let a coding agent drive Orchard through the CLI instead of MCP. - [Use the terminal dashboard](/run/terminal-dashboard/) - Read logs, deploy, scale, and manage databases from an interactive dashboard in your terminal. - [`orchard auth` reference](/reference/cli/#auth) - Every sign-in, session, and token command. --- # Back up and restore a database > Back up an Orchard managed database, take checkpoints, restore to a point in time, copy a database, recover a deleted database, and configure backup storage. Source: https://docs.orchard.hackclub.com/data/backups/ Backups let you undo a bad migration, bring back a dropped table, or recover a deleted database. Orchard backs up managed databases to S3-compatible object storage. Each database continuously archives its write-ahead log (WAL) and takes a daily base backup. A base backup is a full copy of the database, and WAL is the stream of changes that Orchard replays onto a base backup, which is why you can restore to any moment rather than only to the last backup. You can restore from a backup, from a checkpoint, or to any moment in the recovery window. Orchard keeps backups and WAL for 30 days. ## Prerequisites A database needs one of these storage locations. The organization's bucket takes priority. - An organization bucket, set under **Organization settings** > **Backups**. - The instance bucket, which an operator sets up as described in [Backup storage for operators](#backup-storage-for-operators). Without storage, the **Backups** tab shows **Backups need storage**. Checkpoints, the drop guard, and restore tests are not available. ## Take a backup **Dashboard** 1. Open the database. 2. Go to **Backups**. 3. Select **Save a point** > **Backup**. The backup appears in **Restore points** with its status. **CLI** ```sh orchard db backup create --wait ``` ## Set the schedule Orchard gives each new database a daily schedule. To change it: **Dashboard** 1. Open the database. 2. Go to **Backups**. 3. In **Schedule**, select a preset. For another schedule, select **Custom cron…**, enter a five-field cron expression in UTC, and select **Apply**. **CLI** ```sh orchard db backup-schedule set --cron "0 3 * * *" ``` ## Take a checkpoint A checkpoint is a named restore point: a marker in the WAL. It does not copy data, and it needs at least one completed backup. **Dashboard** 1. Open the database. 2. Go to **Backups**. 3. Select **Save a point** > **Checkpoint**. 4. (Optional) In **Label**, enter a name. 5. Select **Take checkpoint**. To checkpoint every database in a project, open the project's **Overview**, select **More actions**, then **Checkpoint all databases**. **CLI** ```sh orchard db checkpoint create --label "Before the users migration" ``` Without a database ID, the command takes a checkpoint of every database in the project or environment. A checkpoint shows as pending until its WAL reaches object storage. You can restore it after that. Checkpoints expire after 30 days. Orchard also takes checkpoints automatically: | Type | When Orchard takes it | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Before a drop** | Before any `DROP TABLE`, `DROP SCHEMA`, or `DROP COLUMN` runs, when **Checkpoint before drops** is on. The checkpoint records what was dropped and by whom. This check does not cover `TRUNCATE`. | | **Before a deploy** | Before an app that references the database deploys, so that a [rollback](/deploy/rollbacks/) can also restore the app's databases. | | **Before a change** | Before an operation that changes the database, such as an in-place restore or a [major upgrade](/data/upgrades/). | ## Restore a database You can restore in two ways. | Option | Result | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Replace this database** | Orchard takes a checkpoint, then swaps in the restored copy. It keeps the previous copy stopped for 24 hours, so you can undo the restore. Apps reconnect automatically. | | **Copy into a new database** | The original keeps running. The copy keeps the source's database name, so an app that connects to it finds its tables. | **Dashboard** 1. Open the database. 2. Go to **Backups**. 3. Select **Restore**. 4. In **Point to restore to**, select **Latest**, **A backup**, **A checkpoint**, or **A time**. When you copy a database, **Now** replaces **Latest** and copies the live data. 5. In **Where to restore**, select **Replace this database** or **Copy into a new database**. 6. For a copy, enter a **Name**. 7. For a copy, select an **Environment**. 8. Select **Restore** or **Create copy**. The operation appears in **Operations** on the same tab. **CLI** To restore in place to a point in time: ```sh orchard db backup restore --at 2026-11-03T14:30:00Z --wait ``` To restore to a checkpoint: ```sh orchard db checkpoint restore --wait ``` To copy a database from now, a backup, a checkpoint, or a point in time: ```sh orchard db fork --name appdb-copy --wait ``` For the source, add `--backup`, `--checkpoint`, or `--at`. To start a new database from an existing one, select **Copy of a database** in **Start from** when you [create a database](/data/databases/#create-a-database). ### Undo a restore You can undo an in-place restore for 24 hours. **Dashboard** 1. Open the database. 2. Go to **Backups**. 3. In **Operations**, select **Undo** on the restore. 4. Select **Undo restore**. Orchard moves aside anything written since the restore. **CLI** ```sh orchard db ops undo --wait ``` ## Recover a deleted database A deleted database stays in **Recently deleted** for 30 days, and Orchard then purges it. You can bring it back only if it had at least one completed backup, because recovery replays that backup. **Dashboard** 1. Open the project's **Overview**. 2. In **Recently deleted**, select **Bring back**. **CLI** ```sh orchard db trash list orchard db trash restore --wait ``` To block deletion, turn on **Deletion protection** as described in [Protect a database](/data/protection/). ## Test a backup A restore test restores the latest backup into a temporary copy, compares its tables and estimated row counts with the source, and deletes the copy. A failed test sends a [notification](/run/notifications/). **Dashboard** 1. Open the database. 2. Go to **Backups**. 3. In **Restore tests**, select **Test this backup**. To run a test every week, turn on **Weekly restore tests** under **Settings** > **Protection**. **CLI** ```sh orchard db test-backup run --wait ``` Superadmins set instance-wide defaults under **Instance admin** > **Configuration** > **Databases**. By default, checkpoints before drops are on and weekly restore tests are off. ## Verify your backups > **Caution** > > WAL alone cannot restore a database. If no base backup has completed, a deleted database cannot be recovered. 1. Open the database. 2. Go to **Backups**. 3. Confirm that the status reads **Protected**. 4. In **Restore tests**, select **Test this backup**. In the API, an empty `liveStatus.firstRecoverabilityPoint` means no base backup has completed. ## How backups use memory The base backup runs inside the database container and shares its [memory limit](/data/databases/#set-cpu-and-memory) with Postgres. Compressing a backup on a small database can use enough memory for the kernel to kill Postgres. For this reason, Orchard chooses base backup compression from the memory limit. To override the choice, set `backupCompression` through the database settings API. Orchard always compresses WAL, one segment at a time. ## Retention Orchard removes backups and WAL older than 30 days. This limit also sets how far back point-in-time restore and checkpoints reach. If your bucket has its own lifecycle rule, keep objects for longer than 30 days. A shorter rule deletes backups Orchard still needs. ## Backup storage for operators To set up instance storage, refer to [Add S3 storage](/operate/storage/). The setup flow, **Instance admin**, `orchardctl backups s3`, and the installer all save the same settings. Any S3-compatible service works. ### Organization backup endpoints The server checks an organization's own backup endpoint when it is saved and again every time it connects, so a hostname that later resolves to a private address is refused. Set `BACKUP_ALLOW_INTERNAL_ENDPOINT=true` to allow private endpoints. Database pods write their own backups to the endpoint, and the tenant network policy lets them reach any public address. That policy does not limit them to the endpoint an organization saved. If you need an allowlist of backup destinations, enforce it at the node or cloud firewall. ### The store on the server The one-command installer runs an S3 store (versitygw) in the `orchard-object-storage` namespace, with the backup proxy, and sends the instance's backups to it. Checkpoints, point-in-time restore, copies, deleted database recovery, and restore tests work from this store. > **Caution** > > The store on the server is not disaster recovery. Backups sit on the same machine as the databases, and usually on the same disk. They undo a bad migration or a dropped table. If the server is lost, the backups are lost. The chart keys are under `objectStorage.local`. The installer overrides some of the chart defaults: | Key | Chart default | Installer value | | ---------------------- | --------------------------- | ------------------------------------------------------- | | `enabled` | `false` | `true` | | `bucket` | `orchard-backups` | `orchard-backups` | | `uploadsBucket` | `orchard-uploads` | `orchard-uploads` | | `storage.size` | `20Gi` | One fifth of free disk, from 5 GiB to 50 GiB | | `storage.storageClass` | The cluster's default class | The `local-path` class, which does not enforce the size | To install without this store, pass `--object-storage false`. Databases then have no backups until you add S3 storage. On an installer host whose values file does not set `objectStorage.local.enabled`, `orchardctl update` turns the store on, unless object storage is already configured in the values file (in the server environment, `server.envFrom`, or `r2Proxy.upstream`) or under **Instance admin**. ### Add S3 storage later When you add S3 storage, new databases back up to it. Databases you already have keep backing up to where they are now, and their existing backups stay restorable from there. To move a database, create a copy of it. For details, refer to [What happens when you change storage](/operate/storage/#what-happens-when-you-change-storage). ## Related resources - [Back up and restore an instance](/operate/backup-and-restore/) - Learn what else an instance needs backed up to survive the loss of a machine. - [`orchard db` reference](/reference/cli/#db) - Review the backup, checkpoint, and restore commands and their flags. --- # Use a connection pooler > Turn on the Orchard connection pooler for a managed Postgres database so that apps share a small set of server connections. Source: https://docs.orchard.hackclub.com/data/connection-pooler/ Each Postgres connection uses memory on the database server, so a database can serve only a limited number of them. A connection pooler accepts many client connections and shares a small set of Postgres server connections between them. Use a pooler when an app opens more connections than the database can serve. Orchard runs the pooler with PgBouncer. New databases with 1 GB of memory or less start with a pooler. A superadmin can change this default in **Instance admin** > **Configuration** > **Connection pooler for new small databases**. ## Prerequisites - Edit access to the project: the Admin or Member [project role](/teams/organizations/#project-roles). - A dedicated database. ## Turn on the pooler **Dashboard** 1. Open the database. 2. Go to **Settings** > **Connection pooler**. 3. Turn on **Pool connections**. The **Address** row shows the pooler address and its status. Wait for the status to change from **Starting** to **Running**. **CLI** ```sh orchard db pooler set --enabled on ``` To read the pooler address and status, run the following command: ```sh orchard db pooler get ``` ## Connect an app to the pooler Turning on the pooler does not change the database connection string. Apps keep connecting directly to Postgres until you change them. 1. Copy the address from the **Address** row. The address has this format: ```txt pg--pooler-rw..svc.cluster.local:5432 ``` 2. Open the app. 3. Go to **Variables**. 4. Set the connection string [variable](/run/environments/) to a value that uses the pooler address as the host. Keep the same user, password, and database name. 5. Select **Save**. The pooler address works only inside the cluster. ## Change the pooler settings **Dashboard** 1. Open the database. 2. Go to **Settings** > **Connection pooler**. 3. Update the settings. 4. Select **Save**. **CLI** ```sh orchard db pooler set --mode session --pool-size 20 --max-client-conn 1000 ``` Clients reconnect once when the pooler restarts. | Setting | CLI flag | Default | Range | Description | | -------------------------- | ------------------- | ------------- | ------------------------ | ------------------------------------------------------ | | **Mode** | `--mode` | `transaction` | `transaction`, `session` | How the pooler assigns server connections. | | **Pool size** | `--pool-size` | 10 | 1 to 100 | Server connections for each database and user. | | **Max client connections** | `--max-client-conn` | 500 | 10 to 5000 | Clients the pooler accepts before it refuses new ones. | | Not in the dashboard | `--instances` | 1 | 1 to 3 | Pooler instances. | Two modes are available: - **Transaction:** The pooler assigns a server connection for each transaction. This mode fits most apps. - **Session:** The pooler assigns a server connection for each client. Use this mode if the app uses `LISTEN` or session settings. ## Turn off the pooler 1. Open the database. 2. Go to **Settings** > **Connection pooler**. 3. Turn off **Pool connections**. Orchard deletes the pooler. Connections that use its address fail, so point all apps back to the database host first. ## Related resources - [Change Postgres parameters](/data/parameters/) - Raise `max_connections` when a pooler is not an option. - [`orchard db pooler` reference](/reference/cli/#db) - Review the pooler commands and their flags. --- # Create and manage a database > Create a managed Postgres database in an Orchard project, connect an app to it, size it, and turn on public access. Source: https://docs.orchard.hackclub.com/data/databases/ Orchard runs managed Postgres databases in your cluster, next to the apps that use them. Each database belongs to a [project](/teams/projects/) and runs as a CloudNativePG cluster. CloudNativePG is the Kubernetes operator that handles failover, storage, and backups, so you do not run Postgres by hand. ## Create a database **Dashboard** 1. Open a project. 2. Select **New app**. 3. In **Start from scratch**, select **Postgres**. 4. In **Start from**, keep **Empty**. You can also select **Import from URL** or **Copy of a database**. 5. In **Database name**, enter a name. 6. In **Postgres version**, select a version. 7. In **Storage size**, set the volume size. The default is 1 GiB. 8. In **Resources**, set the CPU, memory, and **Instances**. 9. Select **Create database**. **CLI** ```sh orchard db create --name appdb --pg-major 17 --storage 10Gi --wait ``` To seed the database from another Postgres server, add `--restore-from postgres://...`. ## Connect an app To connect an app in the same project, use [a reference](/deploy/connect-resources/). A reference follows the database through a password rotation or a restore. **Dashboard** 1. Open the app. 2. Go to **Variables**. 3. Add a variable named `DATABASE_URL`. 4. In the value field, select **Use a resource**. 5. Select the database. 6. Select **Save**. **CLI** ```sh orchard deploy bindings add --database appdb ``` ### Get a connection string 1. Open the database. 2. Select **Connect**. 3. Select **Private** to connect from apps in this project, or **Public** to connect from anywhere. 4. Select a format: **URI**, **psql**, **.env**, or **JDBC**. 5. For a private connection, select the instances: **Primary**, **Standbys**, or **Any**. The private host is a cluster-internal address, such as `pg--rw..svc.cluster.local`. Traffic to it stays inside the cluster. Apps in the same project use this address. To print the connection details from the CLI, run `orchard db connection `. To open a `psql` session, run `orchard db psql `, or use the console on the database page. The session runs in a sandboxed client pod in your namespace as the app role, and ends when you quit `psql`. ## Set CPU and memory Set CPU and memory under **Settings** > **Resources**, or with `orchard db resources set `. Changing them restarts the database. Orchard sizes `shared_buffers` and backup compression from the memory limit, and recalculates them when the memory changes. To set `shared_buffers` yourself, refer to [Change Postgres parameters](/data/parameters/#shared-buffers). > **Caution** > > Postgres reserves `shared_buffers` when it starts. If this value is close to the memory limit, connections and backups have no room in the container, and the kernel can kill Postgres. ## Manage a database | Task | Location | Refer to | | ------------------------------------ | ---------------------------------------------- | ------------------------------------------------------- | | Read logs and open a shell | **Overview** | [Logs and shell](/run/logs/#database-logs) | | Take and restore backups | **Backups** | [Back up and restore a database](/data/backups/) | | Read metrics and query performance | **Observe** | [Monitor a database](/data/monitoring/) | | Rename, stop, or delete the database | **Settings** > **General** and **Danger zone** | [Delete a database](#delete-a-database) | | Grow storage | **Settings** > **Resources** | [Grow database storage](/data/storage/) | | Change protection settings | **Settings** > **Protection** | [Protect a database](/data/protection/) | | Upgrade Postgres | **Security** | [Upgrade Postgres](/data/upgrades/) | | Add standbys | **Settings** > **High availability** | [Configure high availability](/data/high-availability/) | | Turn on the pooler | **Settings** > **Connection pooler** | [Use a connection pooler](/data/connection-pooler/) | | Add users | **Settings** > **Users** | [Add database users](/data/users/) | | Change parameters | **Settings** > **Parameters** | [Change Postgres parameters](/data/parameters/) | | Install extensions | **Settings** > **Extensions** | [Install Postgres extensions](/data/extensions/) | ## Public access By default, only apps in the project can connect. Public access assigns a port on the organization's public IP address, so you can connect from your computer or a business intelligence tool. ### Prerequisites - A layer 4 (L4) load balancer in the cluster. - A public IP address. To set one for your organization, go to **Organization settings** > **Database defaults** > **Public database IP**. Otherwise, the organization inherits the [instance default](/operate/finishing-setup/#set-a-default-public-ip). Public access is not available in Cloudflare Tunnel mode, because tunnels carry HTTP only. ### Turn on public access **Dashboard** 1. Open the database. 2. Go to **Settings** > **Public access**. 3. Turn on **Reachable from the internet**. The connection string appears when the load balancer assigns the address. If the section shows an error, refer to [Troubleshoot a public address](/deploy/networking/#troubleshoot-a-public-address). **CLI** ```sh orchard db public enable ``` > **Caution** > > Anyone with the password can connect to a public database. Use a strong password, and turn off public access when you finish. To change the password, run `orchard db rotate-password `. ## Delete a database Deleting a database moves it to **Recently deleted** on the project for 30 days. You can bring it back only if it had at least one completed backup. For the steps, refer to [Recover a deleted database](/data/backups/#recover-a-deleted-database). **Dashboard** 1. Open the database. 2. Go to **Settings** > **Danger zone**. 3. Select **Delete database**. 4. Confirm the deletion. **CLI** ```sh orchard db delete ``` > **Caution** > > Orchard cannot delete a database while an app still references it. Remove the reference first. ## Related resources - [Read replicas](/data/replicas/) - Send read-only traffic to standbys through a separate endpoint. - [Connect an app to a database or app](/deploy/connect-resources/) - Learn how references keep connection strings current. - [`orchard db` reference](/reference/cli/#db) - Review every database command and flag. --- # Install Postgres extensions > Install and remove Postgres extensions on an Orchard managed database from the dashboard or the CLI. Source: https://docs.orchard.hackclub.com/data/extensions/ Extensions add features to Postgres, such as vector search with `pgvector` or geospatial types with PostGIS. When you install one, Orchard runs `CREATE EXTENSION` against the database for you. Only extensions on an allowlist are available, because some extensions can run code or reach the network from the database pod. ## Install an extension **Dashboard** 1. Open the database. 2. Go to **Settings** > **Extensions**. 3. Find the extension. 4. Turn on its switch. An extension that loads at startup shows **Loads at startup, restarts the database**. Installing one of these restarts the database and drops open connections. **CLI** ```sh orchard db extension list orchard db extension install vector ``` For an extension that loads at startup, add `--preload`. This option restarts the database. ## Remove an extension **Dashboard** 1. Open the database. 2. Go to **Settings** > **Extensions**. 3. Turn off the extension's switch. 4. Select **Drop extension**, or **Drop and restart** for an extension that loads at startup. **CLI** ```sh orchard db extension uninstall vector ``` For an extension that loads at startup, add `--remove-preload`. This option restarts the database. > **Caution** > > Orchard runs `DROP EXTENSION ... CASCADE`, so columns, indexes, and functions that use the extension are dropped with it. When backup storage is set, Orchard tries to take a [checkpoint](/data/backups/#take-a-checkpoint) first. Restore that checkpoint to bring the dropped objects back. ## Allowed extensions Orchard allows the following extensions. It refuses others, because untrusted languages and foreign data wrappers can run code or reach the network from the database pod. | Purpose | Extensions | | ----------------- | ------------------------------------------------------------------------ | | UUIDs and hashing | `uuid-ossp`, `pgcrypto` | | Vectors | `vector`, `pgvector` | | Geospatial | `postgis`, `postgis_topology`, `postgis_raster`, `cube`, `earthdistance` | | Text search | `pg_trgm`, `unaccent`, `fuzzystrmatch`, `citext` | | Data types | `hstore`, `ltree`, `isn`, `intarray` | | Indexes | `btree_gin`, `btree_gist` | | Query statistics | `pg_stat_statements` | | Other | `tablefunc`, `plpgsql`, `timescaledb` | An extension must also exist in the Postgres image. If you need one that is missing, an operator must change the image. ## Related resources - [Monitor a database](/data/monitoring/) - Turn on `pg_stat_statements` from the **Queries** view to find slow queries. - [`orchard db extension` reference](/reference/cli/#db) - Review the extension commands and their flags. --- # Configure high availability > Add standby instances to an Orchard managed database and choose when a write counts as saved. Source: https://docs.orchard.hackclub.com/data/high-availability/ A database with one instance has no failover: if its node fails, the database is down until the instance comes back. Standby instances keep a copy of the primary, so one of them can take over when the primary fails. To configure high availability, add a standby, then choose a replication mode that sets how much data a failover can lose. ## Prerequisites - Edit access to the project: the Admin or Member [project role](/teams/organizations/#project-roles). - A dedicated database. - Available [quota](/teams/quotas/) for each new instance. ## Add a standby 1. Open the database. 2. Go to **Settings** > **Resources**. 3. In **Instances**, increase the number of instances. 4. Select **Scale to ``**. The **Instances** list shows each instance as **Primary** or **Standby**, with its status. A new standby copies the primary before it serves traffic. ## Choose a replication mode The replication mode controls when Postgres treats a write as saved. | Mode | Behavior | Needs a standby | | ------------- | -------------------------------------------------------------------------- | --------------- | | **Async** | A failover can lose the last moments of writes. | No | | **Preferred** | Each commit waits for a standby while one is healthy. | Yes | | **Required** | No acknowledged write is lost, but writes stop if no standby is reachable. | Yes | **Dashboard** 1. Open the database. 2. Go to **Settings** > **High availability**. 3. Select a mode. Orchard saves the mode immediately. **CLI** ```sh orchard db replication set --mode preferred ``` To read the current mode, run the following command: ```sh orchard db replication get ``` ## Remove a standby > **Caution** > > Removing a standby deletes the standby and its volume. 1. Open the database. 2. Go to **Settings** > **Resources**. 3. In **Instances**, decrease the number of instances. 4. Select **Scale to ``**. 5. In the confirmation dialog, select **Scale to ``**. The primary keeps running. Standbys also serve read-only traffic. To send reads to them, refer to [Read replicas](/data/replicas/). ## Related resources - [Monitor a database](/data/monitoring/) - Watch the **Replication lag** panel. - [`orchard db replication` reference](/reference/cli/#db) - Review the replication commands. --- # Monitor a database > Read metrics and query performance for an Orchard managed database on the Observe tab. Source: https://docs.orchard.hackclub.com/data/monitoring/ The **Observe** tab of a database shows metrics and query statistics, so you can find slow queries and decide whether the database needs more resources before users notice. Metrics and query statistics are available only for dedicated databases. ## View metrics **Dashboard** 1. Open the database. 2. Go to **Observe** > **Metrics**. 3. Select a time range. **CLI** ```sh orchard db metrics ``` The **Metrics** view has the following panels: | Section | Panels | | ------------------------- | -------------------------------------------------------------------------- | | **Activity** | **Connections**, **Transactions**, **Cache hit** | | **Replication & storage** | **Replication lag**, **Database size**, **Disk used** | | **Resources** | **CPU**, **Memory**, **Network in**, **Network out** | | **Health** | **Deadlocks**. This panel appears only when the range contains a deadlock. | The **Disk used** panel marks 80% full and 92% full. Writes pause at 92%, so [grow the storage](/data/storage/) before the line reaches that mark. ## Turn on query statistics Query statistics use the `pg_stat_statements` [extension](/data/extensions/). Turning on the extension restarts the database once. 1. Open the database. 2. Go to **Observe** > **Queries**. 3. Select **Enable**. ## Find slow queries 1. Open the database. 2. Go to **Observe** > **Queries**. 3. In **Rank queries by**, select one of these options: - **Most time:** Total time across all calls. - **Most frequent:** Number of calls. - **Slowest:** Mean time for each call. 4. (Optional) In **Filter queries**, enter text to search for. 5. Select a row to read the full query. To clear the collected statistics, select **Reset**. ## Read logs and restart history The **Overview** tab of a database includes a [console](/run/logs/#database-logs). In the console, **Logs** shows Postgres logs and **Killed** shows the output of containers that were killed. To read this data from the CLI, run the following commands: ```sh orchard db logs orchard db killed list ``` To print a summary of database health, run the following command: ```sh orchard db diagnose ``` ## Related resources - [Change Postgres parameters](/data/parameters/) - Tune timeouts, memory, and slow query logging. - [Read logs and open a shell](/run/logs/) - Use the database console from the dashboard. - [`orchard db` reference](/reference/cli/#db) - Review the `metrics`, `logs`, `killed`, and `diagnose` commands. --- # Change Postgres parameters > Change connection, memory, timeout, logging, and durability parameters on an Orchard managed Postgres database. Source: https://docs.orchard.hackclub.com/data/parameters/ Orchard sets Postgres defaults for you and sizes `shared_buffers` from the memory limit of the database. When a workload needs something different, such as a longer statement timeout or more connections, you can change a set of parameters yourself. Some parameters restart the database when you save them. ## Prerequisites - Edit access to the project: the Admin or Member [project role](/teams/organizations/#project-roles). - A dedicated database. ## Change a parameter **Dashboard** 1. Open the database. 2. Go to **Settings** > **Parameters**. 3. Update the values. 4. Select **Save**. If the change requires a restart, the page shows `Saving restarts the database` next to the button. **CLI** To read the current values, run the following command: ```sh orchard db settings get ``` To set a value, run the following command: ```sh orchard db settings set statement_timeout=30000 ``` To remove a value, leave it empty: ```sh orchard db settings set statement_timeout= ``` ## Available parameters | Dashboard label | Parameter | Default | Range or values | Restart | | ------------------------------------ | ------------------------------------- | --------- | ---------------------------------------------------- | ------- | | **Max connections** | `max_connections` | 100 | 10 to 500 | Yes | | **Shared buffers** | `shared_buffers` | Automatic | Memory value in `kB`, `MB`, or `GB` | Yes | | **Work memory** | `work_mem` | 4MB | Memory value in `kB`, `MB`, or `GB` | No | | **Maintenance work memory** | `maintenance_work_mem` | 64MB | Memory value in `kB`, `MB`, or `GB` | No | | **Effective cache size** | `effective_cache_size` | 4GB | Memory value in `kB`, `MB`, or `GB` | No | | **Slow query log (ms)** | `log_min_duration_statement` | -1 | -1 to 600000. -1 turns this off. | No | | **Statement timeout (ms)** | `statement_timeout` | 0 | 0 to 3600000. 0 turns this off. | No | | **Idle-in-transaction timeout (ms)** | `idle_in_transaction_session_timeout` | 0 | 0 to 3600000. 0 turns this off. | No | | **Synchronous commit** | `synchronous_commit` | on | `on`, `off`, `local`, `remote_write`, `remote_apply` | No | ## Shared buffers By default, Orchard sizes `shared_buffers` from the database's [memory limit](/data/databases/#set-cpu-and-memory). When you change the memory limit, Orchard recalculates the value. If you enter a value, Orchard uses that value exactly. If the value is large for the current memory limit, the page shows a warning. To return to automatic sizing, clear the field. ## Values changed outside Orchard If a running value differs from the saved value, the parameter row shows the running value and the text `changed outside Orchard`. ## Related resources - [Use a connection pooler](/data/connection-pooler/) - Serve more clients without raising `max_connections`. - [Monitor a database](/data/monitoring/) - Find slow queries before you change timeouts or memory settings. - [`orchard db settings` reference](/reference/cli/#db) - Review the settings commands. --- # Protect a database > Turn on deletion protection, automatic checkpoints before drops, and weekly restore tests for an Orchard managed database. Source: https://docs.orchard.hackclub.com/data/protection/ A backup you have never restored is a backup you cannot trust, and a database deleted by mistake takes its data with it. The protection settings guard against both: they block accidental deletion, take a restore point before destructive SQL, and test your backups every week. | Setting | CLI flag | What it does | Needs backup storage | | --------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | **Deletion protection** | `--deletion` | Orchard refuses to delete the database until you turn this off. | No | | **Checkpoint before drops** | `--ddl-checkpoints` | Orchard takes a [restore point](/data/backups/#take-a-checkpoint) before any `DROP TABLE`, `DROP SCHEMA`, or `DROP COLUMN` runs. | Yes | | **Weekly restore tests** | `--restore-tests` | Orchard restores the latest backup into a temporary copy each week and checks the result. | Yes | ## Prerequisites - Edit access to the project: the Admin or Member [project role](/teams/organizations/#project-roles). - A dedicated database. - For **Checkpoint before drops** and **Weekly restore tests**, [backup storage](/data/backups/#prerequisites) for the organization or the instance. ## Change the protection settings **Dashboard** 1. Open the database. 2. Go to **Settings** > **Protection**. 3. Turn each setting on or off. Orchard saves each change immediately. **CLI** Each flag accepts `on` or `off`: ```sh orchard db protect --deletion on --ddl-checkpoints on --restore-tests on ``` ## Delete a protected database If you try to delete a protected database, Orchard returns this error: ```txt has deletion protection on. Turn it off in its settings first. ``` To delete the database, turn off **Deletion protection** first. After you turn these on, you can recover from a dropped table with a checkpoint, and a failed weekly test sends a [notification](/run/notifications/). ## Related resources - [Back up and restore a database](/data/backups/) - Restore from a checkpoint, a backup, or a point in time. - [`orchard db protect` reference](/reference/cli/#db) - Review the protection flags. --- # Read replicas > Send read-only queries to the standbys of an Orchard managed database through a separate endpoint, and account for replication lag. Source: https://docs.orchard.hackclub.com/data/replicas/ A read replica is a standby Postgres instance that streams changes from the primary and serves read-only queries. Use replicas for read-heavy workloads, analytics queries that should not compete with production traffic, and reporting tools that must not write. To add a standby, refer to [Configure high availability](/data/high-availability/). ## Endpoints A database has one endpoint for each kind of traffic. Select one in the **Connect** dialog under **Primary**, **Standbys**, or **Any**. | **Connect** option | Host prefix | Serves | | ------------------ | -------------- | -------------------------------------------------- | | **Primary** | `pg--rw` | Reads and writes. The endpoint follows a failover. | | **Standbys** | `pg--ro` | Reads only, load-balanced across standbys. | | **Any** | `pg--r` | Reads only, across every instance. | Point your app's main connection at `-rw`, and read-only consumers at `-ro`. A write to `-ro` fails. ```mermaid flowchart LR APP[Your app] -->|reads + writes| RW[["pg-name-rw"]] RPT[Reporting / analytics] -->|reads only| RO[["pg-name-ro"]] RW --> P[(Primary)] RO --> S1[(Standby 1)] RO --> S2[(Standby 2)] P -.->|stream| S1 P -.->|stream| S2 ``` Writes reach only the primary. The -ro endpoint spreads reads across standbys. ## Replication lag A row written to the primary can take time to appear on a standby. A read from `-ro` after a write can return old data. Code that reads its own writes must use `-rw`. The replication mode sets whether a commit waits for a standby. The default is **Async**. For the other modes, refer to [Choose a replication mode](/data/high-availability/#choose-a-replication-mode). ## Cost Each standby is a full copy of the database, with the same storage, CPU, and memory. A primary with two standbys uses about three times the resources of a single instance. ## Related resources - [Add database users](/data/users/) - Create a read-only login for a reporting tool. - [Monitor a database](/data/monitoring/) - Watch the **Replication lag** panel. - [Troubleshooting Orchard](/operate/troubleshooting/#reads-return-old-data) - Fix reads that return old data. --- # Grow database storage > Increase the volume size of an Orchard managed database, and resolve paused writes when the volume is full. Source: https://docs.orchard.hackclub.com/data/storage/ Orchard pauses writes when a database volume is nearly full, so grow the volume before that happens. Orchard grows the volume of every instance without a restart. You cannot decrease the size later, so grow it only as far as you need. The largest volume is 200 GiB by default. An operator can change this limit under **Instance admin** > **Limits** > **Largest volume**, or with `MAX_VOLUME_SIZE`. ## Prerequisites - Edit access to the project: the Admin or Member [project role](/teams/organizations/#project-roles). - A dedicated database. ## Grow the volume **Dashboard** 1. Open the database. 2. Go to **Settings** > **Resources**. 3. In **Storage**, increase **Size**. 4. Select **Grow to ``**. 5. Select **Grow storage**. The volume of every instance grows to the new size. **CLI** ```sh orchard db storage expand --size 20Gi ``` ## Resume paused writes Orchard pauses writes when the volume reaches 92% full. Reads continue. The **Storage** card shows `Writes are paused because the volume is full`. To resume writes: 1. Grow the volume. The **Storage** card shows the minimum size. 2. Wait for the volume to drop under 85% full. Writes resume automatically. The events **Writes paused (disk full)** and **Writes resumed** are available as [notifications](/run/notifications/). ## WAL archiving failures If write-ahead log (WAL) archiving fails, WAL files continue to fill the volume. The **Storage** card shows `WAL archiving is failing`. Growing the volume adds time, but it does not fix the cause. To resolve the failure, check the [backup storage](/data/backups/#prerequisites) configuration. ## Related resources - [Monitor a database](/data/monitoring/) - Watch the **Disk used** panel to grow the volume before writes pause. - [`orchard db storage` reference](/reference/cli/#db) - Review the storage commands and their flags. --- # Upgrade Postgres > Upgrade an Orchard managed database to a newer Postgres major version, and review known vulnerabilities in the running version. Source: https://docs.orchard.hackclub.com/data/upgrades/ The Postgres project supports each major version for a fixed period, so a long-lived database eventually needs a major upgrade. Orchard runs the upgrade for you: it can rehearse on a copy first, takes a checkpoint, and puts the database back on the previous version if the upgrade fails. The database is offline during the upgrade step. Minor releases contain bug and security fixes only. To apply one, select **Update to ``** on the database's **Security** tab, or run `orchard db update `. Instances restart one at a time, standbys first. To have Orchard apply minor releases for you, an organization admin turns on **Apply minor updates automatically** under **Organization settings** > **Database defaults**. Orchard then updates a few databases each morning (UTC). An operator can turn automatic updates off for the whole instance. ## Prerequisites - Edit access to the project: the Admin or Member [project role](/teams/organizations/#project-roles). - A dedicated database that is running and healthy. - No other restore or upgrade running on the database. ## Check the running version **Dashboard** 1. Open the database. 2. Go to **Security**. The **Version and security** card shows the running version and its support date. It also lists known vulnerabilities from postgresql.org. **CLI** To read the running version and known vulnerabilities, run the following command: ```sh orchard db security ``` To list the versions that this instance offers, run the following command: ```sh orchard db versions ``` ## Upgrade to a new major version **Dashboard** 1. Open the database. 2. Go to **Security**. 3. Select **Upgrade to Postgres ``**. The button shows the newest version. 4. In **To**, select the target version. 5. Keep **Rehearse on a copy first** turned on. This adds a few minutes before the upgrade. 6. Select **Upgrade to Postgres ``**. To follow the upgrade, go to the **Backups** tab. **CLI** ```sh orchard db upgrade --to 18 --wait ``` To skip the rehearsal, add `--no-rehearse`. To change how long `--wait` blocks, use `--timeout`. The default is 10 minutes. ## How an upgrade runs 1. If rehearsal is on, Orchard upgrades a copy of the database to check that the upgrade works. 2. Orchard takes a [checkpoint](/data/backups/). 3. Orchard upgrades the database. The database is offline during this step. 4. Orchard runs `ANALYZE`. 5. If backup storage is set, Orchard starts a new backup. If the upgrade fails, Orchard returns the database to the previous version. If a previous rehearsal measured the upgrade time, the upgrade dialog shows that time as the expected offline period. ## Respond to a support warning **Version and security** shows a warning when support for the running major version ends soon, and an error after support ends. After that date, the major version receives no more security fixes. To resolve the warning or the error, upgrade to a newer major version. ## Related resources - [Back up and restore a database](/data/backups/) - Restore to a checkpoint if you need to undo an upgrade later. - [`orchard db upgrade` reference](/reference/cli/#db) - Review the upgrade flags, including `--no-rehearse` and `--timeout`. --- # Add database users > Create read-only or read-write Postgres users on an Orchard managed database for reporting tools and other clients. Source: https://docs.orchard.hackclub.com/data/users/ Apps in the project connect as the owner user, which owns the database and can change anything in it. To give a tool or a person a login with less access, add a database user. For example, create a read-only user for a reporting tool, so that it cannot change data even if its credentials leak. You cannot remove the owner user. ## Prerequisites - Edit access to the project: the Admin or Member [project role](/teams/organizations/#project-roles). - A dedicated database. ## Add a user **Dashboard** 1. Open the database. 2. Go to **Settings** > **Users**. 3. Select **Add user**. 4. In **Name**, enter a name for the user. 5. In **Access**, select **Read only** or **Read and write**. 6. Select **Add user**. 7. Copy the **Password** and **Connection string**. 8. Select **Done**. **CLI** ```sh orchard db user create reporting --access read ``` The command prints the password once. The `--access` flag accepts `read` or `write`. The default is `read`. This command needs [a token with the deploy scope](/account/tokens/#token-access-levels). > **Caution** > > Orchard shows the password one time. If you lose the password, remove the user and add it again. ## Usernames A username must follow these rules: - It has 2 to 41 characters. - It starts with a lowercase letter. - It contains only lowercase letters, digits, and underscores. - It does not start with `pg_` or `cnpg_`. - It is not the owner user or another reserved name. ## List users **Dashboard** 1. Open the database. 2. Go to **Settings** > **Users**. **CLI** ```sh orchard db user list ``` ## Remove a user Removing a user disconnects all sessions that use the login, and the login stops working. **Dashboard** 1. Open the database. 2. Go to **Settings** > **Users**. 3. On the user, select the delete icon. 4. Select **Remove user**. **CLI** ```sh orchard db user rm ``` ## Related resources - [Read replicas](/data/replicas/) - Point a read-only user at a standby to keep reporting off the primary. - [`orchard db user` reference](/reference/cli/#db) - Review the user commands and their flags. --- # Builds > Orchard builds images in Kubernetes jobs on your cluster with BuildKit. Learn how build steps, caching, and the queue work, and fix common build failures. Source: https://docs.orchard.hackclub.com/deploy/builds/ Orchard builds images on your own cluster, so your source code and build secrets stay on machines you control. Each build runs as a Kubernetes job that clones the repository, builds the image with BuildKit, and pushes it to the [registry configured on the instance](/operate/finishing-setup/#use-your-own-registry). This page explains how builds move through the queue and how to fix the most common failures. Orchard reads build status from the job. If a builder stops unexpectedly, the build shows as failed. ## Build steps The build progress page shows these steps, with the logs for each one. | Step | What happens | | ------------------------ | ------------------------------------------------------------------ | | **Starting the builder** | The build waits for a slot and a node, and the builder pod starts. | | **Cloning the repo** | The builder clones the repository. | | **Building the image** | BuildKit builds the image. | | **Pushing the image** | The builder pushes the image to the registry. | | **Rolling out** | Kubernetes starts the new pods. | To cancel a running build, select **Cancel deployment** on the progress page. ## Caching Builders share a BuildKit cache, so a later build of the same repository reuses layers. The installer sizes the cache from free disk. On a Helm install, set the size with `builders.localCache.size`. ## Concurrency and the queue `MAX_CONCURRENT_BUILDS` limits how many builds run at once. The installer sets it from the machine's memory. For the values, refer to [Sizing](/start/install/#sizing). One organization can run at most half of a pool's slots at once, so a single organization cannot keep everyone else waiting. A pool with 4 slots or fewer is not split. Set `MAX_CONCURRENT_BUILDS_PER_ORG` to change the limit, or to `0` for no limit. When builds are waiting, Orchard starts the one from the organization with the fewest running builds first, and takes the oldest request when organizations are level. When all slots are busy, Orchard queues the build and starts it when a slot opens. The API reports this in the rebuild response: ```json { "build": { "accepted": true, "started": false, "status": "queued", "running": 2, "slots": 2, "waiting": 1, "message": "All 2 build slots are busy on this instance. ..." } } ``` The rest of that response still describes the previous build. > **Caution** > > Do not retry a queued build. A new request replaces the queued one and moves it to the back of the queue. A retry loop can keep an app waiting indefinitely. ## Troubleshoot a failed build A failed build leaves the previous version running. To read the logs, open the app and select **Build logs** in **Activity**, or run `orchard logs --build`. ### The image has no application in it **Cause:** The build used a stage that does not contain the application. **Fix:** Go to **Settings** > **Source & build**. In **Build stage**, select the stage that contains your app. ### A build step fails because a key is missing **Cause:** A stage needs a value at build time, such as an API key for a code generation step. **Fix:** Add the value as a variable on the app. Orchard passes app variables to the build as [build arguments](/deploy/github/#build-arguments). ### Error: 401 Unauthorized when pulling a base image **Cause:** The registry rejects anonymous pulls. `dhi.io` is one example. **Fix:** Add these keys to the app as [secret variables](/run/environments/#secrets): - `DHI_USERNAME` and `DHI_TOKEN` for Docker Hardened Images (`dhi.io`). - `DOCKER_AUTH_CONFIG` for other registries. The value is a Docker config JSON whose `auths` map lists each registry. Orchard uses these keys only for `FROM` and `COPY --from` pulls. It does not pass them as build arguments, and it does not add them to the running container. ### The build fails with I/O errors in a layer **Cause:** The builder ran out of disk or the cache is full. **Fix:** Increase the cache size. On an installer host, run `sudo orchardctl config set builders.localCache.size G --apply`. ### The build fails quickly with a push error **Cause:** The BuildKit daemon stopped. A fast failure here is usually not a registry rate limit. **Fix:** Read the logs of the BuildKit container, not the pusher container. ### Could not schedule build pod: Insufficient memory **Cause:** Memory requests on the node leave no room for the builder pod. Kubernetes counts requests, not actual usage. **Fix:** Remove or shrink other workloads. On a cluster installed with the Helm chart, you can also [add a node](/operate/nodes/). ### The build also fails on your machine **Cause:** The Dockerfile has a problem of its own. Orchard runs your Dockerfile as written. It does not change your base image or your build steps. **Fix:** Reproduce the build with `docker build` and fix it in the repository. ## Related resources - [Roll back an app](/deploy/rollbacks/) - Return an app to an earlier release when a new build misbehaves. - [Troubleshooting Orchard](/operate/troubleshooting/) - Diagnose problems with the instance itself. - [Deploy from an image](/deploy/image/) - Run a prebuilt image and skip the build. --- # Connect an app to a database or app > Read the connection details of a database or another Orchard app through a variable that stays current. Source: https://docs.orchard.hackclub.com/deploy/connect-resources/ Connect an app to a database or to another app in the same project, and the app reads the connection details from a [variable](/run/environments/). Orchard stores a reference instead of a copied value, so the variable stays correct after a password rotation or a restore, and you never paste a password by hand. A reference has this format: ```txt ${{resource..}} ``` ## Prerequisites - Edit access to the project. - A database or app in the same project. ## Connect a resource **Dashboard** 1. Open the app. 2. Go to **Variables**. 3. Select **Use a resource**. 4. Select a database or app. 5. Select **Save**. For a database, Orchard adds the variable `DATABASE_URL` if the name is free. For an app, Orchard adds a variable named `_URL`. To read a different field, select the reference in the variable row, then select the field. To replace the reference with text, select **Type a value instead**. **CLI** To connect a database and add `DATABASE_URL`, run the following command: ```sh orchard deploy bindings add --database ``` To connect an app, run the following command: ```sh orchard deploy bindings add --app ``` | Flag | Description | | ---------- | ------------------------------------------------------------------------------------ | | `--as` | The connection name used in the reference. The default comes from the resource name. | | `--env` | The variable to add. | | `--no-env` | Connect the resource without adding a variable. | To list the resources that you can connect, run the following command: ```sh orchard deploy bindings options ``` ## Available fields | Resource | Field | Value | | -------- | ------------------- | ------------------------------------------------------------------ | | Database | `connection_string` | The full Postgres connection string. This value is secret. | | Database | `host` | The database host. | | Database | `port` | The database port. | | Database | `database` | The database name. | | Database | `user` | The database user. | | Database | `password` | The database password. This value is secret. | | App | `url` | The internal URL of the app, in the format `http://:`. | | App | `host` | The internal hostname of the app. | | App | `port` | The port of the app's first service. | App fields come from the app's first service. An app with no service has no fields. ## Limits - An app can connect to 20 resources. - A connection name starts with a lowercase letter. It contains only lowercase letters, digits, and underscores. It has 32 characters at most. ## Remove a connection **Dashboard** 1. Open the app. 2. Go to **Variables**. 3. Remove all variables that use the connection. 4. Select **Save**. Orchard removes a connection when no variable uses it. **CLI** Remove all variables that use the connection, then run the following command: ```sh orchard deploy bindings remove ``` You cannot delete a database while an app is connected to it. ## Unresolved references If a variable refers to a connection or field that does not exist, the app does not start. Orchard does not pass an empty value to the app. ## Related resources - [Create and manage a database](/data/databases/) - Create the Postgres database an app connects to. - [score.yaml](/deploy/score/) - Declare database connections in a file in the repository. - [`orchard deploy bindings` reference](/reference/cli/#deploy) - Every flag of the `orchard deploy bindings` commands. --- # Deploy from your terminal > Deploy a local directory with orchard up, or import a GitHub repository with orchard import. Source: https://docs.orchard.hackclub.com/deploy/deploy-from-terminal/ The Orchard CLI can create and deploy an app without opening the dashboard. Use `orchard up` to deploy a local directory, which needs no Git repository, and run it again to ship each change. Use `orchard import` to turn a GitHub repository into a project and a running app with one command. ## Deploy a local directory The `orchard up` command packs a directory, uploads it, and builds it on the cluster. The first run creates the app in the linked project. Later runs deploy the new code to the same app. ### Prerequisites - The [Orchard CLI](/cli/), installed and signed in. - A project linked to the directory. To link one, run `orchard link --project `. - S3 storage on the instance, as described in [Turn on local deploys](#turn-on-local-deploys). ### Run the deploy ```sh orchard up ``` If the directory has a Dockerfile, Orchard builds it. If the directory has no Dockerfile, Railpack detects the language. To use Railpack when a Dockerfile exists, add `--railpack`. The CLI always excludes `.git`, `.orchard`, and `.env.orchard`. It also leaves out files that look like secrets, such as `.env`, `.env.*`, `.npmrc`, `.aws`, `.ssh`, and `*.pem`, and prints what it skipped. To upload one, add a line such as `!.env.build` to `.dockerignore`. The CLI also uses `.dockerignore` if the file exists. Otherwise, it uses `.gitignore`. The compressed directory cannot be larger than 100 MB. If you exceed the limit, the CLI returns this error: ```txt build context exceeds 100MB; add a .dockerignore to exclude build artifacts ``` ### Common options | Flag | Description | | -------------- | -------------------------------------------------------------------------------------------------------------- | | `--name` | The app name. The default is the directory name. | | `--root` | The directory of the app inside a monorepo. | | `--port` | The port the app listens on. The default is the `EXPOSE` value, then the port the base image exposes, or 3000. | | `--dockerfile` | The path to the Dockerfile, relative to the directory. | | `--output-dir` | A directory of built static files. The app serves them as a static site. | | `--detach` | Start the build without following its logs. | | `--wait` | Block until the deploy is live. This is the default. To return when the build finishes, use `--wait=false`. | The command exits with code 9 if the build fails and code 10 if the pods crash. It also warns you if the app is live and nothing listens on its port. For all flags, refer to the [`orchard up` reference](/reference/cli/#up). ### Turn on local deploys Local deploys need S3 storage, because Orchard stores each uploaded directory in a bucket that build pods can reach. The store on the server holds database backups, so builds do not use it. To turn on local deploys, a superadmin [adds S3 storage](/operate/storage/). Local deploys then turn on with no other setting. If the instance has no S3 storage, the CLI returns this error: ```txt Local deploys need S3 storage. Add it under Instance admin, or run: sudo orchardctl backups s3 set ``` To deploy without S3 storage, [import a GitHub repository](#import-a-github-repository). If you set storage with `R2_*` environment variables, also set `LOCAL_DEPLOYS_ENABLED=true` and `R2_BUILD_CONTEXT_BUCKET`. To turn local deploys off, set `LOCAL_DEPLOYS_ENABLED=false`. ## Import a GitHub repository The `orchard import` command creates a project named after the repository. It detects how to build the repository and starts the first build. It also attaches a [protected generated URL](/deploy/protection/). [Auto-deploy](/deploy/github/#auto-deploy) is on when the GitHub App covers the repository. ### Prerequisites - The [Orchard CLI](/cli/), installed and signed in. - For a private repository, a [GitHub account linked to Orchard](/deploy/github/). A public repository needs neither a linked account nor the GitHub App. ### Run the import ```sh orchard import owner/repo --wait ``` To select a branch, use `owner/repo#branch`. You can also pass a repository URL. | Flag | Description | | -------- | ------------------------------------------------------------- | | `--name` | The project and app name. The default is the repository name. | | `--port` | The port. This overrides the detected port. | | `--wait` | Block until the operation finishes. | ## Related resources - [Deploy from GitHub](/deploy/github/) - Create an app from the dashboard and deploy on each push. - [Builds](/deploy/builds/) - Learn how Orchard builds images and how to fix common build errors. --- # Manage domains and HTTPS > Use the generated HTTPS URL for an Orchard app, add a custom domain, configure DNS, and redirect a domain. Source: https://docs.orchard.hackclub.com/deploy/domains/ Every app with a web port can get an HTTPS URL on the instance's app domain as soon as it deploys, with no DNS work. When you are ready to serve it on your own name, add a custom domain, and Orchard issues and renews its certificate for you. You manage generated URLs, custom domains, and redirects on the app's **Network** tab. ## Generated URLs When you create an app and set a port's reach to **Private link** or **Public link**, Orchard generates a URL on the app domain. **Private link** requires people to sign in. **Public link** is open to anyone. The [reach](/deploy/networking/#reach) options **Public port** and **Internal** do not generate a URL. ## Add a custom domain ### Prerequisites - An app with a TCP port. - Access to the DNS settings of the domain. - A CNAME target. [A superadmin sets it](/operate/finishing-setup/#set-the-custom-domains-target) under **Instance admin** > **Configuration** > **Custom domains**. ### Steps **Dashboard** 1. Open the app. 2. Go to **Network**. 3. In **Domains**, select **Add domain**. 4. Enter the domain, such as `app.example.com`. 5. Keep **Point to this app** selected. 6. If the app has more than one port, select the **Port**. 7. Select **Add domain**. 8. In the **Set up DNS** dialog, add the record it shows at your DNS provider. 9. Wait for the status to change from **Waiting for DNS** to **Connected**. 10. Select **Done**. To open this dialog later, open the domain's menu and select **DNS setup…**. **CLI** 1. Add the domain: ```sh orchard domain create --deployment --host app.example.com --service-port 3000 ``` 2. Add the DNS record at your DNS provider. 3. Check the record: ```sh orchard domain validate-dns app.example.com ``` After the record resolves, cert-manager issues a certificate and renews it. The domain's status shows **Securing** while the certificate is in progress. ## Prove you own a domain An instance can require proof of ownership before anyone adds a custom domain. This setting is off by default. When it is on, add one more record at your DNS provider. The DNS setup shows the exact name and value: | Type | Name | Value | | ----- | ------------------------------------ | ------------------- | | `TXT` | `_orchard-challenge.app.example.com` | Shown in the dialog | The value is different for each project and domain. Until Orchard finds the record, adding the domain fails with the error `domain_proof_required`, and the message gives the record to add. You can remove the record after the domain is added. You do not need the record in these cases: - The domain is under a generated URL on this instance. - The project already uses the domain. - Your organization already [verified the domain](/teams/sso/#verify-an-email-domain), or a parent of it. ## Redirect a domain A redirect sends visitors from a domain to another address. It keeps the path and query string. **Dashboard** 1. Go to **Network** > **Domains**. 2. Select **Add domain**. 3. Enter the domain. 4. Select **Redirect**. 5. In **Redirect to**, enter the destination. 6. In **Status**, select **307 Temporary**, **302 Found**, **308 Permanent**, or **301 Moved Permanently**. 7. Select **Add domain**. To change a redirect, open its menu and select **Edit redirect…**. If you change the domain, Orchard provisions the new domain before it removes the old one. **CLI** You can edit an existing redirect from the CLI: ```sh orchard domain update --redirect-to www.example.com --redirect-status 308 orchard domain update --host new.example.com ``` ## Certificates | Setup | Certificates | | ------------------------------- | ------------------------------------------------------------- | | Installer, `public` mode | One certificate for each hostname, over HTTP-01 | | Installer, `lan` mode | Self-signed certificates | | Installer, `tunnel` mode | Cloudflare terminates TLS. Orchard does not use cert-manager. | | Helm chart with a DNS-01 issuer | A [wildcard certificate](/operate/wildcard-certificates/). | ## Related resources - [Protect an app](/deploy/protection/) - Require a sign-in or a password before a domain opens. - [Reach apps over Tailscale](/deploy/tailscale/) - Give an app a private address instead of a public domain. - [A certificate never issues](/operate/troubleshooting/#a-certificate-never-issues) - Find out why a domain stays on **Securing**. - [`orchard domain` reference](/reference/cli/#domain) - Every flag of the `orchard domain` commands. --- # Deploy from GitLab, Gitea, and others > Link GitLab, Gitea, Forgejo, Codeberg, Bitbucket Cloud, or another Git host to your Orchard account, then deploy an app from it with auto-deploy on push. Source: https://docs.orchard.hackclub.com/deploy/git-providers/ Orchard can build apps from repositories outside the [GitHub App](/deploy/github/). Link a Git provider to your account, and you can pick its repositories in the new app form and turn on auto-deploy on push, the same way you do for GitHub. Orchard supports GitLab, Gitea, Forgejo, Codeberg, Bitbucket Cloud, GitHub with a token, and any Git host that serves HTTPS. A provider belongs to you. Orchard lists only the repositories your token can see, and builds clone with your token. ## Link a provider To link a provider, sign in with OAuth or add a token. OAuth is available for GitLab and Bitbucket when a superadmin registers an OAuth app under **Instance admin** > **Configuration**. Orchard refreshes OAuth tokens for you. **Dashboard** 1. Go to **Account settings** > **Connections**. 2. In **Git providers**, take one of these steps: - If your instance has OAuth configured, select **Add provider**, then **Sign in with GitLab** or **Sign in with Bitbucket**. - Otherwise, select **Add with a token**. 3. If you add a token, enter the **Provider**, **Name**, **Host**, and **Token**. For **Bitbucket Cloud**, also enter the **Atlassian account email** that owns the API token. For **Any git host**, also enter the **Username** if the host expects one. 4. Select **Connect**. **CLI** ```sh orchard git add --provider gitlab --name work --token glpat-... ``` The `--provider` flag accepts `github`, `gitlab`, `gitea`, `bitbucket`, or `generic`. For a self-hosted provider, add `--url`. For `bitbucket` with an API token, add `--username` with your Atlassian account email. For `generic`, add `--username` if the host expects one. ```sh orchard git add --provider bitbucket --name bitbucket --username you@example.com --token ATATT... ``` Orchard stores the token encrypted. Before it saves, it lists your repositories with the token, so a wrong token fails here instead of at the first build. Orchard cannot check a token for **Any git host**, because a plain Git host has no API. A wrong token for that host fails when the first build clones. | Provider | Token | Scopes | | ------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------- | | GitLab | Personal or project access token | `read_api`, `read_repository` | | Gitea, Forgejo, Codeberg | Access token | Repository read | | Bitbucket Cloud | Atlassian API token, or access token | `read:repository:bitbucket`, plus `read:webhook:bitbucket` and `write:webhook:bitbucket` for auto-deploy | | GitHub with a token | Fine-grained token | Contents read | | Any Git host | The password used to clone over HTTPS | None | ### Bitbucket Cloud You can link Bitbucket Cloud with **Sign in with Bitbucket** or with an Atlassian API token. **Sign in with Bitbucket** uses OAuth. A superadmin turns it on in **Instance admin** > **Configuration** > **Bitbucket sign-in**, with the key and secret of a Bitbucket OAuth consumer that has repository read access and the callback URL `/apiv1/git/oauth/bitbucket/callback`, where `` is the address of your Orchard dashboard. To link Bitbucket Cloud with an API token: 1. Go to [API tokens](https://id.atlassian.com/manage-profile/security/api-tokens) in your Atlassian account settings. 2. Select **Create API token with scopes**, enter a name and an expiry date, and select **Bitbucket** as the app. 3. Select the `read:repository:bitbucket` scope. For auto-deploy, also select `read:webhook:bitbucket` and `write:webhook:bitbucket`. 4. Copy the token. 5. In Orchard, select **Add with a token**, then select **Bitbucket Cloud** as the **Provider**. 6. In **Atlassian account email**, enter the email of the Atlassian account that created the token, not your Bitbucket username. 7. In **API token**, paste the token, then select **Connect**. Orchard sends the email and the API token to the Bitbucket API, and clones with the token under the username `x-bitbucket-api-token-auth`. For details, refer to [Using API tokens](https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/) and [API token permissions](https://support.atlassian.com/bitbucket-cloud/docs/api-token-permissions/) in the Atlassian documentation. To use a workspace, project, or repository access token instead, leave **Atlassian account email** empty. Orchard sends the access token to the Bitbucket API as a bearer token and clones with the username `x-token-auth`. An access token reaches only the repositories it was created for. For details, refer to [Access tokens](https://support.atlassian.com/bitbucket-cloud/docs/using-access-tokens/) in the Atlassian documentation. #### Replace a Bitbucket app password Bitbucket Cloud does not accept app passwords. A provider that you linked with an app password shows **app password, reconnect with an API token** in **Git providers**, and listing its repositories fails with an error that asks you to reconnect. To keep the apps that build from the provider, replace its app password with an API token through the Orchard API: 1. Find the ID of the provider with `orchard git list`. 2. Create an Atlassian API token as described in the previous steps. 3. Send the token and your Atlassian account email to the provider, with an [Orchard API token](/account/tokens/) that has **Deploy** access: ```bash curl --request PATCH "https://orchard.example.com/apiv1/users/me/git-connections/" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{"username": "you@example.com", "token": ""}' ``` Orchard checks the new token against the Bitbucket API before it saves it. To start over instead, link Bitbucket Cloud again with an API token or with **Sign in with Bitbucket**, and create the apps again from the new provider. ## Create an app **Dashboard** 1. Open a project. 2. Select **New app**. 3. In **Start from scratch**, select **GitHub repo**. 4. In **Source**, select **Git**. 5. In **Repository**, select the provider. 6. Select a repository or enter its URL. 7. In **Branch**, select a branch. 8. Complete the rest of the form. 9. Select **Deploy**. Orchard detects Dockerfiles, frameworks, ports, and a [`score.yaml`](/deploy/score/) file the same way it does for GitHub. **CLI** ```sh orchard deploy create --git work --repo https://gitlab.com/group/app#main --name web ``` ## Turn on auto-deploy Auto-deploy builds the app on each push to a branch. When you turn it on, Orchard registers a push webhook on the repository through the provider's API, signed with a secret that belongs to that provider. A push then builds the app and applies its [watch paths](/deploy/github/#limit-builds-to-certain-paths). 1. Open the app. 2. Go to **Settings** > **Deploy behavior**. 3. In **Auto-deploy**, enter the branch. 4. Turn on **Deploy on push**. **Webhook** shows **Registered on ``** when the webhook is in place. If Orchard cannot register the webhook, the page shows the webhook URL and secret instead. This happens on a plain Git host, which has no API for Orchard to call, and when the token cannot manage webhooks on the repository. Paste the URL and secret into the webhook settings of the repository, for push events. A plain Git host must send a push payload in the GitHub, GitLab, or Bitbucket format. To print the same values from the CLI, run `orchard git webhook `. ## Permissions Only the person who linked a provider can: - List its repositories and branches. - Run detection on it. - Create an app from it. - Change which repository an app builds from. The new repository must be on the same host. After an app exists, [project membership](/teams/projects/#add-a-member) controls access. Project members can rebuild the app, read its logs, and turn auto-deploy on or off. Builds clone with the token of the person who linked the provider. ## Replace a provider when someone leaves An app keeps the provider it was created from, and builds clone with that provider's token. If the token expires or is revoked, or the account of the person who linked it is deleted, builds from that provider fail with an error. Orchard does not let you remove a provider that is still the source of an app. To restore builds, another member creates the app again from their own provider. ## Related resources - [Builds](/deploy/builds/) - Learn how Orchard builds images, where builds run, and how to fix common build errors. - [`orchard git` reference](/reference/cli/#git) - Every flag of the `orchard git` commands. - [Deploy from your terminal](/deploy/deploy-from-terminal/) - Build and deploy a local folder without a Git repository. --- # Deploy from GitHub > Deploy an app from a GitHub repository in Orchard and turn on auto-deploy so that each push builds and rolls out a new version. Source: https://docs.orchard.hackclub.com/deploy/github/ Connect a GitHub repository and Orchard builds it into a running app, using the repository's Dockerfile or the framework it detects. Turn on auto-deploy so that each push to a branch builds and rolls out a new version, and add watch paths so that pushes which do not touch the app skip the build. ## Prerequisites - A GitHub App on the instance. A superadmin creates it during setup, or by following [Connect a GitHub App](/operate/finishing-setup/#connect-a-github-app). - A GitHub account linked to Orchard. Go to **Account settings** > **Connections**, and in **GitHub**, select **Connect**. - The GitHub App installed on the account that owns the repository. Go to **Account settings** > **Connections**, and in **Repository access**, select **Add account**. You can deploy a public repository without these items. In the repository search field, paste `owner/repo`. Auto-deploy still needs the GitHub App and write access to the repository. If the repository later becomes private, builds stop until someone with access to it links it again. Orchard lists only the repositories your own GitHub account granted to the GitHub App. Two people in the same project can see different lists. ## Create the app **Dashboard** 1. Open a project. 2. Select **New app**. 3. In **Start from scratch**, select **GitHub repo**. 4. In **Repository**, select the repository. 5. In **Branch**, select the branch. 6. In **Name**, enter a name for the app. 7. In **Build with**, confirm the build method. Orchard selects **Dockerfile** if the repository has one. Otherwise, it selects the framework it detects. 8. (Optional) Expand **Build and output settings** to change the Dockerfile path or build stage. 9. Under **Environment variables**, review the variables that Orchard detected. 10. Under **Networking**, confirm the port. 11. Select a reach. For the options, refer to [Reach](/deploy/networking/#reach). 12. Select **Deploy**. Orchard opens the build progress page. **CLI** ```sh orchard deploy create --github owner/repo#main --name web --port 3000 --wait ``` For the build flags, refer to the [CLI reference](/reference/cli/). ## Detected settings Orchard reads the repository and fills in the form. | Field | Detected from | | ------------------------- | ---------------------------------------------------------------- | | **Build with** | A `Dockerfile`, or framework detection when no Dockerfile exists | | **Dockerfile** | The file Orchard found | | **Stage** | The stages in the Dockerfile. The default is **Final stage**. | | **Port** | `EXPOSE`, or the default port of the framework | | **Environment variables** | `ENV` lines in the image | In a monorepo, turn on **Build from the repository root** if the Dockerfile copies files from outside its own directory. If the repository contains a [`score.yaml`](/deploy/score/) file, the form shows a summary of what the file provisions. ## Auto-deploy Auto-deploy builds and rolls out the app when you push to the selected branch. ### Turn on auto-deploy **Dashboard** 1. Open the app. 2. Go to **Settings** > **Deploy behavior**. 3. In **Auto-deploy**, enter the branch in **Branch**. 4. Turn on **Deploy on push**. If the GitHub App is not installed on the repository, the page shows **Install GitHub App** instead of the switch. Select it and add the repository. **CLI** ```sh orchard deploy auto-deploy enable --branch main ``` ### Limit builds to certain paths Watch paths limit which pushes start a build. With an empty list, every push builds. ```text apps/api/** packages/shared/** package.json !**/*.md ``` - Enter one glob per line. Orchard matches each glob against every file the push changed. - `**` crosses directories. `*` stays inside one segment. `{a,b}` matches either value. - A bare directory, such as `apps/api`, covers everything under it. - A line that starts with `!` excludes matches. An exclude takes priority over an include. - A list of only excludes watches everything else. If Orchard cannot tell what a push changed, it builds. **Dashboard** 1. Go to **Settings** > **Deploy behavior**. 2. In **Watch paths**, enter the globs. 3. Select **Save**. **CLI** ```sh orchard deploy auto-deploy enable --branch main --path 'apps/api/**' --path '!**/*.md' ``` To clear the list, pass `--path ""`. ### Troubleshoot auto-deploy **Symptom:** Auto-deploy is on, but pushes do not build. **Cause:** The GitHub App cannot see the repository, or the app is not bound to the GitHub App installation. A GitHub App installed with **Only select repositories** does not include repositories created after the install. **Fix:** Add the repository in the GitHub App settings on GitHub. Then open **Settings** > **Deploy behavior**. If the page shows **Auto-deploy is on but not connected**, select **Reconnect**. **Verify:** ```sh orchard deploy auto-deploy status ``` `enabled` is the setting you chose. `deliverable` shows whether a push can reach the app. When `deliverable` is false, the output gives the reason. ## Private submodules Orchard clones submodules when it builds. A private submodule works when all of the following are true: - It is in the same GitHub account or organization as the app's repository. - The [GitHub App](#prerequisites) can see it. - The person who linked the repository to the app can see it on GitHub, with their GitHub account connected to Orchard. Otherwise, the build stops at the clone step with an authentication error. To fix this, give that person access to the submodule, or have someone with access link the repository again. Anyone who can push to the repository can add a submodule. It can read any repository that the person who linked it can see, so limit who can push to repositories that deploy on Orchard. ## Build arguments Orchard passes the app's [variables](/run/environments/) to the build as Dockerfile build arguments. - Orchard adds the `ARG` declarations above your own `ENV` lines. An `ENV` line in the repository takes priority over a build argument of the same name. - The arguments also reach stages that build `FROM` the stage where they are declared. `DHI_USERNAME`, `DHI_TOKEN`, and `DOCKER_AUTH_CONFIG` are not build arguments. They [authenticate base image pulls](/deploy/builds/#error-401-unauthorized-when-pulling-a-base-image). ## Trigger a deploy from outside GitHub To start a deploy from a CI pipeline or another system, use a [webhook token](/run/webhooks/). ## Related resources - [Builds](/deploy/builds/) - Learn how Orchard builds images, where builds run, and how to fix common build errors. - [Deploy from GitLab, Gitea, and others](/deploy/git-providers/) - Deploy from a Git host other than GitHub. - [Roll back an app](/deploy/rollbacks/) - Return an app to an earlier release. - [Deploy from your terminal](/deploy/deploy-from-terminal/) - Build and deploy a local folder without a Git repository. - [`orchard github` reference](/reference/cli/#github) - Every flag of the `orchard github` commands. --- # Deploy from an image > Run a container image in Orchard with no build step, add private registry credentials, and update the image on an existing app. Source: https://docs.orchard.hackclub.com/deploy/image/ Deploy from an image when something else already builds it, such as your CI pipeline or a vendor that publishes one. Orchard skips the build and pulls the image directly, so the app starts as fast as the registry can serve it. Private registries work too, with a credential stored once per project or organization. ## Create the app **Dashboard** 1. Open a project. 2. Select **New app**. 3. In **Start from scratch**, select **Docker image**. 4. In **Image**, enter the image reference, such as `ghcr.io/org/app:latest`. 5. In **Name**, enter a name for the app. 6. Under **Networking**, confirm the port. 7. Select a [reach](/deploy/networking/#reach). 8. Select **Deploy**. When the image exposes a port, Orchard sets the first port for you and shows the value below **Image**. If the image exposes no port, the form uses port 80. Set the port your process listens on. **CLI** ```sh orchard deploy create --image nginx:alpine --name web --port 80 --wait ``` Without `--port`, Orchard uses the port the image exposes, or port 80. An app with no port does not get a URL. To run a worker or a queue consumer with no URL, set the reach to **Internal**. ## Add private registry credentials To pull a private image, add a credential for its registry. Orchard stores one credential per registry for each project. It checks the credential against the registry when you save it. **Dashboard** 1. Open the project. 2. Go to **Settings**. 3. In **Registry credentials**, select **Add**. 4. Select the **Registry**. 5. Enter the **Username** and the token. 6. Save the credential. **CLI** ```sh orchard project registry set ghcr.io --username octocat --password-stdin < token.txt orchard project registry list ``` Orchard attaches the credential to every app and job in the project whose image is on that registry. Those pods restart to pick it up. `ghcr.io/org/app` uses the `ghcr.io` credential. `user/app` and `docker.io/user/app` use the Docker Hub credential. You can also add [credentials for a whole organization](/teams/organizations/#add-registry-credentials) under **Organization settings** > **Registry credentials**. Every project uses them unless it sets its own. | Registry | Username | Token | | --------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------- | | `ghcr.io` | Your GitHub username | A classic personal access token with `read:packages` | | `docker.io` | Your Docker Hub username | A Docker Hub access token | | `registry.gitlab.com` | A deploy token user (`gitlab+deploy-token-…`) or your username | The deploy token, or a personal access token with `read_registry` | | `quay.io` | A robot account name | The robot account token | | Other registries | The username its basic or bearer authentication expects | The matching password or token | For `ghcr.io`, use a classic token. GitHub fine-grained tokens cannot read packages. If an organization owns the package, also authorize the token for SSO in that organization. > **Caution** > > Removing a credential restarts the apps that used it. If their images are private, the new pods do not start. ## Update the image **Dashboard** 1. Open the app. 2. Go to **Settings** > **Source & build**. 3. In **Image**, enter the new reference. 4. Select **Save**. **CLI** ```sh orchard deploy image set ghcr.io/org/app:v2 --wait ``` To update the image from CI, you can also use a [webhook token](/run/webhooks/). Orchard rolls the app onto the new image. [Health checks](/deploy/scaling/#set-health-checks) and [rollback history](/deploy/rollbacks/) apply as they do for any deploy. ## Set the pull policy Orchard does not watch your registry. If you push a new image to the same tag, nothing changes until the app restarts. The pull policy decides whether the restart fetches the new image. | Pull policy | Behavior | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Automatic** | The default. A tag that can move, such as `latest`, `main`, or a major version like `17`, uses `Always`. A pinned tag or a digest uses `IfNotPresent`. | | **Use cached** | Starts reuse the copy already on the node. | | **Always pull** | Every start fetches the image again. The new app form calls this option **Always re-pull**. | To change the policy on an existing app, go to **Settings** > **Source & build** > **Pulling**, or run `orchard deploy pull-policy set --policy always`. The flag accepts `auto`, `always`, or `ifnotpresent`. > **Caution** > > If you select **Use cached** on a tag that can move, a restart does not pick up a new push. Where you control the build, tag images by commit or version. Rollbacks then point at a fixed image. Apps built from a repository get a unique tag for every build. ## Related resources - [Configure app networking](/deploy/networking/) - Set up ports, reach, and how traffic gets to an app. - [Review app security](/deploy/security-tab/) - Scan the image for known vulnerabilities and check the app's settings. --- # Configure app networking > Set how an Orchard app is reached, connect apps with internal addresses, publish raw TCP or UDP ports, and read client details from request headers. Source: https://docs.orchard.hackclub.com/deploy/networking/ Networking decides who can reach an app and how. Each port gets a reach, from a public HTTPS URL to an address that only other apps in the same environment can use, so you expose exactly what you mean to. Behind every port, a Kubernetes Service balances traffic across the app's replicas. You manage ports on the app's **Network** tab. ## Reach Reach sets who can connect to a port. You choose it when you create an app. | Reach | Result | | ---------------- | ---------------------------------------------------------------------------------------- | | **Private link** | An HTTPS URL behind Orchard sign-in. Only people with access to the project can open it. | | **Public link** | An HTTPS URL open to anyone. | | **Public port** | Raw TCP or UDP on an external address. | | **Internal** | A cluster-internal address with no URL. | UDP ports support only **Public port** and **Internal**. ## Connect apps inside the cluster To call another app in the same environment, use its internal address. **Network** > **Ports** shows the address below each port, in this form: ```text ..svc.cluster.local: ``` Inside the same namespace, the short form `:` also resolves. Use the internal address for traffic between apps. A request to a public URL leaves the cluster, depends on public DNS, and passes through the ingress. [Tenant namespaces deny incoming traffic by default](/operate/security/#network-isolation). Apps in the same namespace can reach each other. Each [environment](/start/concepts/#environment) has its own namespace, so apps in different environments cannot use internal addresses to reach each other. ## Add a port **Dashboard** 1. Open the app. 2. Go to **Network**. 3. In **Ports**, select **Add port**. 4. In **Port**, enter the port your process listens on inside the container. 5. Select **TCP** or **UDP**. 6. Select **Add port**. **CLI** ```sh orchard service create --deployment --port 8080 ``` To use UDP, add `--protocol UDP`. ## Publish a TCP or UDP port Publish a raw port to reach a game server or another non-HTTP service from outside the cluster. ### Prerequisites - A layer 4 (L4) load balancer in the cluster. - A public IP address. To set one for your organization, go to **Organization settings** > **Database defaults** > **Public database IP**. Otherwise, the organization inherits the instance default. If neither exists, publishing fails with an error. A superadmin sets the instance default as described in [Set a default public IP](/operate/finishing-setup/#set-a-default-public-ip). This feature is not available in Cloudflare Tunnel mode, because tunnels carry HTTP only. ### Steps **Dashboard** 1. Open the app. 2. Go to **Network**. 3. In **Ports**, turn on **Public** for the port. 4. Select **Make public**. The public address replaces the internal address on the row. Until the load balancer assigns the address, the row shows **Waiting for an address**. If the load balancer reports an error, the row shows the reason instead. For the causes, refer to [Troubleshoot a public address](#troubleshoot-a-public-address). **CLI** ```sh orchard service port public enable --deployment ``` > **Caution** > > Public TCP and UDP traffic skips the HTTP layer, so [app protection](/deploy/protection/) does not apply. The service must handle its own authentication. ### Troubleshoot a public address A public port or a [public database](/data/databases/#public-access) is reachable only after the cluster's load balancer assigns it an address. Orchard reads the state from Kubernetes and shows one of these states: | State | Meaning | | -------------------------- | ------------------------------------------------------------------------------------------ | | **Live** | The load balancer assigned the address. The port accepts connections. | | **Waiting for an address** | The load balancer has not assigned an address yet. A cloud load balancer can take minutes. | | An error with a reason | The load balancer reported a problem. The address does not accept connections. | If Orchard cannot read the state from Kubernetes, the row shows the address without **Live**. | Reason | Cause and fix | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Port _N_ is already in use on the server** | On k3s, the built-in load balancer (ServiceLB) listens on the port on every node, and another LoadBalancer Service or a pod with a host port already holds that port. Turn **Public** off and on to get a new port, or remove the other Service. | | **No address could be allocated** or **No address could be assigned** | MetalLB or Cilium has no free address in its pool, or the public IP is not in a pool. Add the organization's public IP to an address pool, or free an address. | | **The load balancer could not be created** | The cloud provider rejected the request. The reason includes the provider's message, for example a quota limit. Fix the cause in the cloud account. Orchard picks up the address when the provider assigns it. | | **The load balancer assigned _X_ instead of _Y_** | The load balancer ignores the requested IP address. Set the organization's public IP to the assigned address, or configure the load balancer to honor `spec.loadBalancerIP`. | | **No load balancer assigned an address after 5 minutes** | Nothing in the cluster handles LoadBalancer Services. Install a load balancer such as MetalLB, or use k3s with ServiceLB. | To read the full history, run `kubectl describe service -n ` and check **Events**. ## Outbound traffic Apps can reach the public internet. The tenant network policy blocks traffic to private address ranges and to the link-local range that holds cloud metadata services. It also blocks the Kubernetes API, the control-plane database, and unpublished services in other namespaces. ## Request headers Traffic reaches your app through at least one proxy, so the socket peer is the proxy. Client details arrive in headers. | Header | Set by | Contains | | ------------------- | ---------------------------------- | --------------------------------------- | | `X-Real-IP` | The ingress | The peer of the inbound TCP connection | | `X-Forwarded-For` | The ingress, appended for each hop | The client chain, left to right | | `X-Forwarded-Proto` | The ingress | `https` or `http`, as the client saw it | | `X-Forwarded-Host` | The proxy | The hostname the client requested | To get the client address, use `X-Real-IP`. The ingress sets it to the actual peer and overwrites any value from the client. Clients can add entries to `X-Forwarded-For`. Trust only the entries your own proxies added. If your framework derives the client IP from this header, configure the number of proxy hops to trust. A domain with [protection](/deploy/protection/) adds a hop. The protection proxy forwards these headers and appends the peer it saw. It removes `x-orchard-protection-bypass` before the request reaches your app. To build absolute URLs, use `X-Forwarded-Proto` and `X-Forwarded-Host`. Otherwise, a framework can generate links that point at a pod IP address. ## Databases Managed databases are reachable inside the cluster by default. To publish one, refer to [Public access](/data/databases/#public-access). ## Related resources - [Manage domains and HTTPS](/deploy/domains/) - Add a custom domain to an app and redirect domains. - [Reach apps over Tailscale](/deploy/tailscale/) - Give an app a private address on your tailnet. --- # Protect an app > Require a sign-in, a password, or a username and password before visitors can reach an Orchard app, and exclude paths such as webhook receivers. Source: https://docs.orchard.hackclub.com/deploy/protection/ Protection puts a sign-in, a password, or HTTP basic authentication in front of an app, so a staging site or an internal tool is not open to the whole internet. You add it to a domain, and requests to that domain go through Orchard's proxy before they reach the app. Your app needs no changes. ## Protection types | Type | Who can reach the app | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **None** | Anyone. | | **Password** | Visitors who enter the shared password. | | **Username and password** | Clients that send the correct HTTP basic authentication credentials. | | **Project members** | People who sign in to Orchard and have access to the project: its members, the owners and admins of its organization, and superadmins. | A generated URL with the [reach](/deploy/networking/#reach) **Private link** starts with **Project members**. A generated URL with the reach **Public link**, and a custom domain, start with **None**. ## Set protection **Dashboard** 1. Open the app. 2. Go to **Network**. 3. In **Domains**, select **Add protection** on the domain. If the domain already has protection, select its badge. 4. In **Protection type**, select a type. 5. Enter the password, or the username and password, if the type needs them. A password must have at least 8 characters. 6. Select **Save**. **CLI** ```sh orchard domain protection set --mode orchard ``` The `--mode` flag accepts `none`, `password`, or `orchard`. For `password`, add `--password`. To set **Username and password**, use the dashboard. To make a protected URL public, select **None**, then select **Save**. ## Exclude public paths Webhook receivers, health endpoints, and OAuth callbacks must stay reachable. If they sit behind protection, the sender receives a sign-in page and the delivery fails. Add these routes as public paths before you point a provider at the app. 1. In the **Protection** dialog, find **Public paths**. 2. Enter one path per line. `/api` also opens `/api/v1`. It does not open `/apikeys`. 3. Select **Save**. ## Protect a domain with several paths Each path on a domain has its own protection, so you can protect `/` and leave `/docs` public. Each path keeps its own sign-in, and the **Protection** dialog lists the paths on the domain that are still public. A path you add to a domain that already has protection starts with the same protection. To make it public, open its **Protection** dialog and select **None**. > **Caution** > > A path on the domain with its protection set to **None** skips the sign-in check before the request reaches your app. If that path and a protected path point to the same app, list the route in **Public paths** instead, which checks each request first. Orchard never treats a path as public when it is ambiguous: any path containing `;`, a backslash, `//`, a `.` or `..` segment, or a percent-encoded `.`, `/`, `\`, `;` or `%` falls through to the normal sign-in. This holds whatever your ingress controller does with those paths. Orchard recommends that you confirm it against your own HAProxy or Traefik. With `/public` as a public path, each of these requests must return the sign-in redirect, or `401` for basic authentication, and never your app: ```bash for p in '/public/..;/private' '/public/%2e%2e/private' '/public/..%2fprivate' \ '/public%2f..%2fprivate' '/public//..//private' '/public\..\private' \ '/public/%252e%252e/private' '/public/./../private' '/public/..'; do curl -s -o /dev/null -w "%{http_code} $p\n" --path-as-is "https://app.example.com$p" done curl -s -o /dev/null -w "%{http_code} /public/ok\n" https://app.example.com/public/ok ``` Only the last request reaches the app. Run the test again after you change the ingress controller or its path-handling settings. ## Skip protection from scripts Scripts and CI can skip sign-in with a bypass header. After you save protection, reopen the **Protection** dialog to copy the header from **Bypass header**. ```text x-orchard-protection-bypass: ``` Orchard removes this header before the request reaches your app. ## How operators enable each type **Password** and **Username and password** work on every cluster. For **Username and password**, the server checks whether the cluster has the `cilium.io` API group and whether it may create `ciliumenvoyconfigs`: - With Cilium, Orchard adds an Envoy basic authentication filter in front of the Service. The password covers every path to that Service. - Without Cilium, Orchard's protection proxy checks the credentials. The proxy protects the HTTP route, so a pod that can reach the app directly is not affected. To limit that, add a NetworkPolicy. To force the choice, set `CILIUM_ENABLED` to `true` or `false` on the server. To let people choose **Project members** on their own domains, set `protection.orchardLogin: true` in the chart. It needs `FRONTEND_URL` to be reachable from where the app is served. The value only controls whether people can choose this type. Turning it off does not remove protection from hosts that already use it, and generated URLs can still start with **Project members**. ## Limitations Protection covers HTTP. Raw TCP and UDP ports do not pass through the proxy, so protection does not apply to them. ## Related resources - [Manage domains and HTTPS](/deploy/domains/) - Add the custom domains that protection applies to. - [Turn on bot protection](/operate/bot-protection/) - Add a Cloudflare Turnstile challenge to sign-in pages and password-protected apps. --- # Apply resource suggestions > Use Orchard resource suggestions to set an app's CPU and memory from its measured usage. Source: https://docs.orchard.hackclub.com/deploy/resource-suggestions/ Guessing CPU and memory leads to apps that run out of memory or reserve capacity they never use. Orchard reads an app's measured usage and suggests values that fit it, with a sentence that explains why. Nothing changes until you apply a suggestion. ## Prerequisites - Edit access to the project. - At least three days of history for the app in the metrics store. ## Apply a suggestion 1. Open the app. 2. Go to **Settings** > **Resources**. 3. In **CPU and memory**, read the row that starts with **Suggested**. The row explains why Orchard suggests the change. 4. Select **Apply**. This updates the form. 5. Select **Save**. Saving restarts the app. If the row does not appear, Orchard has no suggestion for the app. ## How Orchard calculates a suggestion Orchard uses up to 14 days of history. | Resource | Target | Minimum | | -------- | ----------------------------------------------------------------------------------- | ------------------------------------------- | | Memory | 115% of the highest daily peak. | 128 MiB, or more for an image that needs it | | CPU | The larger of 115% of the 99th percentile and 150% of the 95th percentile of usage. | 100m | Orchard rounds each target up to the next resource preset or step. Orchard also applies these rules: - If the app ran out of memory, the suggestion raises memory by at least 20%, and by at least 100 MiB. - If the app was throttled more than 10% of the time at the 95th percentile, Orchard treats the CPU limit as the bottleneck. Orchard does not suggest a lower CPU value. - If the app restarted in the last 24 hours, Orchard does not suggest lower values. - Orchard ignores changes under 25% of the current value. - Orchard ignores memory changes under 128 MiB and CPU changes under 100m. Orchard does not suggest values for an app that has no [limits](/operate/resource-limits/). When you apply suggestions, you have an app sized to what it uses. To scale it out instead of up, refer to [Scale an app and set resources](/deploy/scaling/). ## Related resources - [Set quotas](/teams/quotas/) - Cap how much CPU and memory an organization and its members can use. - [Monitor an app](/run/monitor-an-app/) - Read the usage graphs that suggestions are based on. - [Review usage](/teams/usage/) - Compare what each project and app uses. --- # Roll back an app > Roll an Orchard app back to an earlier image, optionally restore its bound databases, and restart an app on the same image. Source: https://docs.orchard.hackclub.com/deploy/rollbacks/ When a deploy goes wrong, a rollback puts the app back on an earlier image in the time it takes to start new pods, with no rebuild. A rollback is a deploy of the older image, so it uses the same [rolling update](/deploy/update-strategies/) and [health checks](/deploy/scaling/#set-health-checks) as any other deploy. A rollback does not revert your repository. It also leaves the database schema as it is, unless you restore bound databases. ## Roll back an app **Dashboard** 1. Open the app. 2. Go to **Activity**. 3. In **History**, find the release. 4. Select **Roll back**. To return to the previous release, select **Roll back** on the **Live** release at the top of the page. 5. (Optional) Select **Also restore bound databases to before this deploy**. Each database returns to its [checkpoint](/data/backups/#take-a-checkpoint) from before the deploy. 6. Select **Promote**. **CLI** To roll back to the previous release: ```sh orchard deploy rollback --wait ``` To roll back to a specific release, get its ID from `orchard deploy releases `, then run the following command: ```sh orchard deploy rollback --wait ``` To restore bound databases too, add `--restore-databases`. > **Caution** > > Restoring a database discards writes made after the checkpoint. If you do not restore, a destructive migration stays in place and the older image runs against the new schema. ## Recover from a bad deploy 1. Roll back to the last working image. 2. Fix the problem in the repository. 3. Push the fix. If [auto-deploy](/deploy/github/#auto-deploy) is on, Orchard builds and deploys it. ## Restart an app A restart creates new pods on the same image. Use it for a stuck process, such as a blocked connection pool. If the image has the problem, use a rollback instead. **Dashboard** Open the app and select **Restart** in the header. **CLI** ```sh orchard deploy restart ``` ## Related resources - [Builds](/deploy/builds/) - Find out why a build failed before you push a fix. - [Back up and restore a database](/data/backups/) - Restore a database on its own, outside a rollback. - [`orchard deploy` reference](/reference/cli/#deploy) - Every flag of the `orchard deploy` commands. --- # Scale an app and set resources > Change the replica count of an Orchard app, stop and start it, set its CPU and memory, and configure health checks. Source: https://docs.orchard.hackclub.com/deploy/scaling/ Scale an app out with more replicas so that it handles more traffic and survives a pod restart, or scale it up with more CPU and memory. Health checks tell Orchard when a pod is ready, so a deploy only sends traffic to pods that work. You can also stop an app to free its resources and start it again later. ## Change replicas **Dashboard** 1. Open the app. 2. Go to **Overview**. 3. In **Pods**, use the **Replicas** control to set the count. **CLI** ```sh orchard deploy scale 3 ``` A deploy does not drop traffic if more than one replica is up and health checks pass. ## Stop and start an app Stopping an app scales it to zero and keeps its replica count for later. While the app is stopped, Orchard holds pushes to its repository and does not build them. The header shows how many pushes it holds, such as **3 pushes since**. **Dashboard** To stop the app, open **More actions** in the header and select **Stop**. To start it again, take one of these steps in the header: - Select **Start**. - If pushes are held, select **Build and start**. Orchard builds the newest held commit. - To build from the current branch head, open **More actions** and select **Deploy and start**. **Restart** stays off until the app runs. **CLI** ```sh orchard deploy stop orchard deploy start orchard deploy start --build ``` `start` builds the newest held push if one exists. `--build` rebuilds from source before starting. ## Set CPU and memory **Dashboard** 1. Open the app. 2. Go to **Settings** > **Resources**. 3. In **CPU and memory**, select the sizes. 4. Select **Save**. Saving restarts the app. **CLI** ```sh orchard deploy resources set --cpu 500 --memory 512Mi ``` `--cpu` is in millicores. A value of `0` clears the setting to the organization default. The value you select is the container's limit. If a superadmin has [turned resource limits off](/operate/resource-limits/), the resource picker shows that limits are off and these sizes do not apply. To size an app from its measured usage, [apply resource suggestions](/deploy/resource-suggestions/). - **Memory:** The request equals the limit. The app gets that amount, and Kubernetes kills it if it uses more. - **CPU:** The request is 10% of the limit, with a minimum of 50 millicores. The app can use CPU up to the limit when the node has capacity. To change this, set `CPU_REQUEST_RATIO` and `CPU_REQUEST_MIN_MILLI` on the server. > **Caution** > > When you change resources through the API, send every field you want to keep. An omitted value falls back to the organization default, which may be smaller than the current size. ## Set health checks Health checks decide whether a pod counts as ready. An app that runs but fails its check shows as failing. Orchard applies the checks again on each rebuild. **Dashboard** 1. Open the app. 2. Go to **Settings** > **Health checks**. 3. Turn on **Check this app**. 4. In **Check with**, select the method. 5. Enter the path or command, and the port. 6. Select what the check controls: **Restart the container when it fails**, **Stop sending traffic until it passes**, or **Allow extra time on startup**. 7. Select **Save**. Saving restarts the app. **CLI** ```sh orchard deploy health-check set --path /healthz --port 3000 ``` ## Quotas An organization can set resource caps, and each member can have an allowance inside those caps. The limit for a new app is the smaller of the amount left in your allowance and the amount left in the organization's cap. To set caps and allowances, refer to [Set quotas](/teams/quotas/). ## Related resources - [Metrics and alerts](/run/observability/) - Watch CPU, memory, and restarts after you change resources. - [Attach storage to an app](/deploy/storage/) - Keep files across restarts, and learn how volumes limit replicas. - [Choose an update strategy](/deploy/update-strategies/) - Control how Orchard replaces pods during a deploy. - [`orchard deploy` reference](/reference/cli/#deploy) - Every flag of the `orchard deploy` commands. --- # score.yaml > Describe an Orchard app's ports, variables, and databases in a Score file in the repository. Orchard reads the file on creation and on each auto-deploy push. Source: https://docs.orchard.hackclub.com/deploy/score/ A [Score](https://score.dev) file lets you keep an app's ports, variables, and databases in the repository next to the code, instead of setting them by hand in the dashboard. Score is an open specification, so the same file can describe the workload to other platforms. Name the file `score.yaml` or `score.yml`. Orchard reads it when you create the app, and again on each push that [auto-deploys](/deploy/github/#auto-deploy). The Score file describes the workload. `orchard.json` describes the build. ## Example ```yaml apiVersion: score.dev/v1b1 metadata: name: web annotations: orchard.my/domain: midnight.example.com orchard.my/replicas: '2' containers: web: image: . variables: DATABASE_URL: ${resources.db.connection_string} LOG_LEVEL: info service: ports: www: port: 8080 targetPort: 3000 resources: db: type: postgres ``` ## Field reference | Score field | Orchard result | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `containers..variables` | The app's variables. Keys that are not in the file stay as they are. | | `service.ports` | The app's ports. | | `resources.` with `type: postgres` | [A managed database](/data/databases/) named `` in the project. Orchard creates it if it is missing and connects it to the app. | | `${resources..}` | A reference to that database, resolved when the pod starts. | | `orchard.my/domain` | [A custom domain](/deploy/domains/#add-a-custom-domain) routed to the app. | | `orchard.my/replicas` | The replica count. | Orchard deploys only the first container. `image: .` means the image Orchard builds. If you name another image, Orchard still builds from the repository. ## Database references Orchard writes `${resources.db.connection_string}` as `${{resource.db.connection_string}}`. This is the same [reference](/deploy/connect-resources/) you get from **Use a resource** on the app's **Variables** tab. The reference follows the database through a password rotation or a restore. These fields are available: - `connection_string` or `url` - `host` - `port` - `name` or `database` - `username` or `user` - `password` If a variable references a resource the file does not provision, Orchard leaves the reference in place and reports it. The app then refuses to start. ## Limitations - `type: redis` and `type: valkey` are recognized, but managed Valkey is not available. Orchard reports the resource and skips it. - Orchard ignores other resource types and adds a note. - Orchard reads `orchard.my/health-path`, but it does not set [health checks](/deploy/scaling/#set-health-checks) from Score. ## View what Orchard applied When Orchard finds a Score file, the new app form shows the databases, ports, and domain that it sets up. Each later apply adds an entry to the [audit log](/teams/audit-logs/) with what changed. ## Related resources - [Deploy from GitHub](/deploy/github/) - Create the app that reads the Score file, and turn on auto-deploy. - [Score specification](https://docs.score.dev/) - Read the full Score file format. --- # Review app security > Read configuration findings, image scan results, and attack attempts for an Orchard app on the Security tab. Source: https://docs.orchard.hackclub.com/deploy/security-tab/ The **Security** tab of an app collects what you need to judge its exposure in one place: settings that put it at risk, known vulnerabilities in its image, and suspicious requests that reach it. Each finding links to the setting that fixes it. To open the tab, open the app and select **Security**. ## Configuration The **Configuration** card checks the app's settings. These checks do not need a scanner. | Finding | Meaning | How to resolve | | ------------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | **Secrets in plain variables** | A variable name looks like a secret, and the value is stored as plain text. | Select **Variables**, then store the value as a [secret](/run/environments/#secrets). | | **Served over plain HTTP** | A domain on the app has no TLS and is not a redirect. | Select **Network**, edit the domain, then turn on **HTTPS**. | | **Image tag can change** | The image uses a tag that can point to a different image, such as `latest`. | Select **Source**, then set a fixed tag. | When there are no findings, the card shows **Nothing to flag**. ## Image scan The **Image scan** card lists known vulnerabilities in the app's container image. A superadmin must [set up a scanner](/operate/image-scanning/) on the instance. To run a scan, select **Scan now** or **Scan again**. | Message | Meaning | | ----------------------------------------- | ----------------------------------------------------------------------------- | | `No known vulnerabilities` | The scan found no known vulnerabilities. | | `Not scanned yet` | No scan has run for this image. | | `The last scan failed` | The scan did not finish. The card shows the error. | | `Image scanning is off` | No scanner is selected on this instance. | | `Scanning isn't set up on this instance` | A scanner is selected, but its credentials or server are missing. | | `Harbor only scans images Orchard builds` | The app uses an external image, and the instance uses Harbor. | | `This image is no longer in the registry` | The image was removed from the registry. Redeploy to build and scan it again. | | `The scanner refused Orchard` | The scanner rejected the credentials. | | `Can't reach the scanner` | Orchard cannot connect to the scanner. | ## Attack attempts The **Attack attempts** chart and the **Top sources** list show suspicious requests from the last 24 hours. Orchard finds these requests in the ingress access logs. Orchard records them, but does not block them. | Category | Condition | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Scanners** | The path targets a common probe location, such as `/.env`, `/wp-admin`, or `/.git`, or the user agent is a known scanning tool. | | **Injection** | The path contains an SQL injection, path traversal, script injection, or JNDI lookup pattern. | | **Password guessing** | One client address receives at least 21 `401` or `403` responses from one path within 5 minutes. | | **Floods** | One client address sends at least 300 requests, and more than 10 times the median of all clients. This check needs at least 5 client addresses. | If the card shows `Requests aren't recorded yet`, the log store has no access logs for the app. To set up access logs, refer to [Configure logs and request data](/operate/logs/). The **Top sources** list can show the row **Hidden by the load balancer**. This row groups private and cluster addresses, which usually means the load balancer hides the real client address. To fix it, refer to [Client IPs show as hidden](/operate/logs/#client-ips-show-as-hidden). ## Related resources - [Protect an app](/deploy/protection/) - Require a sign-in or a password before a domain opens. - [Turn on bot protection](/operate/bot-protection/) - Add a Cloudflare Turnstile challenge to sign-in pages and password-protected apps. --- # Attach storage to an app > Attach a persistent volume to an Orchard app so that its files survive restarts and redeploys. Source: https://docs.orchard.hackclub.com/deploy/storage/ A container's filesystem is deleted when the pod restarts, so an app that writes uploads, a SQLite file, or a cache to disk loses them on every deploy. Attach a volume to keep those files. Orchard creates a PersistentVolumeClaim from the cluster's storage class and mounts it at the path you choose. ## Attach a volume **Dashboard** 1. Open the app. 2. Go to **Settings** > **Storage**. 3. In **Volumes**, select **Add volume**. 4. In **Name**, enter a name for the volume. 5. In **Mount path**, enter the path inside the container, such as `/data`. 6. In **Size**, enter the size, such as `1Gi`. 7. (Optional) Turn on **Read-only**. 8. Select **Save**. Saving restarts the app. You can also add a volume when you create an app, under **Advanced** > **Storage**. **CLI** ```sh orchard deploy volumes set --volume /data=1Gi ``` This command replaces all the app's volumes with the ones you pass. To remove every volume, omit `--volume`. ## Verify the mount From a [shell](/run/logs/#open-a-shell) in the container, list the mount path. An empty ext4 volume contains a `lost+found` directory. If the path is not mounted, its contents are ordinary container storage and are deleted with the pod. ## Limitations - Most storage classes allow one writer at a time. If you scale past one replica on one of these classes, the extra pods do not start. - With a volume, [updates stop the app first](/deploy/update-strategies/). - Volumes can grow, but they cannot shrink. Growth needs a storage class that allows expansion. - Orchard does not back up app volumes. To keep data safe, write it to object storage or a [managed database](/data/databases/). Managed databases have their own storage and do not need a volume. ## How volumes interact with builds Orchard records a volume as soon as you add it. A volume you add during a build reaches the pod that build creates. Each rebuild also compares the running pod with the configured volumes and repairs any difference. ## Related resources - [Scale an app and set resources](/deploy/scaling/) - Change replicas, CPU, and memory. - [Grow database storage](/data/storage/) - Increase the volume size of a managed database. --- # Reach apps over Tailscale > Give an Orchard app a private address on your tailnet, without a public URL or an open port. Source: https://docs.orchard.hackclub.com/deploy/tailscale/ Put an app on your [Tailscale](https://tailscale.com/) network when only your own devices should reach it, such as an internal tool or an admin panel. Devices on your tailnet reach the app at a private address, so the app needs no public URL or open port. Orchard runs a Tailscale proxy pod next to the app, in the same namespace. The proxy joins your tailnet with your auth key and forwards traffic to the app's Service. The app's own pods do not change or restart. ## Prerequisites - A Tailscale account. - Edit access to the project. - On an instance that uses PostHog, the Tailscale feature turned on for your account. Go to **Account settings** > **Early access**. On an instance with no PostHog key, the feature is always on. ## Link your tailnet An auth key connects your Orchard account to your tailnet. Each person links their own key. 1. In the [Tailscale admin console](https://login.tailscale.com/admin/settings/keys), go to **Settings** > **Keys** and select **Generate auth key**. 2. Turn on **Reusable** and **Ephemeral**. Leave the tags empty. 3. Set the key to expire in 90 days, the longest period Tailscale allows. 4. Copy the key. It starts with `tskey-auth-`. **Dashboard** 1. Go to **Account settings** > **Connections**. 2. In **Tailscale**, select **Connect**. 3. Paste the auth key and select **Connect**. **CLI** ```sh orchard tailscale link ``` The command prompts for the key. You can also set `ORCHARD_TS_AUTHKEY` or pass `--auth-key`. Orchard encrypts the key before it stores it. ## Put an app on your tailnet **Dashboard** 1. Open the app and go to the **Network** tab. 2. In **Ports**, turn on the **Tailscale** switch. The address appears in the same row when the proxy joins the tailnet. **CLI** ```sh orchard tailscale expose orchard tailscale get ``` The device name on your tailnet is `-`. With [MagicDNS](https://tailscale.com/kb/1081/magicdns) on, the address is: ```text -..ts.net ``` Tailscale access controls apply to this device in the same way as to any other device on your tailnet. ## Remove an app from your tailnet **Dashboard** 1. Open the app and go to the **Network** tab. 2. In **Ports**, turn off the **Tailscale** switch. **CLI** ```sh orchard tailscale unexpose ``` Orchard deletes the proxy pod and its copy of the auth key. Orchard also removes the proxy when you delete the app or its project. ## Unlink your tailnet Go to **Account settings** > **Connections**, and in **Tailscale**, select **Disconnect**. In the CLI, run `orchard tailscale unlink`. > **Caution** > > Unlinking removes every app you put on your tailnet from it. Apps that other people put on their tailnets stay connected. ## When an auth key expires A proxy uses its auth key when it joins your tailnet. After the key expires, a proxy that has to join again fails, and new apps cannot join. To replace the key: 1. Generate a new auth key and link your tailnet again. The new key replaces the old one on your account. 2. For each app, turn the **Tailscale** switch off and on. Each proxy keeps its own copy of the key, so an app only gets the new key when its proxy is created again. ## Related resources - [Configure app networking](/deploy/networking/) - Set up ports, reach, and how traffic gets to an app. - [Protect an app](/deploy/protection/) - Require a sign-in or a password before a public URL opens. - [`orchard tailscale` reference](/reference/cli/#tailscale) - Every flag of the `orchard tailscale` commands. --- # Choose an update strategy > Select how Orchard replaces an app's pods during a deploy, and how many pods stay ready when a node drains. Source: https://docs.orchard.hackclub.com/deploy/update-strategies/ The update strategy controls how Orchard replaces an app's pods when you deploy a new version, which decides whether visitors see any downtime. Most apps keep the default, **Rolling**. Change it when an app cannot run two versions at the same time, or when you want traffic to move only after every new pod is ready. | Strategy | CLI value | Behavior | | -------------- | --------------- | ------------------------------------------------------ | | **Rolling** | `rollingupdate` | New pods start before old pods stop. | | **Recreate** | `recreate` | All pods stop first. The app has brief downtime. | | **Blue/green** | `bluegreen` | Traffic moves to new pods when the new pods are ready. | Apps with [storage](/deploy/storage/) must use **Recreate**. The other strategies are not available for those apps. ## Prerequisites - Edit access to the project. ## Change the strategy **Dashboard** 1. Open the app. 2. Go to **Settings** > **Deploy behavior**. 3. In **Updates**, select a **Strategy**. Orchard saves the change immediately. The new strategy applies to the next deploy. **CLI** ```sh orchard deploy strategy set --type bluegreen ``` ## Keep pods ready during a node drain **Keep ready during a drain** sets how many pods stay ready when a node drains. This setting creates a Kubernetes PodDisruptionBudget. 1. Open the app. 2. Go to **Settings** > **Deploy behavior**. 3. In **Updates**, set **Keep ready during a drain**. Orchard saves the change immediately. The setting takes effect when the app has more replicas than the value. If you set the value to 0, a drain can take all pods down at the same time. ## Related resources - [Scale an app and set resources](/deploy/scaling/) - Run more replicas so that a rolling update keeps serving traffic. - [Roll back an app](/deploy/rollbacks/) - Return an app to an earlier release. - [`orchard deploy strategy` reference](/reference/cli/#deploy) - Every flag of the `orchard deploy strategy` commands. --- # Docs for agents > Read Orchard documentation as Markdown with .md URLs and llms.txt, and find the entry points that agents use to call the Orchard API. Source: https://docs.orchard.hackclub.com/for-agents/ Every page of this documentation is also available as plain Markdown, so an agent can read it without parsing HTML or running a browser. This page lists those Markdown sources, and the separate entry points an agent uses to operate an Orchard instance through MCP or the API. ## Get a page as Markdown Add `.md` to a documentation URL: ```txt https://docs.orchard.hackclub.com/start/install/ the page https://docs.orchard.hackclub.com/start/install.md its Markdown source ``` The home page is at `/index.md`. Each page has these actions under its title: | Action | Result | | -------------------- | -------------------------------------------- | | **Copy as Markdown** | Copies the page as Markdown. | | **View as Markdown** | Opens the Markdown source. | | **Agent setup** | Opens the [agent setup](/agent-setup/) page. | The menu next to them has **Open in Claude**, **Open in ChatGPT**, and **Connect to MCP**. ## Use llms.txt Two files follow the [llms.txt](https://llmstxt.org) convention. | File | Contents | | ------------------------------------------------------------------- | ---------------------------------------------------------------- | | [`/llms.txt`](https://docs.orchard.hackclub.com/llms.txt) | An index of every page, grouped by section, with Markdown links. | | [`/llms-full.txt`](https://docs.orchard.hackclub.com/llms-full.txt) | The entire documentation set as one document. | Use `llms.txt` to decide what to read. Use `llms-full.txt` to load everything in one request. ## Operate an instance This documentation has no MCP server. The Orchard MCP server runs at `mcp.` and operates your instance instead of serving these pages. To set it up, refer to [Connect an MCP client](/mcp/). An agent can also use the following entry points, which [code mode for agents](/agents-code-mode/) describes in detail. | Entry point | Purpose | | ----------------------------------- | -------------------------------------------------------- | | `GET /apiv1/agent-spec.json` | A trimmed spec of the operations that an agent can call. | | `GET /apiv1/openapi.json` | The complete OpenAPI document. | | `orchard api search` and `describe` | The same spec from a shell, with calls by `operationId`. | | `https://mcp./compact` | The whole API through three MCP tools. | ## Check whether a deploy worked Send the following request: ```txt GET /apiv1/deployments/:id/rollout?wait=1 ``` The response has the phase and, when the deploy is live, the URL. When the deploy fails, it has the build error or the crashing pod with a log tail. To [roll back](/deploy/rollbacks/) to the previous image, send `POST /apiv1/deployments/:id/rollback` with no history ID. ## Retry requests safely To retry a request without doing the work twice, send an `Idempotency-Key` header. Orchard supports this header on requests that create a project, app, or database, rebuild, restart, or roll back an app, run a job, restart a database, and upgrade, fork, checkpoint, or restore a database. A retry with the same key and body replays the first response for 24 hours. The same key with a different body returns a `422` status. A key that is still in progress returns a `409` status. ## Related resources - [Use the CLI](/cli/) - Install the `orchard` CLI and script it with JSON output and stable exit codes. - [MCP tools](/reference/mcp-tools/) - Every tool that the Orchard MCP server exposes. --- # Post announcements > Use the Orchard announcements graft to post instance-wide notices that appear on every project and app page. Source: https://docs.orchard.hackclub.com/grafts/announcements/ The announcements graft lets superadmins tell every person on the instance about something, such as planned maintenance, without sending email. Active notices appear on project and app overview pages. ## Prerequisites - The `announcements` graft [installed on your instance](/grafts/install/). - The superadmin role, to post or remove a notice. ## Post a notice 1. Go to **Instance admin** > **Announcements**. 2. In **Message**, enter the text. The limit is 500 characters. 3. In **Tone**, select **Info**, **Good news**, or **Warning**. 4. In **Hide after (hours, 0 keeps it up)**, enter the number of hours to show the notice. 5. Select **Post announcement**. The notice appears on project and app overview pages. ## Remove a notice 1. Go to **Instance admin** > **Announcements**. 2. On the notice, select **Take down**. ## Change how many notices appear 1. Go to **Instance admin** > **Configuration**. 2. In **Announcements**, set **Shown on overview pages** to a value from 1 to 10. The default is 3. 3. Save the section. ## Related resources - [Grafts](/grafts/overview/) - What grafts are and how Orchard loads them. - [Run the Grove](/run/grove/) - Another first-party graft, a forum for the people on an instance. --- # Use the database > Add migrations to an Orchard graft's own Postgres schema, read declared columns from Orchard's tables, and connect through the db door. Source: https://docs.orchard.hackclub.com/grafts/build/database/ Store a graft's data in its own Postgres schema. The schema is named `ext_`, with dashes turned into underscores. Orchard creates it, runs the graft's migrations in it, and points the graft's connections at it. A migration writes `CREATE TABLE notes` and does not name the schema. ## Add a migration Add a folder under `migrations/` with a `migration.sql` file: ```text migrations/ 0001_init/migration.sql 0002_pinned/migration.sql ``` Folders run in name order, and each runs once. A graft's pending migrations run in one transaction. A migration that cannot run in a transaction starts with a marker, and runs on its own: ```sql -- graft:no-transaction CREATE INDEX CONCURRENTLY notes_body ON notes (body); ``` `graft doctor` notes these migrations. Follow these rules: - **Do not edit a released migration.** Orchard checksums each one and refuses a graft whose history changed. Add a new migration. - **Support two versions during a rollout.** Old and new pods run side by side. Add new structures in one version, and remove what they replace in the next. - **Change only your own schema.** You can read core tables. `graft doctor` reports a problem for migrations that change them, unless the graft lists them in `database.adopts`. ## Read Orchard's tables Declare the core columns you need in `graft.json`, and join against them as `public.`: ```json { "database": { "coreReads": { "users": ["id", "username"] } } } ``` ```sql SELECT n.body, u.username FROM notes n LEFT JOIN public.users u ON u.id = n.created_by; ``` Foreign keys to core tables are allowed. Use `ON DELETE CASCADE` or `ON DELETE SET NULL`, so that a deleted user or project does not leave orphaned rows. When the database user can create roles, the graft's connections run as `orchard_ext_`. This role can use the graft's schema and read only the declared columns. > **Note** > > The role catches mistakes only. The graft's code runs inside Orchard, so the role is not a security boundary. ## Connect to the database [`Doors.db`](/grafts/build/server/#use-doors) gives you a `pg` pool that points at the schema: ```ts const { rows } = await this.db.query('SELECT * FROM notes WHERE id = $1', [id]); ``` To use a query builder or an ORM that accepts a `pg` pool, call `this.db.pool()`. The pool holds 3 connections per pod by default. To ask for more, up to 50, set this in `graft.json`: ```json "database": { "pool": 10 } ``` Operators can override the size with `orchardctl graft pool`. Orchard checks the pools of all pods against the database's [connection limit](/grafts/install/#database-connections). ## Related resources - [Upgrade and roll back grafts](/grafts/upgrades/) - How migrations run during upgrades, and how rollback restores data. - [Write server code](/grafts/build/server/) - Inject the `db` door into a controller. --- # graft.json > Review each field of graft.json, the Orchard graft manifest, how claims work, and which names a graft owns without a claim. Source: https://docs.orchard.hackclub.com/grafts/build/manifest/ `graft.json` is the manifest that Orchard reads before it runs a graft's code. Orchard refuses unknown fields when it checks or loads a graft. [`graft pack`](/grafts/build/quickstart/#3-check-pack-and-sign) checks only the required fields, so use [`orchardctl graft add --dry-run`](/grafts/install/#install-with-orchardctl) to validate the whole file. ```json { "id": "announcements", "name": "Announcements", "version": "0.2.0", "publisher": "orchard", "description": "Post instance-wide notices that show up on every project and app page.", "engines": { "platform": ">=2.67.0 <3", "sdk": "^1.0.0" }, "capabilities": ["db", "audit", "settings"], "database": { "coreReads": { "users": ["id", "username"] } }, "settings": [ { "id": "display", "title": "Announcements", "fields": [{ "key": "maxShown", "type": "number", "label": "Shown on overview pages" }] } ], "ui": { "screens": [{ "id": "manage", "path": "/announcements", "layout": "shell" }] } } ``` ## Fields | Field | Description | | --- | --- | | `id` | 2 to 48 lowercase letters, digits, and dashes, starting with a letter. It is the graft's URL prefix and namespace. Names in Orchard such as `admin` and `api` are reserved. | | `name`, `version`, `publisher`, `description`, `homepage`, `icon` | Shown in the Extension Marketplace and in **Instance admin** > **Grafts**. `version` is a semver version. | | `engines.platform` | The Orchard versions the graft works with, as a semver range. | | `engines.sdk` | The graft SDK versions it was built against. | | `uses` | Filled in by `graft pack`. The [doors](/grafts/build/server/#use-doors) and versions the server code injects. | | `requires.grafts` | Other grafts it needs, with version ranges. | | `requires.kubernetes.crds` | CRDs that must exist. `orchardctl` checks them before it installs the graft. | | `requires.kubernetes.verbs` | Kubernetes API verbs the graft uses, each with `group`, `resource`, `verb`, and an optional `namespace`. | | `capabilities` | What the graft asks for. Each door needs its capability. Refer to the [graft API reference](/reference/graft-api/). | | `database.coreReads` | Core tables and columns the graft can read, for joins. Shown before install. | | `database.adopts` | Core tables the graft takes over from an older Orchard that included the feature. Its first migration moves them into its own schema and leaves a view with the old name. Shown before install. The Extension Marketplace accepts this only from official grafts. | | `database.pool` | [Database connections per pod](/grafts/install/#database-connections), from 1 to 50. The default is 3. Operators can override it. | | `permissions` | Permissions the graft checks, with default grants by role. For example, `{ "use": { "label": "Use it", "defaultGrants": ["org:member"] } }`. | | `settings` | Sections for **Instance admin** > **Configuration**. Refer to [Settings](#settings). | | `ui.screens` | [Pages](/grafts/build/ui/#add-a-screen) the graft owns: `id`, `path` (with `:param` and a trailing `*`), `layout` (`shell` or `fullscreen`), `title`, and optional `og` metadata. | | `public.routes` | Every route open to anyone, as `"POST /hooks/github"`. Orchard refuses a public route that is not listed. | | `claims` | Names outside the graft's own ID. Refer to [Claims](#claims). | | `entries` | Filled in by `graft pack`. | ## Settings Each section has an `id`, a `title`, and `fields`. It can also have a `description`, a `storageKey`, and a `required` list of field keys. | Field property | Description | | --- | --- | | `key` | The field's key. | | `type` | `string`, `text`, `number`, `boolean`, `select`, or `secret`. | | `label`, `help` | The text in **Instance admin**. | | `env` | An environment variable that overrides the field. | | `options` | The choices for a `select` field. | | `default` | The default value. | Only instance-scoped fields are supported. A field with another `scope` adds a warning in **Instance admin** > **Grafts**. ## Claims A graft owns `/apiv1//...`, `//...`, and names that start with `.`, `-`, `/`, `:`, or `_` without a claim. A name outside that is a claim. Orchard shows claims to the operator before install. | Claim | Purpose | | --- | --- | | `apiAliases` | API paths. For example, `sandboxes` serves `/apiv1/sandboxes/...` from the graft's `sandboxes` controller. | | `uiAliases` | Top-level page paths. | | `wsAliases` | WebSocket paths. | | `hostRouting` | Hostnames the graft serves directly, for preview domains. | | `notificationEvents`, `notificationCategories` | Notification names. | | `configSections`, `settingKeys` | Settings names. | | `auditActions` | Audit log action prefixes. | | `mcpTools` | MCP tool names. | | `sseEvents` | Live event types. | | `rateLimitBuckets` | Rate limit names. | | `applyOps` | Apply queue operation names the graft handles. | | `deviceNames` | Session device name prefixes for organization-scoped tokens the graft mints. | | `engineShards` | Engine shard names the graft registers. `mirrorShards` is an older name for this claim, and it still works. | ### Conflicts Between two grafts, a name that one graft owns by its ID beats the other graft's claim. Otherwise, the first graft in the values list wins. The losing claim shows as **taken** in **Instance admin** > **Grafts** and is skipped. The graft keeps working under its own ID. For an `apiAliases` claim, a core route that handles the same path and method takes priority on each request. `graft doctor` notes each alias claim, because core Orchard can start using that path later. ## Related resources - [Write server code](/grafts/build/server/) - Add API routes and reach Orchard through doors. - [Add UI](/grafts/build/ui/) - Add pages, navigation, tabs, and cards. - [Use the database](/grafts/build/database/) - Add migrations and read Orchard's tables. - [Publish a graft](/grafts/build/publishing/) - Sign a graft and share it. --- # Publish a graft > Sign an Orchard graft, share it from an https address or a tap, and list it in the Extension Marketplace as a community graft. Source: https://docs.orchard.hackclub.com/grafts/build/publishing/ To let other Orchard instances install your graft, sign it and publish it in one of three ways. An `https` address needs only a file host. A listing in the Extension Marketplace lets operators find the graft with `orchardctl graft search`. - From any `https` address. - From a [tap](/grafts/install/#add-a-tap): your own catalog of grafts. - From the Extension Marketplace, as a community graft. ## Sign a graft A packed `.graft` is a tar.gz file with `graft.json`, the built code, migrations, a `MANIFEST.json` listing the SHA-256 of each file, and `MANIFEST.sig`, an ed25519 signature over that list. ```sh graft keygen ~/.config/graft/key.pem graft pack --key ~/.config/graft/key.pem ``` The command prints the public key. Operators add it to [`graftSettings.keys`](/grafts/install/#trust) to trust your grafts. In CI, set `GRAFT_SIGNING_KEY` to the base64 of the private key, instead of passing `--key`. ## Share a graft from an https address 1. Upload the `.graft` file to an `https` address. Use a separate address for each version. 2. Give operators this command: ```sh sudo orchardctl graft add https://example.com/snippets-0.1.0.graft ``` For Helm values, they use the entry that `graft pack` printed, with `source` set to the address. The digest pins the exact file. If the file at the address changes, installs fail. ## Run a tap A tap is a folder on an `https` host that people add once and then install from by name. 1. Create the tap: ```sh graft tap init ./my-tap --name acme --key ~/.config/graft/key.pem ``` 2. Pack a graft with the same key, and add it to the tap: ```sh graft pack --key ~/.config/graft/key.pem graft tap add ./my-tap notes-0.1.0.graft ``` 3. Upload `./my-tap` to a static host such as GitHub Pages, R2, or S3. 4. Give operators these commands: ```sh sudo orchardctl graft tap add acme https://grafts.example.com/orchard sudo orchardctl graft add acme/notes --apply ``` `graft tap add` refuses a file that is not signed with the tap's key. It also refuses different bytes for a published version. Bump the version instead. ## List a community graft Community grafts appear in the [Extension Marketplace](https://orchard.hackclub.com/extensions), labeled with their publisher. The code stays in your own repository. 1. Run `graft keygen`, and store the private key as a GitHub Actions secret. 2. Add a workflow that packs, signs, and attaches `-.graft` to each GitHub Release: ```yaml on: release: types: [published] permissions: contents: write jobs: graft: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: hackclub/orchard/.github/actions/graft-release@main with: key: ${{ secrets.GRAFT_SIGNING_KEY }} ``` 3. Open a pull request that adds `registry/community/.json` to the Orchard repository. For the file format, refer to [`registry/community/README.md`](https://github.com/hackclub/orchard/blob/main/registry/community/README.md). A maintainer reviews the first listing. After that, the Extension Marketplace checks for new releases every hour. It checks the signature, the file hashes, and that migrations do not change Orchard's tables. It then publishes the release with no further review. A release that fails a check is skipped, and the previous version stays available. ## Publish an official graft Official grafts live in the [`grafts/` directory](https://github.com/hackclub/orchard/tree/main/grafts) of the Orchard repository. CI runs `graft doctor` and packs each graft. On merge, CI signs new versions with Orchard's key and publishes them. Published versions do not change, so each update needs a new `version`. Each graft is a release-please component. `feat:` and `fix:` commits that touch it add it to the next release pull request, which bumps `package.json` and `graft.json`. Merging that pull request publishes the new version. To add a graft, add it to `release-please-config.json` and `.release-please-manifest.json`, like `grafts/greenhouse`. ## Version compatibility Each version lists the Orchard versions it works with in `engines.platform`. `orchardctl` installs the newest version that matches the instance. ## Related resources - [Install grafts](/grafts/install/) - What operators run to install your graft, and how trust works. - [Upgrade and roll back grafts](/grafts/upgrades/) - How operators move between your versions. --- # Get started > Build an Orchard graft by scaffolding it with the graft CLI, running it against a local Orchard, and packing and signing it. You need Node.js, pnpm, and a local Orchard dev stack. Source: https://docs.orchard.hackclub.com/grafts/build/quickstart/ Build a graft when Orchard is missing something your team needs. In this guide, you scaffold a graft, run it against your local Orchard, and pack it into a signed file that any instance can install. A graft is a folder with a [`graft.json`](/grafts/build/manifest/). It can also have a NestJS module for the API, a Svelte island for the UI, SQL migrations, and MCP tools. The `graft` command in `@orchardlabs/graft-sdk` builds, packs, and signs it. ## Prerequisites - Node.js and pnpm. - A local Orchard dev stack. To set one up, follow [Getting set up](https://github.com/hackclub/orchard/blob/main/CONTRIBUTING.md#getting-set-up) in the repository's contributing guide. ## 1. Scaffold a graft ```sh npx -p @orchardlabs/graft-sdk graft init snippets cd snippets pnpm install ``` The command creates these files: ```text snippets/ graft.json what the graft is and what it asks for package.json README.md server/src/index.ts NestJS module, default export ui/src/client.ts defineGraft({ slots, screens }) ui/src/Home.svelte migrations/0001_init/migration.sql tsconfig.json ``` ## 2. Run the graft In the graft's folder, run the following command: ```sh graft dev ``` The command builds into `.graft-dev/` and rebuilds when a file changes. Start the Orchard server and frontend with these variables: ```sh ORCHARD_GRAFTS_DIR=/path/to/snippets/.graft-dev ORCHARD_GRAFTS_DEV=1 ``` `ORCHARD_GRAFTS_DEV` skips signature checks for local work. The graft's pages are at `http://localhost:4000/snippets`, and its API is at `/apiv1/snippets/...`. **Instance admin** > **Grafts** shows its status. UI changes appear when you reload the page. Restart the API server to pick up server changes and new migrations. ## 3. Check, pack, and sign ```sh graft doctor graft keygen ~/.config/graft/key.pem graft pack --key ~/.config/graft/key.pem ``` `graft doctor` checks `graft.json` and the migrations for common mistakes. `graft pack` does the following: 1. It builds everything. 2. It records each route and its access level in `routes.json`. 3. It works out which [doors](/reference/graft-api/) the graft uses. 4. It hashes each file into `MANIFEST.json`, and signs that list. 5. It writes `snippets-0.1.0.graft`, and prints the Helm entry to install it. `graft pack` fails if a route open to anyone is not listed in `graft.json`, or if the code uses a door without its capability. Keep the private key secret. To let people trust your grafts, share the public key that `graft keygen` prints. ## Licenses `@orchardlabs/graft-sdk` is MIT licensed, so a graft that only imports it can use any license. `@orchardlabs/graft-ui` is licensed under AGPL-3.0-only. A graft that imports `@orchardlabs/graft-ui` must be released under a license compatible with AGPL-3.0-only, and the AGPL's source-sharing terms apply to it. To use another license, build the graft's UI with `@orchardlabs/graft-sdk` and your own components. `graft init` adds `@orchardlabs/graft-ui` to the new graft, and the starter `ui/src/Home.svelte` imports it, so a scaffolded graft is under AGPL-3.0-only as it stands. To use another license, remove the dependency from `package.json` and the import from `Home.svelte`. ## Next steps - [Review each field of the manifest](/grafts/build/manifest/) - [Add API routes and reach Orchard through doors](/grafts/build/server/) - [Add pages, navigation, tabs, and cards](/grafts/build/ui/) - [Add migrations and read Orchard's tables](/grafts/build/database/) - [Share your graft or list it in the Extension Marketplace](/grafts/build/publishing/) For an example, read the [announcements graft](https://github.com/hackclub/orchard/tree/main/grafts/announcements). It has a server module, UI, migrations, and settings. ## Related resources - [Graft UI slots](/reference/graft-slots/) - Every place in the dashboard a graft can add to. - [Graft API versions](/reference/graft-api/) - Doors, their members, and the capability each needs. - [Troubleshooting grafts](/grafts/troubleshooting/) - Find out why a graft did not load. --- # Write server code > Write an Orchard graft's API as a NestJS module, control who can call each route, and reach Orchard through versioned doors. Source: https://docs.orchard.hackclub.com/grafts/build/server/ To add API routes to a graft, write a NestJS module. The module is the default export of `server/src/index.ts`. Orchard mounts each controller in it under `/apiv1//`, including controllers in modules it imports. ```ts import { Controller, Get, Inject, Module, Param } from '@nestjs/common'; import { Auth, Doors, GraftUserId, type AuthDoor, type DbDoor } from '@orchardlabs/graft-sdk/server'; @Controller('notes') class NotesController { constructor( @Inject(Doors.db) private readonly db: DbDoor, @Inject(Doors.auth) private readonly auth: AuthDoor ) {} @Get(':orgId') @Auth() async list(@GraftUserId() userId: string, @Param('orgId') orgId: string) { await this.auth.requireOrgMember(orgId, userId); return (await this.db.query('SELECT * FROM notes WHERE org_id = $1', [orgId])).rows; } } @Module({ controllers: [NotesController] }) export default class NotesModule {} ``` ## Control who can call a route A route with no decorator is open to superadmins only. | Decorator | Route is open to | | --- | --- | | None | Superadmins only | | `@SuperAdmin()` | Superadmins only | | `@Auth()` | Anyone signed in. Check what they can see with `Doors.auth`. | | `@Public()` | Anyone. The route must also be listed in `public.routes` in `graft.json`. | | `@RequireScope('read' \| 'deploy' \| 'exec')` | API tokens need this scope. | `@GraftUserId()` gives you the signed-in user's ID. `graft pack` records each route and its access level. Orchard refuses to load a graft whose routes no longer match that record. ## Use doors A graft reaches Orchard through doors. Inject a door with `@Inject(Doors.)`. A door checks which graft injected it. If the door's capability is missing from `graft.json`, the graft does not boot, and the message names the capability. For each door's members, version, and capability, refer to the [graft API reference](/reference/graft-api/). | Door | Purpose | | --- | --- | | `context` | The graft's ID, version, manifest, schema, and API base. | | `auth` | Organization and project access checks, and the graft's own permissions with `can()` and `require()`. | | `users` | Basic profile data of other users. | | `db` | A connection pool to the graft's schema. | | `settings` | Values of the graft's settings sections. | | `secrets` | Encryption and decryption with Orchard's secret key. | | `storage` | Uploads to and deletions from the instance's object storage. | | `audit` | Audit log entries, under the graft's action names. | | `events` | Live events to an organization's open pages, and Orchard's event stream. | | `flags` | Feature flags. | | `http` | WebSocket endpoints, the HTTP server once it listens, and hostnames for preview domains. | | `kube` | The cluster client, leader election, and Engine shards that watch resources into Postgres. | | `apply` | Cluster changes on Orchard's retrying apply queue, and handlers for the graft's operations. | | `exec` | Terminals into the graft's workloads through Orchard's session engine. | | `projects` | Deployments and environments, and environment variable changes. Changes need the `projects.write` capability. | | `notifications` | Notification events, and notifications to a person. | | `rateLimit` | Rate limit buckets shared across replicas. | | `metrics` | Instant queries against the metrics store. | | `github` | GitHub tokens for a user, a repository, or an app installation, and issue comment webhooks. | ## Bundle dependencies Grafts bundle their own dependencies. `@nestjs/*`, `rxjs`, and `reflect-metadata` come from Orchard, so that there is one Nest instance. To leave another package out of the bundle, list it in `graft.config.mjs` under `server.external`. ## Add MCP tools 1. Add the `mcp` capability to `graft.json`. 2. Export a function from `mcp/src/index.ts`: ```ts import { defineMcp } from '@orchardlabs/graft-sdk/server'; export default defineMcp((server, client, { apiBase }) => { server.registerTool('notes_list', { description: 'List notes' }, async () => ({ content: [{ type: 'text', text: JSON.stringify(await client.get(`${apiBase}/notes`)) }] })); }); ``` Tools run in Orchard's [MCP server](/mcp/) and call the graft's API as the signed-in user. A tool's name must start with the graft's ID, with dashes turned into underscores, or be listed under `claims.mcpTools`. A connection only sees the tools its scope allows. A tool with `annotations: { readOnlyHint: true }` needs `read`, and any other tool needs `deploy`. If the tool calls a route that has `@RequireScope('exec')`, set `_meta: { 'orchard/scope': 'exec' }` in the tool config. > **Note** > > If a graft has both MCP tools and the `flags` capability, and the instance has PostHog configured, Orchard treats the graft as gated on a flag named after its ID. Accounts without that flag do not see the graft's tools. ## Gate a graft with a feature flag Use the `flags` door to limit a graft to some accounts. Check `configured` first, so that the graft stays open on instances without PostHog: ```ts if (this.flags.configured && !(await this.flags.isEnabled('notes', userId))) { throw new NotFoundException(); } ``` ## Related resources - [graft.json](/grafts/build/manifest/) - Declare capabilities, public routes, and claims. - [Use the database](/grafts/build/database/) - Add migrations and query through the `db` door. --- # Add UI > Add pages, navigation, tabs, and cards to Orchard's UI from a graft, using a Svelte island, slots, and the host object. Source: https://docs.orchard.hackclub.com/grafts/build/ui/ To add pages, navigation, tabs, and cards to the dashboard, add UI to a graft. A graft's UI is an island: a bundle with its own copy of Svelte. Orchard loads the bundle and gives it an empty element to draw in. Because the island does not share Orchard's build, a graft can use any library. ## Define what the graft adds `ui/src/client.ts` default-exports what the graft adds: ```ts import { mount, unmount } from 'svelte'; import { defineGraft } from '@orchardlabs/graft-sdk/client'; import Notes from './Notes.svelte'; import NotesCard from './NotesCard.svelte'; export default defineGraft({ slots: { 'nav.primary': [{ id: 'notes', label: 'Notes', href: '/notes' }], 'project.overview.cards': [ { id: 'recent', mount: (target, props, host) => { const app = mount(NotesCard, { target, props: { ...props, host } }); return () => unmount(app); } } ] }, screens: { home: (target, props, host) => { const app = mount(Notes, { target, props: { host } }); return () => unmount(app); } } }); ``` For each place a graft can add to, refer to the [slot reference](/reference/graft-slots/). ## Add a screen List each screen in `graft.json` under `ui.screens`, with its path and layout: | Layout | Behavior | | ------------ | ----------------------------------------- | | `shell` | Draws inside Orchard's sidebar and header. | | `fullscreen` | Takes the whole window. | A screen at `/admin/`, or below it, renders in the **Instance admin** area, and only superadmins reach it. Pair it with an `admin.nav` entry. Orchard ignores a screen under `/admin/` that uses another path. ## Use the host object Each mount function receives `host`, the graft's interface to Orchard's UI. | Member | Description | | --- | --- | | `host.graft` | The graft's `id`, `version`, `apiBase`, and `assetBase`. | | `host.api(path, init?)` | Returns JSON from the graft's API. Paths are relative to `/apiv1/`. `json` in `init` sends a body. | | `host.fetch(path, init?)` | Returns the raw response. | | `host.stores.user`, `.org`, `.theme`, `.route` | Svelte-compatible stores. Use `$user` in a component. | | `host.navigate(href, options?)` | Navigates on the client. | | `host.toast(message, tone?, options?)` | Shows one of Orchard's toasts. | | `host.confirm({ title, body, confirmLabel, danger })` | Shows Orchard's confirmation dialog, and resolves to a boolean. | | `host.onOrgEvent(handler)` | Receives live events for the current organization. | | `host.refreshSlots()` | Evaluates the `visible` functions of the graft's slot items again. | ## Match Orchard's styles `@orchardlabs/graft-ui` is Orchard's component kit, packaged for grafts. It includes components such as `Button`, `SectionCard`, `Field`, `Input`, `Select`, `Modal`, and `EmptyState`. > **Note** > > `@orchardlabs/graft-sdk` is MIT licensed, so a graft that only imports it can use any license. `@orchardlabs/graft-ui` is licensed under AGPL-3.0-only. A graft that imports `@orchardlabs/graft-ui` must be released under a license compatible with AGPL-3.0-only, and the AGPL's source-sharing terms apply to it. To use another license, build the graft's UI with `@orchardlabs/graft-sdk` and your own components. Orchard sets theme colors, fonts, and spacing as CSS variables on the page. You can use `var(--text-muted)` and `var(--bg-surface)` in a graft's own styles. A graft bundles its copy of the kit. A graft built against an older Orchard keeps that version's components until you rebuild it. Colors and fonts follow the instance. ## Errors Orchard wraps each mount. If a graft throws while mounting or updating, that element shows an error with a **Retry** button. The rest of the page keeps working. ## Related resources - [graft.json](/grafts/build/manifest/) - Declare screens and their layouts. - [Write server code](/grafts/build/server/) - Add the API routes that `host.api` calls. --- # Install grafts > Add, list, and remove Orchard grafts with orchardctl or Helm values, and set the trust policy that controls which grafts can load. Source: https://docs.orchard.hackclub.com/grafts/install/ To add a graft to your instance, install it with `orchardctl` or Helm values. The list of grafts is part of the instance's configuration: a `grafts` list in the Orchard chart values. `orchardctl graft` edits that list on hosts set up by the [installer](/start/install/). GitOps setups edit it in Git. In both cases, a change rolls Orchard out like [an upgrade](/operate/upgrades/). > **Caution** > > Only install grafts you trust. A graft runs with the same access as Orchard. `orchardctl` shows what a graft asks for before it installs anything. ## Install with orchardctl 1. Find a graft: ```sh sudo orchardctl graft search ``` 2. Review its versions, and which of them work with your instance: ```sh sudo orchardctl graft info announcements ``` 3. Add the graft: ```sh sudo orchardctl graft add announcements --apply ``` `add` selects the newest version that works with your Orchard, unless you give a version with `@`. It then runs these checks on the server: 1. It checks the download against its digest, and the signature against your [trust policy](#trust). 2. It checks the graft against your Orchard version, the doors it uses, and the grafts it depends on. 3. It lists the database migrations that would run. No graft SQL runs at this point. `orchardctl` then shows the graft's capabilities, the core tables it reads, its paths outside its own ID, and its routes open to anyone. It also checks that any CRDs the graft requires exist. A graft's migrations run with Orchard's database user. If a graft ships a Helm chart, `orchardctl` installs it with cluster-admin rights and asks you to type the graft's ID first. To accept a chart with `--yes`, add `--allow-chart`. Community grafts cannot ship a chart. After you confirm, Orchard rehearses the migrations inside a transaction and rolls them back. If that passes, `orchardctl` writes the graft into your values. `--apply` rolls Orchard out immediately. Without it, run `sudo orchardctl update` when you are ready. ### Commands | Command | Action | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `orchardctl graft search [term]` | Searches the Extension Marketplace and your taps. | | `orchardctl graft info ` | Shows a graft's tier, publisher, versions, and compatibility. | | `orchardctl graft add [@version]` | Installs from the Extension Marketplace. | | `orchardctl graft add ./file.graft` | Installs a file. Orchard stores it in its database, so this works offline and on clusters with several nodes. | | `orchardctl graft add https://.../x.graft` | Installs from an `https` address, pinned to the digest it had when you added it. | | `orchardctl graft list` | Shows what is installed, whether it is running, and recent server messages about grafts. | | `orchardctl graft upgrade [id]` | Moves to the newest compatible version. Refer to [Upgrade and roll back grafts](/grafts/upgrades/). | | `orchardctl graft rollback ` | Returns to the previous version and its data. | | `orchardctl graft remove ` | Uninstalls the graft. Its data stays. | | `orchardctl graft remove --purge --apply` | Uninstalls the graft and deletes its schema, stored files, and settings. | | `orchardctl graft pool [n\|default]` | Shows or sets the database connections the graft can open per pod. | | `orchardctl graft tap add\|list\|remove` | Manages [taps](#add-a-tap). | | `orchardctl graft trust [level]` | Shows or sets the [trust policy](#trust). | `add` and `upgrade` accept these flags: | Flag | Effect | | --------------------- | -------------------------------------------------------- | | `--yes` | Skips the confirmation prompt. | | `--dry-run` | Runs every check and changes nothing. | | `--apply` | Rolls Orchard out afterward. | | `--allow-third-party` | With `--yes`, accepts a graft that Orchard did not make. | | `--allow-chart` | With `--yes`, accepts a graft's Helm chart. | If a graft includes a cluster chart for CRDs or RBAC, `add` installs it as the Helm release `orchard-graft-`. `remove` leaves that release in place and prints the `helm uninstall` command. ## Install with Helm values Add an entry to your values. The graft's [Extension Marketplace](https://orchard.hackclub.com/extensions) page shows the entry to copy. ```yaml grafts: - id: announcements version: digest: sha256: graftSettings: trust: listed ``` `digest` is the SHA-256 of the `.graft` file. It is required, and Orchard does not install a graft whose bytes do not match. `source` is optional and defaults to the Extension Marketplace. Set it to an `https://` address to install from elsewhere. A graft with a cluster chart needs that chart installed as its own HelmRelease. ## Where grafts come from | Kind | Publisher | How Orchard identifies it | Label | | --------- | --------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------- | | Official | Orchard | Signed with Orchard's key | **Official** | | Community | Another author, listed in the Extension Marketplace | Signed with the author's key, from a listing that Orchard signed | **Community · by** the author | | Tap | Anyone, from a tap you added | Signed with the tap's key, which you trusted when you added the tap | **Tap:** its name | An Orchard maintainer reviews a community graft when it is first listed. Each new version passes automated checks, but no one reviews it by hand. Orchard does not check taps. ## Trust > **Warning** > > A graft that Orchard did not make runs inside Orchard with no sandbox. It can read your secrets and database, sign in as any user, and change the apps on your cluster. Orchard cannot limit what it does, and nobody at Orchard reviews its updates. Only install it if you would give its publisher full control of your server. > > Before it installs one, `orchardctl` asks you to type the graft's ID. With `--yes`, also pass `--allow-third-party`. Grafts listed in `grafts` in your Helm values skip this prompt. `graftSettings.trust` controls which grafts can load. To load only Orchard's own grafts, set it to `official`: | Policy | Loads | | ------------------ | --------------------------------------------------------------------------------- | | `official` | Only Orchard's own grafts | | `listed` (default) | Official and community grafts, and grafts signed by a key in `graftSettings.keys` | | `taps` | All of the above, and grafts from taps you added | | `any` | Unsigned grafts too. Anything in the grafts directory runs. | `signed` is an older name for `listed`, and it still works. To change the policy, run the following command: ```sh sudo orchardctl graft trust taps --apply ``` A publisher can also give you a public key, a short base64 string from [`graft keygen`](/grafts/build/publishing/#sign-a-graft). To trust grafts signed with it, run `sudo orchardctl config edit` and add the key to `graftSettings.keys`. The Extension Marketplace can revoke a version or delist a community graft. `orchardctl` does not offer or install a revoked version. An instance that has it refuses to load it on its next start. ## Add a tap A tap is a catalog of grafts in a folder on an `https` host. 1. Add the tap. The command shows the tap's signing key and asks you to confirm it. ```sh sudo orchardctl graft tap add acme https://grafts.example.com/orchard ``` 2. Allow taps in your trust policy: ```sh sudo orchardctl graft trust taps --apply ``` 3. Install a graft with the tap's name in front: ```sh sudo orchardctl graft add acme/notes --apply ``` Every graft from a tap must be signed with the tap's key. With Helm values: ```yaml graftSettings: trust: taps taps: - name: acme url: https://grafts.example.com/orchard key: grafts: - id: notes version: digest: sha256: tap: acme ``` An instance has one graft per ID, whatever its source. `orchardctl` refuses `acme/notes` if a `notes` graft from another source is installed. ## View installed grafts Go to **Instance admin** > **Grafts**. The page lists each graft with its status, signature, capabilities, core table reads, and routes, including routes open to anyone. A failed graft shows the phase it failed in and the reason. Settings that a graft adds appear in **Instance admin** > **Configuration**. ## Settings | Value | Environment variable | Default | | --------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `grafts` | `ORCHARD_GRAFTS` | None | | `graftSettings.trust` | `ORCHARD_GRAFT_TRUST` | `listed`. One of `official`, `listed`, `taps`, or `any`. | | `graftSettings.registrySignature` | `ORCHARD_REGISTRY_SIGNATURE` | `required`. Set `auto` to accept an unsigned revocation list from a registry you run yourself. | | `graftSettings.taps` | `ORCHARD_GRAFT_TAPS` | None. Each tap has a `name`, `url`, and `key`. | | `graftSettings.keys` | `ORCHARD_GRAFT_KEYS` | None | | `graftSettings.marketplaceUrl` | `ORCHARD_GRAFT_MARKETPLACE_URL` | `https://assets.orchard.my/registry` | | `graftSettings.strict` | `ORCHARD_GRAFTS_STRICT` | `false`. When true, a graft that fails stops the pod instead of being skipped. The rollout halts and the previous pods keep serving. | | `graftSettings.safeMode` | `ORCHARD_GRAFTS_SAFE_MODE` | `false`. When true, no grafts load. | | `graftSettings.pools` | `ORCHARD_GRAFT_POOLS` | None. Database connections per pod by graft ID, for example `{ greenhouse: 15 }`. | | | `ORCHARD_GRAFT_DB_POOL` | `3`. Database connections per pod for grafts that do not ask for a size. | ## Database connections Each graft opens its own pool of database connections on every server and worker pod. A graft asks for a size in its [`graft.json`](/grafts/build/manifest/). Greenhouse asks for 10. To change a graft's size, run the following command: ```sh sudo orchardctl graft pool greenhouse 15 --apply ``` To return to the size the graft asks for, use `default` instead of a number. Connections open when needed and close after about 10 seconds idle. Every pod can open its whole pool at once, and during an update the old and new server pods run side by side. Orchard compares this peak against the database's `max_connections` at boot and in **Instance admin** > **Grafts**: - Past 80% of usable connections, Orchard warns. - Past 100%, Orchard reports that the budget is exceeded. With `graftSettings.strict`, new pods refuse to start and the rollout halts. When the database runs out of connections, new requests fail until connections free up. Lower a pool or raise `max_connections`. ## Related resources - [Upgrade and roll back grafts](/grafts/upgrades/) - Move between versions and keep the graft's data. - [Troubleshooting grafts](/grafts/troubleshooting/) - Find out why a graft did not load. - [Run Greenhouse](/operate/greenhouse/) - Install and configure the largest first-party graft. --- # Grafts > Grafts are Orchard's extensions. A graft adds pages, API endpoints, database tables, MCP tools, and settings to an Orchard instance. Operators install grafts with orchardctl or Helm values. Source: https://docs.orchard.hackclub.com/grafts/overview/ A graft is an extension that adds features to an Orchard instance, so you can add what your team needs without forking Orchard and keeping the fork up to date. It can add pages, API endpoints, its own database tables, [Model Context Protocol (MCP) tools](/mcp/#choose-toolsets), instance settings, and cards or tabs on existing pages. You find grafts in the [Extension Marketplace](https://orchard.hackclub.com/extensions). You install them with [`orchardctl graft add`](/grafts/install/) or with Helm values, and Orchard rolls out the change like an upgrade. > **Caution** > > Only install grafts you trust. A graft runs inside Orchard with the same access as Orchard: your database, your users' data, and your cluster. Orchard checks signatures, versions, and declared requirements, and shows them to you before you install. These checks are not a sandbox. ## Get started - [Install grafts](/grafts/install/): Add, list, and remove grafts, and set your trust policy. - [Upgrade and roll back grafts](/grafts/upgrades/): Move between versions and keep your data. - [Troubleshooting grafts](/grafts/troubleshooting/): Find out why a graft did not load. - [Build a graft](/grafts/build/quickstart/): Scaffold, run, and sign your own graft. ## Kinds of graft | Kind | Publisher | Label in Orchard | | --------- | --------------------------------------------------- | ----------------------------- | | Official | Orchard | **Official** | | Community | Another author, listed in the Extension Marketplace | **Community · by** the author | | Tap | Anyone, from a catalog that you added | **Tap:** the tap's name | Your [trust policy](/grafts/install/#trust) controls which kinds can load. Orchard publishes these first-party grafts: - [Greenhouse](/greenhouse/) (`greenhouse`): Cloud machines with coding agents. - [The Grove](/run/grove/) (`forum`): A forum for the people on an instance. - [Announcements](/grafts/announcements/) (`announcements`): Notices on project and app pages. ## Parts of a graft | Part | Runs as | Location | | ------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------- | | Server module | A NestJS module loaded into the Orchard server | `/apiv1//...` | | UI | An island: a bundle with its own copy of Svelte, mounted in pages Orchard renders | `//...` and the [slots](/reference/graft-slots/) | | Migrations | SQL that Orchard runs in a transaction | The graft's own schema, `ext_` | | MCP tools | Tools registered in the MCP server | Named `_...`, or claimed by name | | Settings | Sections in **Instance admin** > **Configuration** | Stored as instance settings | | Cluster chart | An optional Helm chart for CRDs, namespaces, and RBAC | Its own Helm release, `orchard-graft-` | ## How grafts stay separate from Orchard - **Doors:** A graft reaches Orchard through versioned interfaces called doors. A stable door does not change shape. A change ships as a new version next to the old one. `orchardctl` refuses a graft that needs a door the instance does not have. For the list, refer to the [graft API reference](/reference/graft-api/). - **Islands:** A graft's UI carries its own Svelte and its own copy of Orchard's components, and draws in an element that Orchard gives it. Colors and fonts come from the shared theme. - **Claims:** A graft's names live under its ID, such as `/apiv1/`, `/`, and `.` events. A graft can ask for a name outside its ID with a [claim](/grafts/build/manifest/#claims). - **Data:** Each graft has its own Postgres schema. When the database user can create roles, the graft also has a role that can read only the core columns it declared. Removing a graft keeps its data until you purge it. - **Failure handling:** Orchard skips a graft that fails to load, migrate, or boot, and shows it as failed in **Instance admin** > **Grafts**. Orchard itself still starts. ## Related resources - [`orchardctl graft` reference](/operate/host-commands/#graft) - Every graft command on an installer host. - [Security and isolation](/operate/security/) - What Orchard isolates, and what a graft can reach. --- # Troubleshooting grafts > Fix common Orchard graft failures by symptom, including failed downloads, signature errors, version conflicts, and failed migrations, and recover an instance with safe mode. Source: https://docs.orchard.hackclub.com/grafts/troubleshooting/ Use this page to fix common failures with grafts. Each entry lists the symptom, the cause, and the fix. **Instance admin** > **Grafts** shows each graft's status. A failed graft shows **Failed during** a phase, and the reason. `sudo orchardctl graft list` shows the status too, with recent server messages about grafts. ## Failure phases | Phase | Meaning | Fix | | -------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `sync` | The download failed, the digest did not match, or the signature did not pass your trust policy. | Check `digest` in your values and your [trust policy](/grafts/install/#trust). | | `manifest` | `graft.json` is invalid. | Ask the publisher for a fixed version. | | `integrity` | A file does not match the signed file list, or the signature does not pass your trust policy. | Reinstall. Do not edit files in an installed graft. | | `compat` | The graft needs a different Orchard version, graft SDK, or door. | [Upgrade Orchard](/operate/upgrades/), or install a matching version of the graft. | | `dependencies` | A graft it needs is missing, failed, or the wrong version. | Install or fix the other graft first. | | `migrations` | Its database changes failed and were rolled back. | Read the error. It is usually a bug in the graft. | | `load` | Its server code threw an error while loading. | Contact the publisher. | | `routes` | Its routes do not match what it was packed with, or it opens a route to anyone without declaring it. | Contact the publisher, or reinstall if a file changed. | | `boot` | Orchard could not start with the graft, and started without it. | Read the reason. A common cause is a capability missing from `graft.json`. | ## digest mismatch ```text digest mismatch: expected 1a88f45b..., downloaded 7c2d91e0... ``` **Cause:** The file at the source is not the file your values pin. **Fix:** Check `digest` in your values. If the publisher changed the file at that address, ask for a new version. ## MANIFEST.sig does not verify against any trusted key ```text MANIFEST.sig does not verify against any trusted key ``` **Cause:** The graft is signed with a key that your instance does not trust. **Fix:** Add the publisher's key to `graftSettings.keys`, or install the graft from its listing or [tap](/grafts/install/#add-a-tap). ## graft is unsigned ```text graft is unsigned and the trust policy is "listed"; add its publisher key or set the policy to "any" ``` **Cause:** The graft has no signature. **Fix:** Ask the publisher for a signed version. Setting the policy to `any` lets any file in the grafts directory run. ## was revoked by the Extension Marketplace ```text notes 1.2.0 (sha256:1a88f45b...) was revoked by the Extension Marketplace; install another version ``` **Cause:** The Extension Marketplace revoked this version. **Fix:** Run `sudo orchardctl graft upgrade notes`, or remove the graft. ## needs Orchard ```text needs Orchard >=2.70.0 <3, this is 2.67.0 ``` **Cause:** This version of the graft does not support your Orchard version. **Fix:** Upgrade Orchard, or install a version of the graft that lists your Orchard version. `sudo orchardctl graft info ` shows which versions are compatible. ## migration was changed after it was applied ```text migration 0001_init was changed after it was applied (checksum mismatch); ship a new migration instead ``` **Cause:** A published graft version edited a migration that your database already ran. **Fix:** Contact the publisher. To return to the previous version, refer to [Roll back a graft](/grafts/upgrades/#roll-back-a-graft). ## A claim shows as taken **Cause:** In **Instance admin** > **Grafts**, `taken by` next to a [claim](/grafts/build/manifest/#claims) means another graft uses the name. **Fix:** No action is needed for the graft to work. It still serves its paths under `//`. ## A graft misbehaves or Orchard does not start With `graftSettings.strict` off, which is the default, Orchard skips a broken graft and starts without it. With `graftSettings.strict` on, a graft that fails stops the pod. To turn off every graft at once, run the following command: ```sh sudo orchardctl config set graftSettings.safeMode true --apply ``` Remove the failing graft, then set `graftSettings.safeMode` back to `false`. ## Still stuck? Collect the phase and reason from **Instance admin** > **Grafts**, and the output of `sudo orchardctl graft list`. Then contact the graft's publisher. Its details are on its [Extension Marketplace](https://orchard.hackclub.com/extensions) page. ## Related resources - [Upgrade and roll back grafts](/grafts/upgrades/) - Return to a version that worked. - [Troubleshooting Orchard](/operate/troubleshooting/) - Fix problems with Orchard itself. --- # Upgrade and roll back grafts > Upgrade an Orchard graft with a rehearsal and a snapshot, roll back to the previous version and its data, and follow a version range from Git. Source: https://docs.orchard.hackclub.com/grafts/upgrades/ Upgrading a graft can change its database schema, so `orchardctl` rehearses each upgrade and keeps a snapshot that lets you return to the previous version with its data. An upgrade or rollback changes only the graft's own schema, `ext_`. It does not change Orchard's data or the data of other grafts. ## Upgrade a graft Run the following command: ```sh sudo orchardctl graft upgrade announcements --apply ``` To upgrade all grafts, omit the ID. A graft that you installed from a file does not upgrade this way. Run `orchardctl graft add` with the newer file. The command does the following: 1. **Rehearsal:** It runs the new version's migrations against your live database, in a transaction that it rolls back. If they would fail, it shows the error and changes nothing. `--dry-run` stops here. 2. **Snapshot:** If the new version has pending migrations, it saves the graft's schema and migration history under `/etc/orchard/graft-snapshots//