adoe
Book a technical demo

Getting started

Run your own adoe server with Docker Compose. This guide takes you from a fresh copy of the code to a server that answers health checks and receives alerts.

Using hosted adoe? You do not need to install anything. Sign in at app.adoe.ai and follow the onboarding steps. Then read Integration setup.

Prerequisites

  • Docker and Docker Compose. Docker Compose starts several containers from one file. For local development, you can use Python 3.11 and PostgreSQL 16 instead.
  • An Anthropic API key. adoe uses Claude, Anthropic's AI model, to choose SOPs and investigate alerts.
  • Credentials for the monitoring and notification tools you want to connect. You can add most of these later in the dashboard.

1. Get the code and configure it

Clone the repository. TODO(owner): repository URL or remove self-host instructions

Then copy the environment template and edit it:

# Copy the environment template
cp .env.example .env

# Set your values (see the table below)
vim .env

2. Environment variables

adoe reads all of its configuration from environment variables. Docker Compose loads them from .env. These are the ones most people need:

VariableWhat it doesRequired
ENVIRONMENTThe deployment environment. Any value except development, dev, local, test or testing turns on the startup security checks for the next two variables.No. Default development
ENCRYPTION_KEYA Fernet key (a symmetric encryption key) that encrypts the integration credentials adoe stores.Yes, outside development. adoe will not start without it. You also need it in development to save credentials.
JWT_SECRET_KEYThe secret that signs login tokens for the dashboard and the API.Yes, outside development. adoe will not start with the default value.
DATABASE_URLThe PostgreSQL connection string. Docker Compose sets it for you.For the local Python setup
ANTHROPIC_API_KEYYour Claude API key, used to choose SOPs and investigate alerts.Yes
GITHUB_TOKENA GitHub token for GitHub Actions runbooks and code search.For GitHub Actions
GITHUB_ORGThe GitHub organization adoe uses when a repository name has no owner.For GitHub Actions
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_REGION		AWS credentials for runbooks that use AWS Systems Manager (SSM).For AWS SSM
SLACK_WEBHOOK_URLA fallback Slack incoming webhook. You can also connect Slack in the dashboard.No
DRY_RUNWhen true, adoe logs each runbook step instead of running it.No. Default false
CONFIDENCE_THRESHOLDThe lowest confidence at which adoe recommends an SOP. Below it, adoe escalates to a person. Running an SOP automatically uses each SOP's own threshold instead.No. Default 0.8

To create the two secrets:

# ENCRYPTION_KEY (needs the Python cryptography package)
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

# JWT_SECRET_KEY
openssl rand -hex 32

Tip: start with DRY_RUN=true. adoe then logs what it would do and changes nothing. Turn it off when you trust your SOPs.

.env.example lists every variable. Its SENSU_WEBHOOK_TOKEN, SPLUNK_WEBHOOK_TOKEN and PAGERDUTY_WEBHOOK_SECRET lines are not used. Webhook tokens come from the dashboard (step 5).

3. Run with Docker Compose

# Start the database, the API server and the dashboard
docker compose up -d

# Follow the API server logs
docker compose logs -f app

# Check that the server is healthy
curl http://localhost:8000/health

Compose starts three services:

  • db: PostgreSQL 16 on port 5432.
  • app: the API server on port 8000. On first start it creates its database tables.
  • dashboard: the web app on port 3000. It forwards API and webhook requests to app.

A healthy server answers /health with "status": "healthy". If it cannot reach the database, the status is "degraded".

4. Create your admin account

Open http://localhost:3000. On the first visit, the dashboard shows a setup screen. It creates your organization and its first admin account. This first account is also a superadmin, which means it can change platform settings for every organization.

Two settings start in a safe state:

  • Execution mode starts as off. adoe investigates, recommends and escalates, but runs nothing. A superadmin changes the mode on the Superadmin page.
  • The plan starts as free. AI processes the first 50 alerts. Later alerts are still recorded, without AI. A superadmin can change the plan on the same page.
ModeWhat adoe may do
offNothing runs. adoe observes, recommends and escalates. This is the default.
shadowNothing runs, but adoe records what it would have run.
approveAn action runs only after a person approves it. SOPs never run on their own.
autoSOPs with auto_execute: true can run on their own. Every other check still applies, including DRY_RUN.

5. Point your tools at adoe

A webhook is an HTTP request that a tool sends when something happens. Each monitoring tool sends its alerts to its own webhook URL. The URL ends with a token that identifies and authenticates your organization:

POST http://your-host:8000/webhooks/{source}/{token}

Generate the token on the Integrations page, on the Webhooks tab. Then copy the full URL from there.

SourceWebhook path
Sensu/webhooks/sensu/{token}
Splunk/webhooks/splunk/{token}
PagerDuty/webhooks/pagerduty/{token}
Grafana/webhooks/grafana/{token}
Uptime.com/webhooks/uptime-com/{token}
Railway/webhooks/railway/{token}

The Integration setup guide covers each tool and the fields adoe reads from it.

Local Python setup

To run the API server directly instead of in a container:

# Create a virtual environment
python3.11 -m venv venv
source venv/bin/activate

# Install the app and test dependencies
pip install -r requirements-dev.txt

# Start only PostgreSQL from the Compose file
docker compose up -d db

# Start the API server with hot reload
uvicorn src.main:app --reload --port 8000

The server creates its database tables on first start. TODO(owner): document the upgrade path for an existing database (Alembic migrations)

The tests need their own, disposable database. The test run deletes and recreates its tables.

# Create the test database once
docker compose exec db createdb -U l1agent l1agent_test

# Run the tests
export TEST_DATABASE_URL=postgresql+asyncpg://l1agent:l1agent@localhost:5432/l1agent_test
pytest tests/ -v

Next steps