create-urateam 0.1.8 → 0.1.12

package/template/.urateam/.env.example

@@ -1,39 +1,95 @@
-# === Required ===
+# =============================================================================
+# urateam .env — copy to .env and fill in. NEVER commit .env to git.
+# =============================================================================
+
+# === Linear (REQUIRED) ===
 LINEAR_API_KEY=
 LINEAR_WEBHOOK_SECRET=
 LINEAR_TEAM_ID=
 
-# Repository — REQUIRED to boot. `ura dev` and `ura start` exit with an
-# error if REPO_TEAM_ID or REPO_URL are missing or blank. Without these
-# the webhook server otherwise starts looking healthy but silently fails
-# every inbound Linear event with "no repo mapping". In the common
-# single-team setup, REPO_TEAM_ID is the same UUID as LINEAR_TEAM_ID.
+# === Repository (REQUIRED) ===
+# `ura dev` and `ura start` exit with an error if these are missing.
+# In a single-team setup, REPO_TEAM_ID == LINEAR_TEAM_ID.
 REPO_URL=
 REPO_DEFAULT_BRANCH=main
 REPO_TEAM_ID=
 
-# Database
-DATABASE_URL=postgres://urateam:password@postgres:5432/urateam
+# === Anthropic auth (REQUIRED for production / headless) ===
+# Use ANTHROPIC_API_KEY for any deployment without an interactive shell
+# (VPS, containerized, CI). The OSS-tier `claude` CLI session flow only
+# works when you can `claude login` interactively on the host.
+ANTHROPIC_API_KEY=
+
+# === Pro license (REQUIRED for Pro features: Slack, multi-repo, deep-review, etc.) ===
+URATEAM_LICENSE_KEY=
+
+# === GitHub (REQUIRED for PR creation in production) ===
+# Two paths: GitHub App credentials (production) OR `gh` CLI session
+# inside the container (`docker compose exec agent gh auth login` after
+# bringing the stack up — fine for solo / single-repo).
+#
+# Production path — GitHub App:
+#   1. Create at github.com/settings/apps/new with Contents:Write,
+#      Pull requests:Write, Metadata:Read scopes
+#   2. Install the app on the target repo
+#   3. Download the private key .pem and bind-mount it into the container
+#      (e.g. add a volume map in docker-compose.yml: ./gh-app.pem:/run/gh-app.pem:ro)
+# GITHUB_APP_ID=
+# GITHUB_PRIVATE_KEY_PATH=/run/gh-app.pem
+# GITHUB_INSTALLATION_ID=
+# Optional: only needed if PR-comment-driven re-runs are enabled
+# GITHUB_WEBHOOK_SECRET=
 
-# Dashboard auth (required)
+# === Database ===
+# Generate POSTGRES_PASSWORD with: openssl rand -base64 32
+# DATABASE_URL is assembled in docker-compose.yml from this password —
+# do NOT set it here (env_file does not interpolate variables).
+POSTGRES_PASSWORD=
+
+# === Domain (REQUIRED for production deploy with the Caddy reverse proxy) ===
+# Public hostname Caddy will request a Let's Encrypt cert for. Must resolve
+# to this host before bringing the stack up; ports 80 + 443 must be open.
+DOMAIN=
+# Email for ACME / Let's Encrypt expiry warnings. Strongly recommended.
+CADDY_EMAIL=
+
+# === Dashboard auth (REQUIRED) ===
+# Generate a strong DASHBOARD_PASSWORD. Production refuses to start without one.
 DASHBOARD_USER=admin
 DASHBOARD_PASSWORD=
+# Set DASHBOARD_BASE_PATH if mounting under a path prefix (no trailing slash).
+# DASHBOARD_BASE_PATH=
+
+# === Workspace (defaults inside the container) ===
+# AGENT_RUN_DIR=/var/agent-runs
+# REPO_CLONE_DIR=/var/agent-repos
+# WORKTREE_TTL_HOURS=24
+
+# === Concurrency ===
+# MAX_CONCURRENT_RUNS=3
+
+# =============================================================================
+# Optional features below
+# =============================================================================
 
-# === Optional ===
 # Override per-stage agent budget (maxTurns / maxInputTokens / model / tools).
-# Useful when the test stage has to bootstrap test infra from scratch and
-# burns through the default 25-turn cap. See urateam#38.
+# Useful when the test stage has to bootstrap test infra and burns the
+# default 25-turn cap. See urateam#38.
 # URATEAM_AGENT_PROFILES='{"test":{"maxTurns":50,"maxInputTokens":80000}}'
 
+# Slack notifier — basic incoming-webhook (no Pro license needed)
 # SLACK_WEBHOOK_URL=
 # DISCORD_WEBHOOK_URL=
-# GITHUB_WEBHOOK_SECRET=
+
+# PM Agent + Slack interface (Pro feature: slack-interface)
 # PM_AGENT_ENABLED=false
 # PM_AGENT_TEAM_IDS=
 # PM_AGENT_SLACK_CHANNEL_ID=
 # PM_AGENT_DAILY_TOKEN_BUDGET=5000000
 # PM_AGENT_MAX_IN_FLIGHT=3
