Self-Hosting

Orchard is designed to be self-hosted on your own infrastructure. This page covers system requirements and deployment options.

System Requirements

QEMU

Orchard's default VM provider uses QEMU to provision isolated VMs. Install on Ubuntu/Debian:

apt install qemu-system-x86 qemu-utils

KVM acceleration is enabled by default. Ensure your host supports hardware virtualization (/dev/kvm must exist).

Supported Architectures

• linux/amd64 — fully supported
• linux/arm64 — fully supported
• macOS/arm64 — supported via HVF acceleration (build from source required; no prebuilt binary yet)

Database

Orchard uses PostgreSQL for all persistent state. A Docker Compose file is included for running just the database:

docker compose up -d postgres

Back up the database regularly:

pg_dump -U orchard orchard > orchard-backup.sql

Running the Server

Option A: Download a release (recommended)

Download the latest server binary from the releases page:

# Linux amd64
curl -LO https://github.com/orchard-cde/orchard/releases/latest/download/orchard-server-linux-amd64.tar.gz
tar xzf orchard-server-linux-amd64.tar.gz
 
# Linux arm64
curl -LO https://github.com/orchard-cde/orchard/releases/latest/download/orchard-server-linux-arm64.tar.gz
tar xzf orchard-server-linux-arm64.tar.gz
 
./orchard-server

Option B: Build from source

git clone https://github.com/orchard-cde/orchard.git
cd orchard
./gradlew :trellis:bootRun

The API server starts on port 8080.

Fence (authentication) — required in production

The server above runs with authentication disabled by default (orchard.security.oauth2.enabled: false), which is fine for a quick local trial but is not a production configuration — anyone with API access can act as any cultivator. A real deployment always runs Fence, Orchard's own OAuth2/OIDC authorization server, alongside the core API. Download its JAR from the latest release:

curl -LO https://github.com/orchard-cde/orchard/releases/latest/download/fence.jar
java -jar fence.jar --server.port=7779

See the Deployment guide's Authentication (Fence) section for the full production setup (issuer URL, signing key persistence, upstream provider credentials) — treat it as required reading before going live, not optional hardening.

SSH gateway — required in production

Cultivators reach their groves through the SSH gateway rather than connecting to seedlings directly. It runs alongside Fence and the core API, on the same host as the core API when you use QEMU. Its JAR is published on the same release:

curl -LO https://github.com/orchard-cde/orchard/releases/latest/download/gateway.jar
java -jar gateway.jar

See the Deployment guide's SSH Gateway section for the client secret it shares with Fence, its internal seedling key, and firewall rules.

Network Requirements

• Port 8080 accessible to Trowel CLI users (API)
• Port 7779 accessible for Fence (authentication — required in production, see above)
• Port 2222 accessible for the SSH gateway (grove SSH connections — required in production, see above)
• SSH port range 49152–49999 used by QEMU seedlings (configurable via orchard.qemu.ssh-port-range-start/end in application.yml). In production only the local gateway connects to it, so firewall it from outside the host. Local/dev setups without the gateway connect to it directly.

Deployment Options

• Docker Compose — start PostgreSQL and the server
• Deployment guide — production configuration and health checks
• Cloud Providers — provision grove VMs on AWS EC2 and other cloud platforms

VM Providers

Orchard supports pluggable VM providers for grove provisioning. Set the active provider in application.yml:

orchard:
  nursery:
    provider: aws   # aws | qemu