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

# 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

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

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

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

Or the X-API-Key header:

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

Creating API Keys

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

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

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

Database connection errors

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

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