d94a8cedc0
Adds the full devops-documentation OpenSpec change implementation. Separate from docs/developers/ — serves a different audience (operators, not API consumers). docs/devops/: - README.md — index and system overview - architecture.md — components, ports, data flow, Redis key patterns - environment-variables.md — all 7 env vars (required + optional, formats, .env example) - database.md — 4-table schema, indexes, constraints, migration runner - local-development.md — docker-compose setup, health checks, startup, Dockerfile gap noted - security.md — RSA key generation/rotation, CORS, bcrypt, secret storage guidance - operations.md — startup order, graceful shutdown, log reference, troubleshooting QA gates: 48/48 tasks complete. All env vars verified against source. All table names verified against migrations. All ports verified against docker-compose.yml. All internal links resolve. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
229 lines
5.0 KiB
Markdown
229 lines
5.0 KiB
Markdown
# Local Development
|
|
|
|
Complete setup guide for running AgentIdP locally.
|
|
|
|
## Prerequisites
|
|
|
|
| Tool | Minimum version | Purpose |
|
|
|------|----------------|---------|
|
|
| Docker + Docker Compose | 24+ | Run PostgreSQL and Redis |
|
|
| Node.js | 18.0.0 | Run the application and migrations |
|
|
| npm | 9+ | Package management and scripts |
|
|
|
|
Verify versions:
|
|
|
|
```bash
|
|
docker --version
|
|
docker-compose --version
|
|
node --version
|
|
npm --version
|
|
```
|
|
|
|
---
|
|
|
|
## Step 1 — Clone and install dependencies
|
|
|
|
```bash
|
|
git clone https://git.sentryagent.ai/vijay_admin/sentryagent-idp.git
|
|
cd sentryagent-idp
|
|
npm install
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
Create a `.env` file in the project root:
|
|
|
|
```bash
|
|
cat > .env << 'ENVEOF'
|
|
DATABASE_URL=postgresql://sentryagent:sentryagent@localhost:5432/sentryagent_idp
|
|
REDIS_URL=redis://localhost:6379
|
|
PORT=3000
|
|
NODE_ENV=development
|
|
CORS_ORIGIN=*
|
|
ENVEOF
|
|
```
|
|
|
|
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 `docker-compose.yml` 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:
|
|
|
|
| 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: 002_create_credentials.sql
|
|
✓ Applied: 003_create_audit_events.sql
|
|
✓ Applied: 004_create_tokens.sql
|
|
|
|
Migrations complete. 4 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`.
|
|
|
|
---
|
|
|
|
## Full Docker Compose Stack
|
|
|
|
> **Note:** The `app` service in `docker-compose.yml` requires a `Dockerfile` which has not been written yet. This is a **Phase 1 P1 pending item**. The commands below will work once the Dockerfile exists.
|
|
|
|
When the Dockerfile is available, the entire stack (infrastructure + application) can be started with:
|
|
|
|
```bash
|
|
docker-compose up -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 for the container are loaded from `.env` via the `env_file` directive in `docker-compose.yml`.
|
|
|
|
---
|
|
|
|
## 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.
|