# 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.