Skip to content

Installation

Step-by-step guide to install OpenRemedy on a single Linux host using the openremedy-deployment Docker Compose stack.

This is the supported deployment shape today. Kubernetes / Helm charts are on the roadmap.

1. Requirements

Hardware

Resource Minimum Recommended
CPU 2 vCPU 4 vCPU
RAM 4 GB 8 GB
Disk 30 GB 60 GB
Architecture linux/amd64 (linux/arm64 for the daemon, but the platform images today ship amd64 only) —

The platform stack is the API + Next.js UI + Postgres + Redis + SeaweedFS (S3-compatible) + Caddy + Phoenix (LLM tracing). All of them run as containers on a single host.

Operating system

Any Linux distribution that runs Docker Engine 25+ and the Compose v2 plugin. Tested on:

  • Debian 12 / 13
  • Ubuntu 22.04 / 24.04

Software prerequisites

On the host, before you start:

# Docker Engine + Compose plugin (Debian/Ubuntu — adapt for RHEL/Alpine)
sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg \
    -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
   https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
    docker-buildx-plugin docker-compose-plugin

# Verify
docker --version          # Docker version 25.x or newer
docker compose version    # Docker Compose version v2.x or newer

# Plus general tools used in this guide
sudo apt-get install -y git openssl curl

Network

Port Protocol Direction Purpose
80 TCP inbound HTTP — Caddy redirects to HTTPS, also serves Let's Encrypt HTTP-01 challenges
443 TCP inbound HTTPS — UI, API, daemon endpoints, telemetry receiver, docs

The host needs to be reachable on the public internet for both ports so Let's Encrypt can issue TLS certificates automatically.

DNS

Point one A (or AAAA) record at the host for the dashboard / API:

Subdomain What lives there
app.example.com The dashboard + API + WebSocket + daemon endpoints

That's the only DNS record you need to operate. The .deb packages, the documentation site, and the telemetry receiver are services we run at dls.openremedy.io, docs.openremedy.io, and telemetry.openremedy.io — your install consumes them, it does not host them.

2. Clone the deployment repo

The deployment repo pins a tested combination of component versions. Always check out a specific tag for production:

cd /home/alberto
git clone --branch v0.1.2 https://github.com/OpenRemedy/openremedy-deployment.git
cd openremedy-deployment/docker

