# Quick Start

Deploy Monetarie PIX locally in 15 minutes using Docker Compose. This guide covers the fastest path from zero to a running system with the admin portal accessible.

## Prerequisites

- Docker 24+ and Docker Compose v2 installed
- 8 GB RAM available
- Ports 4003, 5432, 6379, 4222, and 8080 free
- Git installed

## Step 1: Clone the Repository

```bash
git clone https://github.com/MonetarieBR/pix.git
cd pix
```

## Step 2: Configure Environment

```bash
cp backend/.env.example backend/.env
```

The default `.env` file contains development settings that work out of the box:

```bash
# Database
DB_HOST=postgres
DB_PORT=5432
DB_USER=postgres
DB_PASS=postgres
DB_NAME=monetarie

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

# NATS
NATS_HOST=nats
NATS_PORT=4222
NATS_ENABLED=true

# Security
SECRET_KEY_BASE=dev-only-secret-key-base-replace-in-production-min-64-chars!!
MIX_ENV=prod

# Simulator (no real BACEN connection needed)
SIMULATOR_ENABLED=true
BACEN_ENABLED=false
```

## Step 3: Start Services

```bash
cd backend
docker compose up -d
```

This starts 4 containers:
- `postgres` -- PostgreSQL 16 on port 5432
- `redis` -- Redis 7 on port 6379
- `nats` -- NATS 2.10 with JetStream on port 4222
- `pix-backend` -- Monetarie PIX backend on port 4003

Wait for the backend to be healthy (~30 seconds):

```bash
docker compose logs -f pix-backend
# Wait for: "=== Starting Shared Application ==="
```

## Step 4: Run Migrations

```bash
docker compose exec pix-backend bin/monetarie_pix eval "Shared.Release.migrate()"
```

Expected output: 25 migrations applied.

## Step 5: Seed Data

```bash
docker compose exec pix-backend bin/monetarie_pix eval "Shared.Release.seed()"
```

This loads:
- 10 participants, 7 users, 369 reference banks
- 277 PIX keys, 15,442 DICT operations
- 1,000+ realistic transactions (30-day history)
- 44 COSIF accounts, 27 XSD schemas
- BACEN simulator scenarios

## Step 6: Verify

```bash
# Health check
curl http://localhost:4003/health

# Login (returns JWT cookie)
curl -X POST http://localhost:4003/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Admin@2026!"}'
```

## Step 7: Access the Admin Portal

If running the admin frontend locally:

```bash
cd frontend/admin
npm install
npm run dev
# Open http://localhost:5173
```

Login credentials:

| User | Password | Role |
|------|----------|------|
| admin | Admin@2026! | System Administrator |
| operator | Operator@2026! | Transaction Operator |
| viewer | Viewer@2026! | Read-only Viewer |

## Quick Verification Checklist

| Check | Command | Expected |
|-------|---------|----------|
| Backend health | `curl localhost:4003/health` | `200 OK` |
| Dict Service | `curl localhost:4001/api/health` | `200 OK` |
| SPI Service | `curl localhost:4002/api/health` | `200 OK` |
| Database | `docker compose exec postgres psql -U postgres -d monetarie -c "SELECT count(*) FROM monetarie_spi.messages"` | 1000+ rows |
| NATS | `docker compose exec nats nats stream ls` | 7 streams |
| Redis | `docker compose exec redis redis-cli ping` | `PONG` |

## Stopping the Environment

```bash
docker compose down        # Stop containers (keep data)
docker compose down -v     # Stop containers and delete volumes
```

## Next Steps

- [Architecture](./architecture.md) -- understand the system design
- [Environment Variables](../configuration/environment.md) -- full configuration reference
- [Kubernetes Deployment](../deployment/kubernetes.md) -- production-grade deployment
- [Admin Portal](../administration/portal.md) -- explore the admin interface

## Expected Outcome

After completing this quick start:

- All 4 backend services are running and healthy
- The database is populated with seed data including test transactions
- You can log in as admin and explore the API
- The BACEN simulator is available for testing PIX flows without real BACEN connectivity