f9a6a8aafb
- Replace all docker-compose.yml/docker-compose.monitoring.yml references with compose.yaml/compose.monitoring.yaml (modern Compose Spec naming) - Replace all `docker-compose` CLI commands with `docker compose` (plugin syntax) - Update Dockerfile stage descriptions: node:18-alpine → node:20.11-bookworm-slim, built-in node user → explicit nodeapp:1001 non-root user - Update image version references: postgres:14-alpine → postgres:14.12-alpine3.19, redis:7-alpine → redis:7.2-alpine3.19 - Externalize postgres credentials: hardcoded values → POSTGRES_USER/PASSWORD/DB env vars - Externalize Grafana admin password: hardcoded 'agentidp' → GF_ADMIN_PASSWORD env var - Add Docker Compose Variables section to environment-variables.md (POSTGRES_*, GF_ADMIN_PASSWORD) - Update local-development.md Step 3: cp .env.example .env, document POSTGRES_* purpose - Update quick-start.md: cp .env.example .env, use awk/sed for JWT key injection - Update 07-dev-setup.md: remove 'no .env.example' claim, reference cp .env.example - Update docker-compose.yml key file description in 04-codebase-structure.md - Update monitoring overlay launch commands across all docs (compose.yaml + compose.monitoring.yaml) - Update volume names to kebab-case: postgres_data → postgres-data, redis_data → redis-data - Fix compliance encryption-runbook: docker-compose restart agentidp → docker compose restart app All docs now consistent with compose.yaml in repo root. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
291 lines
6.8 KiB
Markdown
291 lines
6.8 KiB
Markdown
# Local Development
|
|
|
|
Complete setup guide for running AgentIdP locally.
|
|
|
|
## Prerequisites
|
|
|
|
| Tool | Minimum version | Purpose |
|
|
|------|----------------|---------|
|
|
| Docker | 24+ | Container runtime |
|
|
| Docker Compose | 2.20+ | Multi-container orchestration |
|
|
| Node.js | 18.0.0 | Run the application, portal, and migrations |
|
|
| npm | 9+ | Package management and scripts |
|
|
| nvm | any | Recommended for managing Node.js versions |
|
|
| openssl | any | RSA key generation |
|
|
|
|
Verify versions:
|
|
|
|
```bash
|
|
docker --version
|
|
docker compose version
|
|
node --version
|
|
npm --version
|
|
```
|
|
|
|
> **nvm activation:** If using nvm, activate it before running any Node.js commands:
|
|
> ```bash
|
|
> export NVM_DIR="$HOME/.nvm" && source "$NVM_DIR/nvm.sh"
|
|
> ```
|
|
|
|
---
|
|
|
|
## Step 1 — Clone and install dependencies
|
|
|
|
```bash
|
|
git clone https://git.sentryagent.ai/vijay_admin/sentryagent-idp.git
|
|
cd sentryagent-idp
|
|
npm install
|
|
|
|
# Install portal dependencies
|
|
cd portal && npm install && cd ..
|
|
```
|
|
|
|
---
|
|
|
|
## Step 2 — Generate JWT keys
|
|
|
|
AgentIdP signs tokens with RS256. You need an RSA-2048 keypair.
|
|
|
|
```bash
|
|
openssl genrsa -out private.pem 2048
|
|
openssl rsa -in private.pem -pubout -out public.pem
|
|
```
|
|
|
|
Keep these files in the project root. They are used only locally and should not be committed.
|
|
|
|
---
|
|
|
|
## Step 3 — Configure environment
|
|
|
|
Copy the template and fill in your values:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
The template already includes all required variables. At minimum, verify these are set correctly for local development:
|
|
|
|
```
|
|
POSTGRES_USER=sentryagent
|
|
POSTGRES_PASSWORD=sentryagent
|
|
POSTGRES_DB=sentryagent_idp
|
|
DATABASE_URL=postgresql://sentryagent:sentryagent@localhost:5432/sentryagent_idp
|
|
REDIS_URL=redis://localhost:6379
|
|
PORT=3000
|
|
NODE_ENV=development
|
|
CORS_ORIGIN=*
|
|
```
|
|
|
|
> **Note:** `POSTGRES_USER`, `POSTGRES_PASSWORD`, and `POSTGRES_DB` are used by `compose.yaml`
|
|
> to configure the PostgreSQL container and construct `DATABASE_URL`. They are not read by
|
|
> the application directly — only `DATABASE_URL` is.
|
|
|
|
Append the JWT keys to `.env`:
|
|
|
|
```bash
|
|
echo "JWT_PRIVATE_KEY=\"$(awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' private.pem)\"" >> .env
|
|
echo "JWT_PUBLIC_KEY=\"$(awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' public.pem)\"" >> .env
|
|
```
|
|
|
|
Verify the file has all required variables:
|
|
|
|
```bash
|
|
grep -E "^(DATABASE_URL|REDIS_URL|JWT_PRIVATE_KEY|JWT_PUBLIC_KEY)" .env
|
|
```
|
|
|
|
---
|
|
|
|
## Step 4 — Start infrastructure services
|
|
|
|
The `compose.yaml` defines three services: `postgres`, `redis`, and `app`. For local development, start only the infrastructure services — the application runs directly via Node.js.
|
|
|
|
```bash
|
|
docker compose up -d postgres redis
|
|
```
|
|
|
|
Expected output:
|
|
|
|
```
|
|
[+] Running 2/2
|
|
✔ Container sentryagent-idp-postgres-1 Healthy
|
|
✔ Container sentryagent-idp-redis-1 Healthy
|
|
```
|
|
|
|
Both services must show `Healthy` before proceeding. If they show `Starting`, wait a few seconds and run `docker compose ps` to recheck.
|
|
|
|
### Service ports
|
|
|
|
| Service | Port | Health check |
|
|
|---------|------|-------------|
|
|
| PostgreSQL | 5432 | `pg_isready -U sentryagent -d sentryagent_idp` |
|
|
| Redis | 6379 | `redis-cli ping` → `PONG` |
|
|
|
|
Verify manually:
|
|
|
|
```bash
|
|
docker compose exec postgres pg_isready -U sentryagent -d sentryagent_idp
|
|
docker compose exec redis redis-cli ping
|
|
```
|
|
|
|
### Docker volumes
|
|
|
|
Data is persisted in named Docker volumes (kebab-case per Compose Spec standard):
|
|
|
|
| Volume | Service | Contents |
|
|
|--------|---------|---------|
|
|
| `sentryagent-idp_postgres-data` | PostgreSQL | All database data |
|
|
| `sentryagent-idp_redis-data` | Redis | Redis persistence (if enabled) |
|
|
|
|
---
|
|
|
|
## Step 5 — Run database migrations
|
|
|
|
```bash
|
|
npm run db:migrate
|
|
```
|
|
|
|
Expected output:
|
|
|
|
```
|
|
Running database migrations...
|
|
✓ Applied: 001_create_agents.sql
|
|
...
|
|
✓ Applied: 026_add_tenant_tiers.sql
|
|
|
|
Migrations complete. 26 migration(s) applied.
|
|
```
|
|
|
|
See [database.md](database.md) for full migration documentation.
|
|
|
|
---
|
|
|
|
## Step 6 — Start the application
|
|
|
|
### Development mode (TypeScript source, no compile step)
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Expected startup output:
|
|
|
|
```
|
|
SentryAgent.ai AgentIdP listening on port 3000
|
|
```
|
|
|
|
The application connects to PostgreSQL and Redis on first request (lazy initialisation). If either service is unreachable, the first request will fail with a connection error — not startup.
|
|
|
|
### Production mode (compiled JavaScript)
|
|
|
|
```bash
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
The compiled output is written to `dist/`. `npm start` runs `node dist/server.js`.
|
|
|
|
---
|
|
|
|
## Step 7 — Start the Next.js portal (optional)
|
|
|
|
The portal is a Next.js 14 application in the `portal/` directory. It communicates with the
|
|
AgentIdP backend at `http://localhost:3000`.
|
|
|
|
Start the portal development server:
|
|
|
|
```bash
|
|
cd portal && npm run dev
|
|
```
|
|
|
|
The portal starts on port 3001 by default. Open http://localhost:3001.
|
|
|
|
Available routes:
|
|
|
|
| Route | Description |
|
|
|-------|-------------|
|
|
| `/login` | OAuth 2.0 login page |
|
|
| `/agents` | Agent registry |
|
|
| `/credentials` | Credential management |
|
|
| `/audit` | Audit log viewer |
|
|
| `/analytics` | Token trend and agent activity charts |
|
|
| `/settings/tier` | Tier status and upgrade |
|
|
| `/compliance` | AGNTCY compliance report |
|
|
| `/webhooks` | Webhook subscription management |
|
|
| `/marketplace` | Agent marketplace |
|
|
|
|
Build the portal for production:
|
|
|
|
```bash
|
|
cd portal && npm run build
|
|
cd portal && npm start # serves the production build
|
|
```
|
|
|
|
Ensure `CORS_ORIGIN` in your `.env` includes `http://localhost:3001`:
|
|
```
|
|
CORS_ORIGIN=http://localhost:3001
|
|
```
|
|
|
|
---
|
|
|
|
## Full Docker Compose Stack
|
|
|
|
> The full Docker Compose stack (including the `app` container) is available for field trial
|
|
> deployments — see the [field trial guide](field-trial.md). For day-to-day development, start
|
|
> only the infrastructure services and run the application directly.
|
|
|
|
The entire stack (infrastructure + application) can be started with:
|
|
|
|
```bash
|
|
docker compose up --build -d
|
|
```
|
|
|
|
The `app` service depends on `postgres` and `redis` with health check conditions, so it will not start until both services are healthy. Environment variables are loaded from `.env` via the `env_file` directive in `compose.yaml` (`required: false` — the file is optional if env vars are injected directly).
|
|
|
|
---
|
|
|
|
## Stopping Services
|
|
|
|
Stop infrastructure only (preserves volumes):
|
|
|
|
```bash
|
|
docker compose stop postgres redis
|
|
```
|
|
|
|
Stop and remove containers (preserves volumes):
|
|
|
|
```bash
|
|
docker compose down
|
|
```
|
|
|
|
Stop and remove containers AND volumes (destroys all data):
|
|
|
|
```bash
|
|
docker compose down -v
|
|
```
|
|
|
|
> Use `-v` only when you want a clean slate. This deletes all PostgreSQL data and Redis data permanently.
|
|
|
|
---
|
|
|
|
## Running Tests
|
|
|
|
Unit tests (no infrastructure required):
|
|
|
|
```bash
|
|
npm run test:unit
|
|
```
|
|
|
|
Integration tests (require running PostgreSQL and Redis):
|
|
|
|
```bash
|
|
npm run test:integration
|
|
```
|
|
|
|
All tests:
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
Integration tests connect to the same `DATABASE_URL` and `REDIS_URL` from `.env`. Ensure infrastructure is running before executing integration tests.
|