(Replace v0.1.2 with the latest tag from the repo's releases page.)

3. Generate secrets and configure .env

Copy the example file and fill in the required values:

cp .env.example .env
chmod 600 .env

Generate the three required secrets:

# JWT signing key — at least 32 characters
openssl rand -base64 48

# AES-256-GCM encryption key for stored SSH keys — exactly 64 hex chars
openssl rand -hex 32

# Postgres password — 24+ characters recommended
openssl rand -base64 24

Edit .env and paste each one into the corresponding variable:

# Required
SECRET_KEY=<paste from openssl rand -base64 48>
ENCRYPTION_KEY=<paste from openssl rand -hex 32>
POSTGRES_PASSWORD=<paste from openssl rand -base64 24>

# Required — public domain Caddy serves traffic on
DOMAIN=app.example.com
CORS_ORIGINS=https://app.example.com

# Pin the component versions — see openremedy-deployment/CHANGELOG.md
OREMEDY_BACKEND_TAG=0.1.2
OREMEDY_FRONTEND_TAG=0.1.2

# At least one LLM provider key — without one, the agent pipeline cannot run.
DEEPSEEK_API_KEY=<your key>
# OPENAI_API_KEY=<your key>
# ANTHROPIC_API_KEY=<your key>
# KIMI_API_KEY=<your key>

The above are the required variables. The platform supports 30+ optional variables for LLM tuning, SMTP, swarm engine, telemetry, integrations, and more — the Configuration reference is the full list with defaults and when to override each.

4. Authenticate Docker to GHCR

The OpenRemedy images are published to the GitHub Container Registry. While the project is in private testing, you need a personal access token with read:packages scope:

  1. Go to https://github.com/settings/tokens/new?scopes=read:packages.
  2. Create a token, copy it.
  3. On the host:
echo "<your-token>" | docker login ghcr.io -u <your-github-username> --password-stdin

(Once OpenRemedy is publicly released, the packages will be public and this step disappears.)

5. Pull images and start the stack

docker compose --env-file .env pull
docker compose --env-file .env up -d

This pulls every image, starts every container, and waits for the health checks to pass. Caddy will request Let's Encrypt certificates on the first request to each domain — make sure DNS resolves before the first hit.

6. Run database migrations

The first run needs the schema:

docker compose --env-file .env exec -T \
    -e OREMEDY_DB_URL_SYNC="postgresql://openremedy:$(grep ^POSTGRES_PASSWORD= .env | cut -d= -f2-)@postgres:5432/openremedy" \
    api alembic upgrade heads

You should see Alembic apply each migration. On subsequent upgrades to new tags, run the same command — it's idempotent.

7. Verify

Three checks confirm everything came up:

# Backend health
curl -fsS https://app.example.com/health
# → {"status":"ok","version":"v0.1.2"}

# Backend version provenance
curl -fsS https://app.example.com/api/v1/version
# → {"component":"openremedy-backend","version":"v0.1.2","git_sha":"...","built_at":"..."}

# Container status
docker compose --env-file .env ps
# All containers in "Up (healthy)" or "Up" state

Open https://app.example.com/ in a browser. You should see the login screen. The footer at the bottom of the sidebar shows the running version of both the backend and the UI.

8. Create the first tenant

The first user registers as the initial tenant owner:

  1. Navigate to https://app.example.com/welcome and follow the prompts.
  2. Choose a tenant name (the slug is derived automatically).
  3. Sign up with your email and a strong password.
  4. You're now the owner of that tenant. Invite teammates from Settings → Users.

9. Install the daemon on a managed server

To monitor a Linux server, install the openremedy-client daemon on that server. The bootstrap script makes this a two-line install:

# On the server you want to monitor (Debian/Ubuntu only for the .deb;
# RHEL packages are not yet shipped):
curl -fsSL https://dls.openremedy.io/openremedy-repo.deb -o /tmp/openremedy-repo.deb
sudo dpkg -i /tmp/openremedy-repo.deb
sudo apt update && sudo apt install -y openremedy-client

After install, register the host with the platform:

sudo openremedy-client --init \
    --platform-url https://app.example.com \
    --token <SERVER_TOKEN_FROM_DASHBOARD>
sudo systemctl enable --now openremedy-client

Generate the SERVER_TOKEN from Servers → Add server in the dashboard.

10. Smoke test: trigger an incident

In the dashboard, go to Incidents → New manual incident, pick the server you just registered, choose port_unavailable as the type, and submit. Within a minute or two you should see the agent pipeline run through triage → diagnose → execute → review.

Upgrading

When a new release of openremedy-deployment ships:

cd /home/alberto/openremedy-deployment
git fetch --tags
git checkout v<new-tag>
cd docker
docker compose --env-file .env pull
docker compose --env-file .env up -d
docker compose --env-file .env exec -T api alembic upgrade heads

The deployment repo's CHANGELOG.md documents which component versions each release pins.

Troubleshooting

  • docker compose up complains about missing required vars — the required env vars (SECRET_KEY, ENCRYPTION_KEY, POSTGRES_PASSWORD) must all be non-empty in .env. Run grep ^SECRET_KEY= .env to confirm.
  • Caddy can't issue a certificate — DNS hasn't propagated, or port 80/443 isn't reachable from the public internet. Check docker logs openremedy-caddy-1.
  • The dashboard loads but /health returns 502 — the API container hasn't finished starting. Wait 30 seconds; if it persists, docker logs openremedy-api-1.
  • Daemon refuses to register — the SERVER_TOKEN is single-use; if you regenerate the same server in the dashboard, you need a fresh token. Edit /etc/openremedy-client/config.json on the host and restart the service.

What's next

  • Server modes — pick the right live / shadow / audit posture for each managed server.
  • Security — review the auth, encryption, and gating model before going to production.
  • Integrations — wire up your existing alerting stack (Prometheus, Grafana, etc.) via webhooks.
  • Privacy — review what telemetry is sent and how to opt out if needed.