jordan/rdev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add local development environment

Browse Source 
- 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 2026-01-25 00:07:02 -07:00
parent 48f7dc9f74
commit 2fc8454b8c
5 changed files with 313 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
.env.local.example Normal file
View 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
View File

@ -4,6 +4,9 @@
*.key *.key
*.pem *.pem
# Local development
.env.local
# OS # OS
.DS_Store .DS_Store
Thumbs.db Thumbs.db

86
Makefile Normal file
View 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
View 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
View 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: