From 7ff816a43f3ae114be60dfab9fab46ef57b837ef Mon Sep 17 00:00:00 2001 From: Dipesh Babu Date: Thu, 19 Nov 2026 19:54:26 -0500 Subject: [PATCH] Add cloud deployment: published image, HTTPS stack and guide Releases now push the validated image to ghcr.io//agentloop with version and latest tags after checking it reports the release version as a non-root user. deploy/ provides a production Compose stack for one Linux server: Postgres, the API, the dashboard behind a Caddy login and automatic HTTPS, publishing only ports 80 and 443. A new CI job runs that stack over HTTPS and checks API key use, the HTTP redirect, the upload limit, the dashboard login and that internal ports stay unpublished. docs/CLOUD_DEPLOY.md covers single-server and managed platforms. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 117 +++++++++++++++++++ .github/workflows/release.yml | 46 ++++++++ CHANGELOG.md | 9 ++ Dockerfile | 5 + README.md | 19 ++++ deploy/.env.example | 26 +++++ deploy/Caddyfile | 31 +++++ deploy/docker-compose.yml | 119 ++++++++++++++++++++ docs/CLOUD_DEPLOY.md | 205 ++++++++++++++++++++++++++++++++++ docs/PRODUCTION.md | 7 +- docs/RELEASING.md | 15 +++ mkdocs.yml | 1 + 12 files changed, 599 insertions(+), 1 deletion(-) create mode 100644 deploy/.env.example create mode 100644 deploy/Caddyfile create mode 100644 deploy/docker-compose.yml create mode 100644 docs/CLOUD_DEPLOY.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e891470..32c000e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -592,3 +592,120 @@ jobs: - name: Stop deployment stack if: always() run: docker compose down --volumes --remove-orphans + + deploy-stack: + name: Production deploy stack with HTTPS + runs-on: ubuntu-latest + env: + COMPOSE_FILE: deploy/docker-compose.yml + + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Build the image the stack deploys + shell: bash + run: | + test "$(grep -c '^FROM python:' Dockerfile)" -eq 1 + tag="$(sed -n 's|^FROM python:\([^ ]*\).*|\1|p' Dockerfile)" + base="$(.github/scripts/pull-official-image.sh "python:$tag")" + mirror_file="$RUNNER_TEMP/Dockerfile.deploy" + sed "s|^FROM python:$tag|FROM $base|" Dockerfile > "$mirror_file" + docker build --pull=false --file "$mirror_file" --tag agentloop:local . + + - name: Pull Postgres and Caddy through the mirror fallback + shell: bash + run: | + echo "POSTGRES_IMAGE=$(.github/scripts/pull-official-image.sh postgres:16-alpine)" >> "$GITHUB_ENV" + echo "CADDY_IMAGE=$(.github/scripts/pull-official-image.sh caddy:2)" >> "$GITHUB_ENV" + + - name: Configure synthetic production settings + shell: bash + run: | + dashboard_password="dash-$(openssl rand -hex 16)" + admin_key="ci-admin-$(openssl rand -hex 24)" + db_password="db-$(openssl rand -hex 16)" + echo "::add-mask::$dashboard_password" + echo "::add-mask::$admin_key" + echo "::add-mask::$db_password" + hash="$(docker run --rm "$CADDY_IMAGE" caddy hash-password --plaintext "$dashboard_password")" + { + echo "AGENTLOOP_IMAGE=agentloop:local" + echo "AGENTLOOP_API_DOMAIN=api.localhost" + echo "AGENTLOOP_DASHBOARD_DOMAIN=dashboard.localhost" + echo "AGENTLOOP_ADMIN_API_KEY=$admin_key" + echo "AGENTLOOP_DASHBOARD_USER=operator" + echo "AGENTLOOP_DASHBOARD_PASSWORD_HASH='$hash'" + echo "POSTGRES_PASSWORD=$db_password" + echo "POSTGRES_IMAGE=$POSTGRES_IMAGE" + echo "CADDY_IMAGE=$CADDY_IMAGE" + } > deploy/.env + echo "DASHBOARD_PASSWORD=$dashboard_password" >> "$GITHUB_ENV" + echo "AGENTLOOP_ADMIN_API_KEY=$admin_key" >> "$GITHUB_ENV" + echo "127.0.0.1 api.localhost dashboard.localhost" | sudo tee -a /etc/hosts + + - name: Validate production Compose configuration without rendering secrets + run: docker compose config --quiet + + - name: Start production stack + run: docker compose up --detach + + - name: Wait for HTTPS through Caddy + shell: bash + run: | + for attempt in $(seq 1 60); do + if docker compose exec -T caddy cat /data/caddy/pki/authorities/local/root.crt > caddy-root.crt 2>/dev/null \ + && curl --fail --silent --show-error --cacert caddy-root.crt https://api.localhost/readyz > /dev/null; then + exit 0 + fi + sleep 3 + done + echo "The API did not become ready over HTTPS" >&2 + exit 1 + + - name: Verify the API over HTTPS + shell: bash + run: | + SSL_CERT_FILE="$PWD/caddy-root.crt" AGENTLOOP_API_URL=https://api.localhost python3 scripts/smoke_api.py + status="$(curl --silent --output /dev/null --write-out '%{http_code}' http://api.localhost/v1/health)" + test "$status" = 308 + head -c 17000000 /dev/zero | tr '\0' 'a' > oversized.json + status="$(curl --silent --output /dev/null --write-out '%{http_code}' --cacert caddy-root.crt \ + --header 'Content-Type: application/json' --data-binary @oversized.json https://api.localhost/v1/traces)" + test "$status" = 413 + + - name: Verify the dashboard requires a login + shell: bash + run: | + status="$(curl --silent --output /dev/null --write-out '%{http_code}' --cacert caddy-root.crt https://dashboard.localhost/)" + test "$status" = 401 + status="$(curl --silent --output /dev/null --write-out '%{http_code}' --cacert caddy-root.crt \ + --user "operator:wrong-password" https://dashboard.localhost/)" + test "$status" = 401 + for attempt in $(seq 1 40); do + if curl --fail --silent --output /dev/null --cacert caddy-root.crt \ + --user "operator:$DASHBOARD_PASSWORD" https://dashboard.localhost/_stcore/health; then + break + fi + sleep 3 + done + curl --fail --silent --output /dev/null --cacert caddy-root.crt \ + --user "operator:$DASHBOARD_PASSWORD" https://dashboard.localhost/ + + - name: Verify only the proxy is published + shell: bash + run: | + for port in 8000 8501 5432; do + if curl --silent --max-time 3 "http://127.0.0.1:$port/" > /dev/null; then + echo "Port $port must not be published on the host" >&2 + exit 1 + fi + done + + - name: Show container logs on failure + if: failure() + run: docker compose logs --no-color --tail=200 + + - name: Stop production stack + if: always() + run: docker compose down --volumes --remove-orphans diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 93af6ad..792b42b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -78,6 +78,52 @@ jobs: - name: Publish distribution uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3 + publish-image: + name: Publish container image + needs: [guard, validate] + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Build image from the validated tag + shell: bash + run: | + version="${GITHUB_REF_NAME#v}" + image="ghcr.io/${GITHUB_REPOSITORY_OWNER,,}/agentloop" + test "$(grep -c '^FROM python:' Dockerfile)" -eq 1 + tag="$(sed -n 's|^FROM python:\([^ ]*\).*|\1|p' Dockerfile)" + base="$(.github/scripts/pull-official-image.sh "python:$tag")" + mirror_file="$RUNNER_TEMP/Dockerfile.release" + sed "s|^FROM python:$tag|FROM $base|" Dockerfile > "$mirror_file" + docker build --pull=false --file "$mirror_file" \ + --label "org.opencontainers.image.version=$version" \ + --label "org.opencontainers.image.revision=$GITHUB_SHA" \ + --tag "$image:$version" --tag "$image:latest" . + echo "IMAGE=$image" >> "$GITHUB_ENV" + echo "VERSION=$version" >> "$GITHUB_ENV" + + - name: Check the image runs the released version + shell: bash + run: | + actual="$(docker run --rm "$IMAGE:$VERSION" python -c 'import agentloop; print(agentloop.__version__)')" + test "$actual" = "$VERSION" + docker run --rm "$IMAGE:$VERSION" sh -c 'test "$(id -u)" -ne 0' + + - name: Push to GitHub Container Registry + env: + GH_TOKEN: ${{ github.token }} + shell: bash + run: | + printf '%s' "$GH_TOKEN" | docker login ghcr.io --username "$GITHUB_ACTOR" --password-stdin + docker push "$IMAGE:$VERSION" + docker push "$IMAGE:latest" + docker logout ghcr.io + publish-github: name: Publish GitHub release needs: [guard, validate] diff --git a/CHANGELOG.md b/CHANGELOG.md index 8fdfe9f..ce79968 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,15 @@ trace, study, receipt, API and database schema versions. ### Added +- Cloud deployment. Releases publish a container image to + `ghcr.io/dipeshbabu/agentloop` (version and `latest` tags), built from the + validated tag and checked to report the release version as a non-root user. + `deploy/` adds a production Compose stack for one Linux server: Postgres, the + API, the dashboard behind a login, and Caddy with automatic HTTPS, publishing + only ports 80 and 443. CI runs the stack over HTTPS and checks API key use, + HTTPS redirects, the upload limit, the dashboard login and unpublished + internal ports. `docs/CLOUD_DEPLOY.md` covers single-server and managed + platform deployments. - `agentloop improve init --language node` generates a Node.js adapter (`agentloop_runner.mjs`) for the guided workflow. It imports an agent from a relative `.mjs`, `.js` or `.cjs` module, calls it as `answer(input, trace)` diff --git a/Dockerfile b/Dockerfile index 8599c6b..737c954 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,10 @@ FROM python:3.15-slim +LABEL org.opencontainers.image.title="AgentLoop" \ + org.opencontainers.image.description="AgentLoop API and dashboard for agent traces and reports" \ + org.opencontainers.image.source="https://github.com/dipeshbabu/agentloop" \ + org.opencontainers.image.licenses="Apache-2.0" + COPY --from=ghcr.io/astral-sh/uv:0.13.7 /uv /uvx /bin/ ENV PYTHONDONTWRITEBYTECODE=1 \ diff --git a/README.md b/README.md index 2db2d8d..7d45a33 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ Trace your code · Compare runs · Integrations · + Deploy · Guide

