Deployment

This guide covers deploying Orchard in a production environment.

Preparation

Before deploying, ensure you have:

A server meeting the system requirements
A domain name pointing to your server
TLS termination (a reverse proxy such as Caddy or nginx with Let's Encrypt)
PostgreSQL running and accessible

DNS Configuration

Create DNS records pointing to your server:

code

orchard.example.com.  A  203.0.113.10

If you want per-grove SSH subdomains, add a wildcard:

code

*.orchard.example.com.  A  203.0.113.10

TLS with a Reverse Proxy

The Orchard API server runs plain HTTP on port 8080. Use a reverse proxy to terminate TLS:

Caddy example (Caddyfile):

code

orchard.example.com {
  reverse_proxy localhost:8080
}

nginx example:

code

server {
  listen 443 ssl;
  server_name orchard.example.com;
 
  ssl_certificate     /etc/letsencrypt/live/orchard.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/orchard.example.com/privkey.pem;
 
  location / {
    proxy_pass http://localhost:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}

Production Configuration

Edit application.yml (or override via environment variables) before starting:

code

orchard:
  security:
    oauth2:
      enabled: true        # Always enable in production
  issuer-uri: https://your-idp.example.com/realms/orchard
 
  qemu:
    ssh-port-range-start: 49152
    ssh-port-range-end: 49999
    enable-kvm: true
    ssh-public-key: <your-public-key>

Health Checks

Monitor your deployment with the health endpoint:

code

curl https://orchard.example.com/api/health

Expected response:

code

{
  "status": "healthy",
  "name": "Orchard",
  "version": "0.3.0"
}

Check provider readiness (e.g. QEMU availability):

code

curl https://orchard.example.com/api/health/ready

Returns 200 when the configured seedling provider is available, 503 otherwise.

Updates

Pull the latest changes and restart:

code

git pull
./gradlew :trellis:bootRun

Docker Compose

Overview