rdev/QUICKSTART.md

# rdev-api Developer Quickstart

Get the API running locally in under 2 minutes.

## Prerequisites

- Go 1.21+
- Docker (for PostgreSQL)
- jq (optional, for pretty JSON output)

## Quick Start

```bash
# 1. Clone and enter the repo
cd rdev

# 2. First-time setup (creates .env.local)
make setup

# 3. Start PostgreSQL
make db-up

# 4. Run the API
make run
```

The API will:
- Connect to PostgreSQL on port 5433
- Auto-run database migrations
- Start serving on http://localhost:8080

## Verify It Works

```bash
# Health check (no auth required)
curl http://localhost:8080/health | jq .

# API docs
open http://localhost:8080/docs

# List projects (requires auth)
make curl-projects

# Create a test API key
make create-test-key
```

## Available Commands

Run `make help` to see all commands:

| Command | Description |
|---------|-------------|
| `make setup` | First-time setup: create .env.local |
| `make run` | Run the API server |
| `make dev` | Start database + run API |
| `make test` | Run all tests |
| `make build` | Build the binary |
| `make db-up` | Start PostgreSQL container |
| `make db-down` | Stop PostgreSQL container |
| `make db-reset` | Destroy and recreate database |
| `make db-shell` | Open psql shell |
| `make curl-health` | Test health endpoint |
| `make curl-projects` | Test projects endpoint |
| `make curl-keys` | Test keys endpoint |
| `make create-test-key` | Create a test API key |

## Configuration

Edit `.env.local` to customize:

```bash
# Server
PORT=8080

# Database
DB_HOST=localhost
DB_PORT=5433
DB_USER=appuser
DB_PASSWORD=localdev
DB_NAME=rdev
DB_SSL_MODE=disable

# Authentication (dev admin key)
RDEV_ADMIN_KEY=rdev_sk_devadmin_0123456789abcdef0123456789abcdef
```

## API Authentication

All endpoints except `/health`, `/ready`, `/docs`, and `/openapi.json` require authentication.

Use the `Authorization` header:

```bash
curl -H "Authorization: Bearer rdev_sk_devadmin_..." http://localhost:8080/projects
```

Or the `X-API-Key` header:

```bash
curl -H "X-API-Key: rdev_sk_devadmin_..." http://localhost:8080/projects
```

### Creating API Keys

```bash
# Using the Makefile helper
make create-test-key

# Or manually
curl -X POST http://localhost:8080/keys \
  -H "Authorization: Bearer $RDEV_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-key", "scopes": ["projects:read"], "expires_in": "30d"}'
```

### Available Scopes

| Scope | Description |
|-------|-------------|
| `projects:read` | List and view projects |
| `projects:execute` | Run commands (claude, shell, git) |
| `keys:read` | List API keys |
| `keys:write` | Create and revoke keys |
| `admin` | Full access |

## Project Structure

```
rdev/
├── cmd/rdev-api/           # API entry point
├── internal/
│   ├── auth/               # Authentication (keys, middleware)
│   ├── db/                 # Database connection + migrations
│   ├── handlers/           # HTTP handlers
│   ├── executor/           # kubectl exec wrapper
│   └── projects/           # Project registry
├── pkg/api/                # HTTP server chassis
├── docker-compose.yaml     # Local PostgreSQL
├── Makefile                # Dev commands
└── .env.local              # Local config (gitignored)
```

## Troubleshooting

### Port 5432 already in use

The default port is 5433 to avoid conflicts with local PostgreSQL. If you still have issues:

```bash
# Check what's using the port
lsof -i :5433

# Or change the port in .env.local and docker-compose.yaml
```

### Database connection errors

```bash
# Reset the database
make db-reset

# Check PostgreSQL is running
docker compose ps

# View PostgreSQL logs
make db-logs
```

### Permission denied on /projects

Ensure you're using the admin key from `.env.local`:

```bash
source .env.local
curl -H "Authorization: Bearer $RDEV_ADMIN_KEY" http://localhost:8080/projects
```

## Next Steps

- View the API documentation at http://localhost:8080/docs
- Create application-specific API keys for your services
- See `history/` for version history and architecture decisions