sentryagent-idp/docs/devops/local-development.md

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:

docker --version
docker-compose --version
node --version
npm --version

---

Step 1 — Clone and install dependencies

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.

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:

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:

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:

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.

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:

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

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 for full migration documentation.

---

Step 6 — Start the application

Development mode (TypeScript source, no compile step)

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)

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:

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):

docker-compose stop postgres redis

Stop and remove containers (preserves volumes):

docker-compose down

Stop and remove containers AND volumes (destroys all data):

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):

npm run test:unit

Integration tests (require running PostgreSQL and Redis):

npm run test:integration

All tests:

npm test

Integration tests connect to the same DATABASE_URL and REDIS_URL from .env. Ensure infrastructure is running before executing integration tests.