@@ -409,6 +410,24 @@ code changes. +## Deploy to the cloud + +Run a shared AgentLoop server for your team on any cloud. From 0.2.7 each release +publishes a container image, `ghcr.io/dipeshbabu/agentloop`, and `deploy/` +contains a production stack for one Linux server: Postgres, the API, the +dashboard behind a login, and Caddy for automatic HTTPS. Only ports 80 and 443 +are exposed. + +```bash +cp deploy/.env.example deploy/.env # set the image, domains and secrets +docker compose -f deploy/docker-compose.yml up --detach +``` + +CI runs this exact stack over HTTPS on every change. The +[cloud deployment guide](https://dipeshbabu.github.io/agentloop/CLOUD_DEPLOY/) +covers server setup, API keys, upgrades, backups, and managed platforms such as +Cloud Run, App Runner, ECS and Azure Container Apps. + ## Dashboard and persistence From a [source checkout](#source-checkout), load the synthetic example and start diff --git a/deploy/.env.example b/deploy/.env.example new file mode 100644 index 0000000..8ddac02 --- /dev/null +++ b/deploy/.env.example @@ -0,0 +1,26 @@ +# Copy to deploy/.env and replace every placeholder before starting the stack. +# Keep deploy/.env out of version control; it holds production secrets. + +# Container image. Pin an exact release instead of "latest". +AGENTLOOP_IMAGE=ghcr.io/dipeshbabu/agentloop:0.2.7 + +# Public hostnames. Point both DNS records (A/AAAA) at this host first. +AGENTLOOP_API_DOMAIN=agentloop-api.example.com +AGENTLOOP_DASHBOARD_DOMAIN=agentloop.example.com + +# Admin secret for creating project API keys. Generate with: openssl rand -hex 32 +AGENTLOOP_ADMIN_API_KEY=replace-with-a-long-random-admin-secret + +# Dashboard login. Create the bcrypt hash with: +# docker run --rm caddy:2 caddy hash-password --plaintext 'your-password' +# Keep the single quotes so Compose does not expand the $ characters in the hash. +AGENTLOOP_DASHBOARD_USER=admin +AGENTLOOP_DASHBOARD_PASSWORD_HASH='replace-with-a-bcrypt-hash' + +# Database. Mounted as a Compose secret; never embedded in a URL. +POSTGRES_DB=agentloop +POSTGRES_USER=agentloop +POSTGRES_PASSWORD=replace-with-a-long-random-db-password + +# Largest trace upload the proxy accepts. +AGENTLOOP_MAX_UPLOAD=16MB diff --git a/deploy/Caddyfile b/deploy/Caddyfile new file mode 100644 index 0000000..012fa75 --- /dev/null +++ b/deploy/Caddyfile @@ -0,0 +1,31 @@ +# HTTPS reverse proxy for the AgentLoop production stack. +# Caddy obtains and renews certificates for both domains automatically once +# their DNS records point at this host and ports 80 and 443 are reachable. + +{$AGENTLOOP_API_DOMAIN} { + encode zstd gzip + request_body { + max_size {$AGENTLOOP_MAX_UPLOAD} + } + header { + Strict-Transport-Security "max-age=31536000" + X-Content-Type-Options "nosniff" + -Server + } + reverse_proxy api:8000 +} + +# The dashboard has no login of its own, so Caddy requires one. +{$AGENTLOOP_DASHBOARD_DOMAIN} { + encode zstd gzip + basic_auth { + {$AGENTLOOP_DASHBOARD_USER} {$AGENTLOOP_DASHBOARD_PASSWORD_HASH} + } + header { + Strict-Transport-Security "max-age=31536000" + X-Content-Type-Options "nosniff" + X-Frame-Options "DENY" + -Server + } + reverse_proxy dashboard:8501 +} diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml new file mode 100644 index 0000000..da1156f --- /dev/null +++ b/deploy/docker-compose.yml @@ -0,0 +1,119 @@ +# Production AgentLoop stack for one Linux host on any cloud. +# +# Caddy terminates HTTPS with automatically issued certificates, serves the API +# on AGENTLOOP_API_DOMAIN and the dashboard behind a login on +# AGENTLOOP_DASHBOARD_DOMAIN. Only ports 80 and 443 are published; the API, +# dashboard and Postgres stay on the private Compose network. +# +# cp deploy/.env.example deploy/.env # then replace every placeholder +# docker compose -f deploy/docker-compose.yml up --detach +# +# See docs/CLOUD_DEPLOY.md. +name: agentloop + +services: + db: + image: ${POSTGRES_IMAGE:-postgres:16-alpine} + restart: unless-stopped + environment: + POSTGRES_DB: ${POSTGRES_DB:-agentloop} + POSTGRES_USER: ${POSTGRES_USER:-agentloop} + POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password + healthcheck: + test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-agentloop} -d ${POSTGRES_DB:-agentloop}"] + interval: 5s + timeout: 5s + retries: 20 + volumes: + - postgres_data:/var/lib/postgresql/data + secrets: + - postgres_password + + api: + image: ${AGENTLOOP_IMAGE:?Set AGENTLOOP_IMAGE in deploy/.env, for example ghcr.io/dipeshbabu/agentloop:0.2.7} + restart: unless-stopped + environment: + AGENTLOOP_STORE_BACKEND: postgres + PGHOST: db + PGPORT: "5432" + PGDATABASE: ${POSTGRES_DB:-agentloop} + PGUSER: ${POSTGRES_USER:-agentloop} + AGENTLOOP_POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password + AGENTLOOP_REQUIRE_API_KEY: "true" + AGENTLOOP_ADMIN_API_KEY: ${AGENTLOOP_ADMIN_API_KEY:?Set AGENTLOOP_ADMIN_API_KEY in deploy/.env} + AGENTLOOP_CORS_ORIGINS: https://${AGENTLOOP_DASHBOARD_DOMAIN:?Set AGENTLOOP_DASHBOARD_DOMAIN in deploy/.env} + depends_on: + db: + condition: service_healthy + secrets: + - postgres_password + healthcheck: + test: + [ + "CMD", + "python", + "-c", + "import json, urllib.request; assert json.load(urllib.request.urlopen('http://127.0.0.1:8000/readyz'))['status'] == 'ready'", + ] + interval: 10s + timeout: 5s + retries: 12 + + dashboard: + image: ${AGENTLOOP_IMAGE} + restart: unless-stopped + command: + [ + "streamlit", + "run", + "dashboard/app.py", + "--server.address=0.0.0.0", + "--server.port=8501", + "--server.headless=true", + "--browser.gatherUsageStats=false", + ] + environment: + AGENTLOOP_STORE_BACKEND: postgres + PGHOST: db + PGPORT: "5432" + PGDATABASE: ${POSTGRES_DB:-agentloop} + PGUSER: ${POSTGRES_USER:-agentloop} + AGENTLOOP_POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password + AGENTLOOP_API_URL: http://api:8000 + depends_on: + api: + condition: service_healthy + secrets: + - postgres_password + + caddy: + image: ${CADDY_IMAGE:-caddy:2} + restart: unless-stopped + ports: + - "80:80" + - "443:443" + - "443:443/udp" + environment: + AGENTLOOP_API_DOMAIN: ${AGENTLOOP_API_DOMAIN:?Set AGENTLOOP_API_DOMAIN in deploy/.env} + AGENTLOOP_DASHBOARD_DOMAIN: ${AGENTLOOP_DASHBOARD_DOMAIN} + AGENTLOOP_DASHBOARD_USER: ${AGENTLOOP_DASHBOARD_USER:?Set AGENTLOOP_DASHBOARD_USER in deploy/.env} + AGENTLOOP_DASHBOARD_PASSWORD_HASH: ${AGENTLOOP_DASHBOARD_PASSWORD_HASH:?Set AGENTLOOP_DASHBOARD_PASSWORD_HASH in deploy/.env} + AGENTLOOP_MAX_UPLOAD: ${AGENTLOOP_MAX_UPLOAD:-16MB} + volumes: + - ./Caddyfile:/etc/caddy/Caddyfile:ro + - caddy_data:/data + - caddy_config:/config + depends_on: + api: + condition: service_healthy + dashboard: + condition: service_started + +volumes: + postgres_data: + caddy_data: + caddy_config: + +secrets: + postgres_password: + environment: POSTGRES_PASSWORD diff --git a/docs/CLOUD_DEPLOY.md b/docs/CLOUD_DEPLOY.md new file mode 100644 index 0000000..7ddf3ac --- /dev/null +++ b/docs/CLOUD_DEPLOY.md @@ -0,0 +1,205 @@ +# Deploy to the cloud + +A cloud deployment gives a team one shared AgentLoop server. Developers and CI +upload traces to it with the Python or TypeScript client, and everyone reviews +the same traces, findings and reports. The CLI, SDKs and guided workflow keep +running where your agents run; only the shared server moves to the cloud. + +The server has three parts, all started from one container image: + +| Part | What it does | Port inside the stack | +| --- | --- | --- | +| API | Stores traces and serves reports under `/v1`, with project API keys | 8000 | +| Dashboard | Streamlit console for traces, findings and comparisons | 8501 | +| Postgres | Shared storage; schema migrations run automatically on startup | 5432 | + +## Container image + +From AgentLoop 0.2.7, every release publishes an image to GitHub Container +Registry, built from the validated release tag: + +```bash +docker pull ghcr.io/dipeshbabu/agentloop:0.2.7 +``` + +The image runs as a non-root user. Its default command starts the API on port +8000; the dashboard uses the same image with a `streamlit run dashboard/app.py` +command. Images are built for `linux/amd64`. Pin an exact version in +deployments; `latest` follows the newest release. + +## Option 1: one server on any cloud + +This is the recommended starting point. It works on any Linux virtual machine, +such as an AWS EC2 instance, a Google Compute Engine VM, an Azure VM or a +DigitalOcean droplet, and it is the setup CI runs on every change. + +The `deploy/` directory contains the stack: + +- `deploy/docker-compose.yml` starts Postgres, the API, the dashboard and + [Caddy](https://caddyserver.com/), which obtains and renews HTTPS + certificates automatically; +- `deploy/Caddyfile` serves the API on one hostname and the dashboard on + another, with a login in front of the dashboard; +- `deploy/.env.example` lists every setting. + +Only ports 80 and 443 are published. The API, dashboard and database are +reachable only through Caddy or the private Compose network. + +### Prepare the server + +1. Create a Linux VM and install Docker Engine with the Compose plugin. +2. Allow inbound TCP 80 and 443 (and UDP 443 for HTTP/3) in the cloud + firewall or security group. Keep SSH restricted to your own addresses. +3. Create DNS records for two hostnames, for example + `agentloop-api.example.com` and `agentloop.example.com`, pointing at the VM's + public address. Caddy can only issue certificates once these resolve. + +### Configure and start + +```bash +git clone --depth 1 --branch v0.2.7 https://github.com/dipeshbabu/agentloop.git +cd agentloop +cp deploy/.env.example deploy/.env +``` + +Create the dashboard password hash and random secrets: + +```bash +docker run --rm caddy:2 caddy hash-password --plaintext 'choose-a-strong-password' +openssl rand -hex 32 +``` + +Edit `deploy/.env`: set `AGENTLOOP_IMAGE` to the release you want, both +domains, `AGENTLOOP_ADMIN_API_KEY`, `POSTGRES_PASSWORD`, the dashboard user and +the bcrypt hash. Keep the hash in single quotes so Compose does not expand its +`$` characters. Never commit `deploy/.env`. + +```bash +docker compose -f deploy/docker-compose.yml up --detach +docker compose -f deploy/docker-compose.yml ps +curl https://agentloop-api.example.com/v1/readyz +``` + +Open the dashboard hostname in a browser and sign in with the user and password +you chose. + +### Create a project key and upload traces + +The admin key only creates project keys. Create one per team or CI pipeline: + +```bash +curl -X POST https://agentloop-api.example.com/v1/api-keys \ + -H "X-AgentLoop-Admin-Key: $AGENTLOOP_ADMIN_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"project_id": "my-team", "name": "ci"}' +``` + +Use the returned key from Python: + +```python +from agentloop import AgentLoopClient + +client = AgentLoopClient(base_url="https://agentloop-api.example.com", api_key="...") +client.upload_trace(trace) +``` + +or from the TypeScript SDK with +`new AgentLoopClient({ baseUrl: "https://agentloop-api.example.com", apiKey: "..." })`. +In the dashboard, set the sidebar's Project field to the same project ID. + +### Upgrade and back up + +Back up the database, change `AGENTLOOP_IMAGE` to the new version, then +recreate the containers. Pending migrations run on startup. + +```bash +docker compose -f deploy/docker-compose.yml exec db \ + pg_dump --format=custom --username agentloop --file /tmp/agentloop.dump agentloop +docker compose -f deploy/docker-compose.yml cp db:/tmp/agentloop.dump ./agentloop.dump +docker compose -f deploy/docker-compose.yml pull +docker compose -f deploy/docker-compose.yml up --detach +``` + +Copy backups off the server and test restoring them. Migrations are +forward-only; to roll back, restore the backup and redeploy the previous image. +See [database schema migrations](PRODUCTION.md#database-schema-migrations). + +### What CI verifies + +Every pull request starts this exact stack with the image built from that +commit, using Caddy's local certificate authority for `*.localhost` names. It +checks that: + +- the API is ready over HTTPS and stores and returns a trace with a project key; +- plain HTTP redirects to HTTPS, and uploads over the size limit are refused; +- the dashboard returns 401 without the login or with a wrong password, and + loads with the right one; +- the API, dashboard and database ports are not published on the host. + +## Option 2: managed container platforms + +Managed platforms run the image without a server to maintain. Pair the API with +the platform's managed Postgres: + +| Platform | Containers | Postgres | +| --- | --- | --- | +| Google Cloud | Cloud Run | Cloud SQL for PostgreSQL | +| AWS | App Runner or ECS on Fargate | Amazon RDS for PostgreSQL | +| Azure | Container Apps | Azure Database for PostgreSQL | +| Others | Fly.io, Render, Railway | Their managed Postgres | + +These deployments are not exercised in CI. The same image and settings apply: + +1. Some platforms pull only from their own registry, for example Cloud Run from + Artifact Registry and App Runner from Amazon ECR. Copy the image there: + + ```bash + docker pull ghcr.io/dipeshbabu/agentloop:0.2.7 + docker tag ghcr.io/dipeshbabu/agentloop:0.2.7 REGISTRY/agentloop:0.2.7 + docker push REGISTRY/agentloop:0.2.7 + ``` + +2. Run the API with container port 8000 and its default command, and set: + + ```bash + AGENTLOOP_STORE_BACKEND=postgres + AGENTLOOP_DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/agentloop + AGENTLOOP_REQUIRE_API_KEY=true + AGENTLOOP_ADMIN_API_KEY= + AGENTLOOP_CORS_ORIGINS=https:// + ``` + + Store the secrets in the platform's secret manager rather than plain + environment settings, and percent-encode reserved characters in the URL + password. Use `/readyz` as the health check path. + +3. Optionally run the dashboard as a second service from the same image with + the command `streamlit run dashboard/app.py --server.address=0.0.0.0 + --server.port=8501 --server.headless=true`, the same database settings, and + `AGENTLOOP_API_URL` set to the API's URL. The dashboard has no login of its + own: put it behind the platform's identity layer, such as Identity-Aware + Proxy on Google Cloud or built-in authentication on Azure Container Apps, or + keep it on a private network. Do not expose it publicly without one. + +Multiple API replicas can share one database; migrations are safe to run +concurrently. Set the platform's request size limit to match your largest +trace uploads. + +## Kubernetes + +No manifests or Helm chart are provided yet. The image, port, health check and +environment variables above are all a deployment needs; keep the dashboard +behind an authenticating ingress. + +## Security checklist + +- Require API keys (`AGENTLOOP_REQUIRE_API_KEY=true`) and keep the admin key + out of clients; give each team or pipeline its own project key. +- Serve only HTTPS, and never expose the dashboard without a login. +- Keep Postgres off the public internet and back it up. +- Traces can contain prompts, tool inputs and outputs. Decide what you capture + and how long you keep it before sending production data; see + [trace retention](TRACE_RETENTION.md). + +The [production guide](PRODUCTION.md) covers every setting, health checks and +password rotation in detail. diff --git a/docs/PRODUCTION.md b/docs/PRODUCTION.md index 4e9fdad..9b2b3f9 100644 --- a/docs/PRODUCTION.md +++ b/docs/PRODUCTION.md @@ -6,6 +6,10 @@ AgentLoop has three production surfaces: - API service: receive traces, enforce API keys, store runs, and serve reports. - Dashboard: inspect traces, usage, optimization plans, and value reports. +To run the API and dashboard on a cloud server with HTTPS and a dashboard login, +follow [Deploy to the cloud](CLOUD_DEPLOY.md). This guide covers every setting +behind that deployment. + ## Required configuration Set secrets outside source control and configure the public origins explicitly: @@ -214,7 +218,8 @@ Migration `0003` (issue #19) only adds indexes and has no data impact. Tag releases as `vX.Y.Z`. The release workflow builds the Python package and can publish to PyPI when the repository has a trusted-publishing PyPI environment -configured. +configured. From 0.2.7 it also publishes the container image to +`ghcr.io/dipeshbabu/agentloop`. ## Deployment Notes diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 986f3f6..49e51ee 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -97,6 +97,14 @@ Recover an interrupted tagged release by explicitly dispatching: gh workflow run release.yml --ref vX.Y.Z ``` +The container image job builds the Dockerfile from the tagged commit, checks that +the image reports the release version and runs as a non-root user, and pushes +`ghcr.io/dipeshbabu/agentloop:X.Y.Z` and `:latest` with the workflow's +`GITHUB_TOKEN`. GitHub creates the package as private on its first push. Once, +open the package's settings under the owner's **Packages** tab, connect it to +this repository if needed, and set its visibility to public so deployments can +pull it without credentials. + Do not reuse a published version or move its tag. Publish a new patch for a fix. PyPI cannot restore deleted releases or accept a previously used filename. @@ -121,6 +129,13 @@ path/to/wheel-env/bin/python -I scripts/smoke_installed_wheel.py --expected-vers On Windows use `path/to/wheel-env/Scripts/python.exe`. A merged PR, tag, or GitHub release does not prove PyPI publication; verify each destination independently. +Check the container image the same way: + +```bash +docker pull ghcr.io/dipeshbabu/agentloop:X.Y.Z +docker run --rm ghcr.io/dipeshbabu/agentloop:X.Y.Z python -c "import agentloop; print(agentloop.__version__)" +``` + For the initial numbering restart, install the exact `0.1.0` version in existing environments and refresh pinned requirements. Removing earlier PyPI releases requires the owner's [project management page](https://pypi.org/manage/project/agentloop-profiler/releases/). diff --git a/mkdocs.yml b/mkdocs.yml index bd1de78..dc197e2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -123,6 +123,7 @@ nav: - Workflow tracing: WORKFLOW_TRACING.md - Dashboard: DASHBOARD.md - Server deployment: PRODUCTION.md + - Deploy to the cloud: CLOUD_DEPLOY.md - Operations: OPERATIONS.md - Advanced runtime controls: - Harness overview: HARNESS.md