Deployment Notes

This page follows the deployment flow in the repository README.md.

Quick Start

git clone https://github.com/rallisf1/hesperida.git
cd hesperida

cp .env.example .env

Self-hosted DB:
```
docker compose --profile aio up -d
```
External SurrealDB / SurrealDB SaaS:
```
docker compose --profile backend up -d
```

Open the dashboard at http://localhost:3000 for local access, or at the domain configured in your reverse proxy.

At startup, orchestrator handles tool images automatically:

NODE_ENV=development: builds local tool images
non-development: pulls matching published tool image tags and retags them for runtime

For all-in-one (aio) deployments:

docker compose --profile aio down
docker compose --profile aio pull
docker compose --profile aio up -d

For backend deployments, use the same flow but replace aio with backend where applicable.

If you use the bundled Caddy setup, add -f docker-compose-caddy.yaml to the down, pull, and up commands.

web and orchestrator are required in all active deployments.
db is required only when not using external SurrealDB.
apprise and pdf are part of backend profiles for notifications and PDF export.
docker-compose-caddy.yaml is an optional standalone Compose file for deployments that want bundled Caddy.
tools profile is optional for direct manual tool runs; those containers are not long-running services.

Most deployments should use their existing reverse proxy with docker-compose.yaml and proxy to the loopback dashboard port:

my.domain.com {
	reverse_proxy 127.0.0.1:3000
}

If you want the bundled Caddy container, edit the root Caddyfile and replace my.domain.com with your real hostname:

my.domain.com {
	reverse_proxy web:3000
}

Then set matching public URL/session values in .env:

DASHBOARD_URL=https://my.domain.com
SESSION_COOKIE_SECURE=true

Start the bundled Caddy stack with:

docker compose -f docker-compose-caddy.yaml --profile aio up -d

See Reverse Proxy for the full guide.

Start from .env.example and configure at least: