feat: add local development environment
- docker-compose.yaml: Local PostgreSQL on port 5433 - .env.local.example: Environment template for local dev - Makefile: Dev commands (run, test, db-up, db-reset, etc.) - QUICKSTART.md: Developer setup guide - .gitignore: Exclude .env.local Verified workflow: 1. make setup (creates .env.local) 2. make db-up (starts postgres) 3. make run (auto-migrates and serves on :8080) All endpoints tested and working. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
jordan
parent
48f7dc9f74
commit
2fc8454b8c
18
.env.local.example
Normal file
18
.env.local.example
Normal file
@ -0,0 +1,18 @@
|
||||
# rdev-api local development configuration
|
||||
# Copy to .env.local and customize as needed
|
||||
# Usage: cp .env.local.example .env.local
|
||||
|
||||
# Server
|
||||
PORT=8080
|
||||
|
||||
# Database (matches docker-compose.yaml defaults)
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5433
|
||||
DB_USER=appuser
|
||||
DB_PASSWORD=localdev
|
||||
DB_NAME=rdev
|
||||
DB_SSL_MODE=disable
|
||||
|
||||
# Authentication
|
||||
# Fixed dev admin key - DO NOT use in production
|
||||
RDEV_ADMIN_KEY=rdev_sk_devadmin_0123456789abcdef0123456789abcdef
|
||||
3
.gitignore
vendored
3
.gitignore
vendored
@ -4,6 +4,9 @@
|
||||
*.key
|
||||
*.pem
|
||||
|
||||
# Local development
|
||||
.env.local
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
86
Makefile
Normal file
86
Makefile
Normal file
@ -0,0 +1,86 @@
|
||||
# rdev-api development commands
|
||||
# Run 'make help' to see available targets
|
||||
|
||||
.PHONY: help setup run test build clean db-up db-down db-reset db-shell db-logs
|
||||
|
||||
# Load .env.local if it exists
|
||||
ifneq (,$(wildcard .env.local))
|
||||
include .env.local
|
||||
endif
|
||||
|
||||
# Default values (can be overridden by .env.local)
|
||||
PORT ?= 8080
|
||||
DB_HOST ?= localhost
|
||||
DB_PORT ?= 5433
|
||||
DB_USER ?= appuser
|
||||
DB_PASSWORD ?= localdev
|
||||
DB_NAME ?= rdev
|
||||
DB_SSL_MODE ?= disable
|
||||
RDEV_ADMIN_KEY ?= rdev_sk_devadmin_0123456789abcdef0123456789abcdef
|
||||
|
||||
# Export all variables to child processes
|
||||
export PORT DB_HOST DB_PORT DB_USER DB_PASSWORD DB_NAME DB_SSL_MODE RDEV_ADMIN_KEY
|
||||
|
||||
help: ## Show this help
|
||||
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
|
||||
|
||||
setup: ## First-time setup: copy env template
|
||||
@if [ ! -f .env.local ]; then \
|
||||
cp .env.local.example .env.local; \
|
||||
echo "Created .env.local from template"; \
|
||||
else \
|
||||
echo ".env.local already exists"; \
|
||||
fi
|
||||
|
||||
run: ## Run the API server locally
|
||||
go run ./cmd/rdev-api
|
||||
|
||||
test: ## Run all tests
|
||||
go test -v ./...
|
||||
|
||||
build: ## Build the binary
|
||||
CGO_ENABLED=0 go build -o rdev-api ./cmd/rdev-api
|
||||
|
||||
clean: ## Remove build artifacts
|
||||
rm -f rdev-api
|
||||
|
||||
# Database commands
|
||||
db-up: ## Start local PostgreSQL container
|
||||
docker compose up -d postgres
|
||||
@echo "Waiting for postgres to be ready..."
|
||||
@until docker compose exec -T postgres pg_isready -U $(DB_USER) -d $(DB_NAME) > /dev/null 2>&1; do \
|
||||
sleep 1; \
|
||||
done
|
||||
@echo "PostgreSQL is ready on port $(DB_PORT)"
|
||||
|
||||
db-down: ## Stop local PostgreSQL container
|
||||
docker compose down
|
||||
|
||||
db-reset: ## Reset database (destroy and recreate)
|
||||
docker compose down -v
|
||||
$(MAKE) db-up
|
||||
|
||||
db-shell: ## Open psql shell to local database
|
||||
docker compose exec postgres psql -U $(DB_USER) -d $(DB_NAME)
|
||||
|
||||
db-logs: ## View PostgreSQL logs
|
||||
docker compose logs -f postgres
|
||||
|
||||
# Combined commands
|
||||
dev: db-up run ## Start database and run API
|
||||
|
||||
# Testing helpers
|
||||
curl-health: ## Test health endpoint
|
||||
@curl -s http://localhost:$(PORT)/health | jq .
|
||||
|
||||
curl-projects: ## Test projects endpoint (requires auth)
|
||||
@curl -s -H "Authorization: Bearer $(RDEV_ADMIN_KEY)" http://localhost:$(PORT)/projects | jq .
|
||||
|
||||
curl-keys: ## Test keys endpoint (requires auth)
|
||||
@curl -s -H "Authorization: Bearer $(RDEV_ADMIN_KEY)" http://localhost:$(PORT)/keys | jq .
|
||||
|
||||
create-test-key: ## Create a test API key
|
||||
@curl -s -X POST -H "Authorization: Bearer $(RDEV_ADMIN_KEY)" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "test-key", "scopes": ["projects:read"], "expires_in": "30d"}' \
|
||||
http://localhost:$(PORT)/keys | jq .
|
||||
183
QUICKSTART.md
Normal file
183
QUICKSTART.md
Normal file
@ -0,0 +1,183 @@
|
||||
# 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
|
||||
23
docker-compose.yaml
Normal file
23
docker-compose.yaml
Normal file
@ -0,0 +1,23 @@
|
||||
# Local development environment for rdev-api
|
||||
# Usage: docker compose up -d
|
||||
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:15-alpine
|
||||
container_name: rdev-postgres
|
||||
environment:
|
||||
POSTGRES_USER: appuser
|
||||
POSTGRES_PASSWORD: localdev
|
||||
POSTGRES_DB: rdev
|
||||
ports:
|
||||
- "5433:5432" # Use 5433 to avoid conflicts with local postgres
|
||||
volumes:
|
||||
- rdev-postgres-data:/var/lib/postgresql/data
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U appuser -d rdev"]
|
||||
interval: 5s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
volumes:
|
||||
rdev-postgres-data:
|
||||
Loading…
Reference in New Issue
Block a user