Skip to main content

Local Dev Sandbox

The Relay sandbox replicates the managed stack (API, worker, Postgres, Redis, metrics) so you can develop and validate functions locally.

Prerequisites​

  • Docker Desktop or Docker Engine 20+
  • Go 1.22+ (the CLI shells out to docker)
  • Python environment with pytest

Validate prerequisites:

docker --version
go version
pytest --version

CLI Quick Start​

# Start the sandbox (uses docker-compose.dev.yml)
relay dev up

# Tail logs for all services
relay dev logs

# Tail logs for a single service
relay dev logs --service api

# Run the unit suite against the sandbox
relay dev test

# Stop the sandbox
relay dev down

# Run full suite with sandbox orchestration
relay test --suite integration --with-sandbox

# Write JUnit XML to a custom directory (defaults to dev_process/results/test_runs)
relay test --suite manifest --results-dir tmp/test_artifacts

# Run performance benchmarks / quality gates
relay bench
relay audit
relay validate

By default CLI commands use docker-compose.dev.yml. Override with --compose-file when running bespoke stacks.

What the Sandbox Includes​

  • FastAPI control plane
  • Background worker
  • Postgres + Redis
  • Metrics exporter
  • Hot reload enabled via Uvicorn --reload

Compose definitions live at the repository root. Feel free to customise .env before launching.

Smoke Testing​

scripts/testing/dev_sandbox_smoke.sh

The script wraps relay dev up/test/down, ensuring Docker is installed and collecting a basic health check. If the relay binary is not on your PATH it falls back to go run ./cli/main.go.

Troubleshooting​

  • Docker missing: install Docker Desktop or the Docker CLI.
  • Ports occupied: relay dev down and rerun, or update the compose file.
  • Pytest not found: install development dependencies (pip install -r requirements.txt).
  • FN-103: Manifest + lockfile tooling powers dependency resolution.
  • FN-108: Upcoming hot reload enhancements reuse the sandbox runner.