+# PM_AGENT_CRON_INTERVAL_MS=1800000
 # SLACK_BOT_TOKEN=
+# SLACK_SIGNING_SECRET=
+
+# Logging
 # LOG_LEVEL=info
-# MAX_CONCURRENT_RUNS=3
-# URATEAM_LICENSE_KEY=

package/template/.urateam/Caddyfile

@@ -0,0 +1,36 @@
+# urateam reverse proxy + auto-HTTPS via Let's Encrypt.
+#
+# Caddy routes:
+#   - /webhooks/*  → agent:3000 (Linear, GitHub webhook receivers)
+#   - /slack/*     → agent:3000 (Slack events + slash commands, optional PM agent)
+#   - /health      → agent:3000 (liveness probe)
+#   - everything else → agent:3001 (the ops dashboard)
+#
+# DOMAIN is read from .env; required for cert issuance.
+# Ports 80 and 443 must be reachable from the public internet for ACME.
+
+{
+    email {$CADDY_EMAIL}
+}
+
+{$DOMAIN} {
+    encode zstd gzip
+
+    handle /webhooks/* {
+        reverse_proxy agent:3000
+    }
+    handle /slack/* {
+        reverse_proxy agent:3000
+    }
+    handle /health {
+        reverse_proxy agent:3000
+    }
+    handle {
+        reverse_proxy agent:3001
+    }
+
+    log {
+        output stdout
+        format console
+    }
+}

package/template/.urateam/Dockerfile

@@ -1,7 +1,16 @@
 FROM node:22-slim
 
-RUN apt-get update && apt-get install -y git gh && rm -rf /var/lib/apt/lists/*
+# git + gh: needed by the agent for cloning, branch operations, PR creation.
+# Claude Code CLI: required for OSS-tier subscription auth and as a fallback
+# for Pro-tier deployments that don't set ANTHROPIC_API_KEY. Persisted auth
+# lives at /root/.config/claude — bind-mounted via a docker volume below
+# so `claude login` only has to run once.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends git gh ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+
 RUN corepack enable
+RUN npm install -g @anthropic-ai/claude-code
 
 WORKDIR /app
 COPY package.json pnpm-lock.yaml* ./

package/template/.urateam/README.md

@@ -7,10 +7,18 @@ to implement features, fix bugs, and create PRs automatically.
 
 ## Setup
 
-1. Fill in `.env` with your Linear API key, webhook secret, team ID, and repo URL
+Two paths: pick one.
+
+### Local dev (your laptop)
+
+1. Copy `.env.example` to `.env` and fill in. NEVER commit `.env`.
 2. Install dependencies: `pnpm install`
-3. **Authenticate Claude** (OSS path only — see [Claude auth lifecycle](#claude-auth-lifecycle-oss-tier) below): `claude login`
-4. Start the agent: `pnpm dev` (SQLite, local dev) or `pnpm start` (production)
+3. **Authenticate Claude** (OSS path only — see [Claude auth lifecycle](#claude-auth-lifecycle-oss-tier) below): `claude login`. Skip if you set `ANTHROPIC_API_KEY`.
+4. Start the agent: `pnpm dev`
+
+### Production VPS
+
+Skip the `pnpm install` / `pnpm dev` steps and jump straight to [Production deploy](#production-deploy-via-docker-compose) — Docker Compose handles everything.
 
 ## Claude auth lifecycle (OSS tier)
 
@@ -44,23 +52,98 @@ Use that variant when re-authing inside a running container.
 have session-lifetime semantics, so this whole concern goes away. See the
 [urateam docs](https://github.com/JonB32/urateam) for upgrade paths.
 
-## Expose the webhook
+## Expose the webhook (local dev only)
 
-The agent listens on `http://localhost:3000/webhooks/linear`. To receive
-webhooks from Linear, expose this port via ngrok or a reverse proxy:
+The agent listens on `http://localhost:3000/webhooks/linear`. For local
+development, expose via ngrok:
 
 ```bash
 ngrok http 3000
 ```
 
 Configure the ngrok URL as a webhook in Linear settings with the
-`LINEAR_WEBHOOK_SECRET` from your `.env`.
+`LINEAR_WEBHOOK_SECRET` from your `.env`. For production, see
+[Production deploy](#production-deploy-via-docker-compose) — Caddy
+handles HTTPS termination directly and you wire Linear to your real domain.
 
 ## Dashboard
 
 The ops dashboard runs on `http://localhost:3001`. Credentials from
 `DASHBOARD_USER` / `DASHBOARD_PASSWORD` in `.env`.
 
+## Production deploy via docker compose
+
+Compose template ships a hardened three-service stack:
+
+- **caddy** — reverse proxy on :80/:443 with automatic Let's Encrypt certs.
+  Routes `/webhooks/*` and `/slack/*` to the agent (:3000), everything else
+  to the dashboard (:3001).
+- **agent** — `ura start`. No public ports; reachable only via Caddy.
+- **postgres** — internal-only network, no published ports. Password from
+  `POSTGRES_PASSWORD` (compose refuses to start without it).
+
+### Pre-flight
+
+1. **Provision a VPS** (Hetzner, DigitalOcean, Linode, Fly, etc.). 4 GB RAM
+   minimum for `MAX_CONCURRENT_RUNS=3`.
+2. **Point a domain** (e.g. `urateam.your-domain.com`) at the VPS IP. Caddy needs
+   ports 80 + 443 open for ACME challenges.
+3. **Install Docker** and the Compose plugin on the box.
+
+### Deploy
+
+```bash
+# 1. On the VPS, clone or scp this project
+cd /opt/<project>/.urateam
+
+# 2. Copy and fill in env
+cp .env.example .env
+# At minimum set: DOMAIN, CADDY_EMAIL, POSTGRES_PASSWORD (openssl rand -base64 32),
+# ANTHROPIC_API_KEY, URATEAM_LICENSE_KEY (for Pro), LINEAR_*, REPO_*,
+# DASHBOARD_PASSWORD.
+
+# 3. Bring up the stack
+docker compose up -d --build
+
+# 4. Authenticate Claude Code CLI inside the container (skip if you set
+#    ANTHROPIC_API_KEY in .env). Login is persisted in a docker volume,
+#    so this only has to run once per deployment.
+docker compose exec agent claude login
+
+# 5. Authenticate gh CLI inside the container (required for PR creation
+#    unless you wired GITHUB_APP_ID / GITHUB_PRIVATE_KEY_PATH /
+#    GITHUB_INSTALLATION_ID in .env). Also persisted across rebuilds.
+docker compose exec agent gh auth login
+
+# 4. Tail logs to verify license, webhooks, dashboard
+docker compose logs -f agent
+```
+
+After the first run, Caddy will request and store a Let's Encrypt cert for
+`$DOMAIN`. The dashboard is reachable at `https://$DOMAIN`, webhooks at
+`https://$DOMAIN/webhooks/linear`.
+
+### Wiring Linear
+
+In Linear → Workspace settings → API → Webhooks → Create:
+
+- URL: `https://$DOMAIN/webhooks/linear`
+- Secret: paste `LINEAR_WEBHOOK_SECRET` from `.env`
+- Subscribe to: Issue state changes (and any others your pipelines key off of).
+
+### Re-deploy
+
+```bash
+git pull && docker compose up -d --build
+```
+
+### Backups
+
+`pgdata` and `agent-runs` are named docker volumes. For backups, snapshot the
+host volume directory or use `docker run --rm -v pgdata:/data … pg_dump` style
+sidecars. Workspace dirs (`/var/agent-runs`, `/var/agent-repos`) auto-clean
+older than `WORKTREE_TTL_HOURS` (default 24h).
+
 ## How it works
 
 1. Move a Linear issue to the `Todo` state with an appropriate pipeline label

package/template/.urateam/docker-compose.yml

@@ -1,28 +1,67 @@
 services:
-  postgres:
-    image: postgres:16
+  caddy:
+    image: caddy:2
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
     environment:
-      POSTGRES_USER: urateam
-      POSTGRES_PASSWORD: password
-      POSTGRES_DB: urateam
+      DOMAIN: ${DOMAIN}
     volumes:
-      - pgdata:/var/lib/postgresql/data
-    ports:
-      - "5432:5432"
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy-data:/data
+      - caddy-config:/config
+    depends_on:
+      - agent
+    networks:
+      - frontend
 
   agent:
     build: .
+    restart: unless-stopped
     env_file: .env
+    environment:
+      # Compose interpolates ${POSTGRES_PASSWORD} from .env here. It does NOT
+      # interpolate inside .env itself, so DATABASE_URL must be assembled
+      # at the compose layer rather than the env-file layer.
+      DATABASE_URL: "postgres://urateam:${POSTGRES_PASSWORD}@postgres:5432/urateam"
     depends_on:
       - postgres
-    ports:
-      - "3000:3000"
-      - "3001:3001"
+    expose:
+      - "3000"
+      - "3001"
     volumes:
       - agent-runs:/var/agent-runs
       - agent-repos:/var/agent-repos
+      # Persist the `claude` and `gh` CLI login state across rebuilds so
+      # operators don't have to re-auth every `docker compose up --build`.
+      - claude-config:/root/.config/claude
+      - gh-config:/root/.config/gh
+    networks:
+      - frontend
+      - backend
+
+  postgres:
+    image: postgres:16
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: urateam
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set in .env}
+      POSTGRES_DB: urateam
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    networks:
+      - backend
+
+networks:
+  frontend:
+  backend:
 
 volumes:
   pgdata:
   agent-runs:
   agent-repos:
+  caddy-data:
+  caddy-config:
+  claude-config:
+  gh-config: