> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Running Locally

tsdevstack provides a complete local development environment with Docker Compose.

## Quick start

```bash
# Generate all configs
npx tsdevstack sync

# Start everything
npm run dev
```

This starts:

- **Kong Gateway** at `http://localhost:8000`
- **PostgreSQL** database
- **Redis** cache
- **RustFS** object storage, console at `http://localhost:9001` (if storage buckets configured)
- **All your services** with hot reload
- **All your workers** with hot reload (see [Workers](/docs/introduction/supported-apps.md#workers))

## Local architecture


````
┌─────────────────────────────────────────────────────────────┐
│  Docker Compose Network                                     │
│                                                             │
│    Browser ──► localhost:8000                               │
│                    │                                        │
│                    ▼                                        │
│              ┌──────────┐                                   │
│              │   Kong   │                                   │
│              └────┬─────┘                                   │
│                   │                                         │
│      ┌────────────┼────────────┐                            │
│      ▼            ▼            ▼                            │
│  ┌────────┐  ┌────────┐  ┌────────┐                         │
│  │  Auth  │  │ Offers │  │  BFF   │  (hot reload)           │
│  │ :3001  │  │ :3002  │  │ :3003  │                         │
│  └───┬────┘  └───┬────┘  └───┬────┘                         │
│      │           │           │                              │
│      └───────────┴───────────┘                              │
│                  │                                          │
│      ┌───────────┴───────────┐                              │
│      ▼                       ▼                              │
│  ┌────────┐             ┌────────┐                          │
│  │Postgres│             │ Redis  │                          │
│  │ :5432  │             │ :6379  │                          │
│  └────────┘             └────────┘                          │
│                                                             │
│  Observability:                                             │
│  Prometheus :9090 │ Grafana :4001 │ Jaeger :16686           │
└─────────────────────────────────────────────────────────────┘
````

Key differences from cloud:

- **No load balancer** - Kong handles TLS termination directly
- **Direct service access** - Services are also reachable on their individual ports for debugging (e.g., `localhost:3001`)
- **Hot reload** - Source code is mounted into containers
- **Local secrets** - Secrets come from `.secrets.local.json` files

## What the generate commands do

The framework has two main generation commands:

```bash
npx tsdevstack generate-secrets  # Regenerates secrets files
npx tsdevstack generate-kong     # Regenerates Kong configuration
```

These regenerate framework-managed files:

- `kong.tsdevstack.yml` - Framework gateway routes
- `kong.yml` - Merged gateway config
- `.secrets.tsdevstack.json` - Framework secrets
- `.secrets.local.json` - Merged secrets

Run generation after:

- Adding or removing a service
- Adding or removing storage buckets
- Changing OpenAPI decorators
- Adding custom secrets to `.secrets.user.json`

## Accessing services

All services are accessed through the Kong gateway:

```bash
# Service endpoints (route prefixes use the short name, e.g., /auth/, /offers/)
curl http://localhost:8000/auth/v1/auth/login
curl http://localhost:8000/offers/v1/plans
```

Swagger UI is served directly by each service (not through Kong):

```bash
# Access Swagger for auth-service running on port 3001
http://localhost:3001/api
```

See [Swagger Docs](/docs/building-apis/swagger-docs.md) for details.

## Stopping

Press `Ctrl+C` in the terminal running `npm run dev` to stop all services.

To stop Docker containers:

```bash
docker compose down
```
