chore: local dev setup

[alexluong]

Improve Local Development Setup

⚠️ Existing Contributors: This PR introduces significant changes to the local dev workflow. After merge, please re-read getting-started.md and update your setup:

• Ports changed from 1xxxx → 2xxxx (e.g., Redis 16379 → 26379)
• New starter configs: .env.dev and .outpost.yaml.dev
• Dependencies now use Docker Compose profiles via LOCAL_DEV_* variables

Why

The previous local dev setup required manual configuration and had port conflicts with common services.

What

1. Quick start config files - Added .env.dev and .outpost.yaml.dev as ready-to-use starter configs that work out of the box

2. Modular dependency management - Refactored docker-compose to use profiles controlled by LOCAL_DEV_* env vars:

   • Entity store: Redis (default) or Dragonfly
   • Log store: PostgreSQL and/or ClickHouse
   • MQ: RabbitMQ, LocalStack (AWS SQS), GCP PubSub
   • Optional GUI tools: redis-commander, pgAdmin, Tabix

3. Port conflict prevention - All host ports now use 2xxxx prefix (e.g., 26379 for Redis, 25432 for PostgreSQL)

4. Streamlined documentation - Rewrote getting-started.md with quick start at the top and reference tables for configuration

5. Test cleanup - Refactored rsmq tests to use shared testutil.CreateTestRedisClient

Getting Started

git clone https://github.com/hookdeck/outpost.git
cd outpost
cp .env.dev .env
cp .outpost.yaml.dev .outpost.yaml
make network
make up/deps
make up/outpost

API available at http://localhost:3333

Configuring Local Dependencies

Configuration is split between two files:

• .env - Controls which Docker services to start (LOCAL_DEV_* variables)
• .outpost.yaml - Outpost application settings (MQ connections, log store, API keys, etc.)

Why .outpost.yaml? Air watches this file and auto-restarts Outpost when it changes. With .env, you'd need to manually run make down/outpost && make up/outpost for changes to take effect.

The .env file controls which services make up/deps starts via LOCAL_DEV_* variables. By default, the setup uses Redis, PostgreSQL, and RabbitMQ.

Example: Switch from RabbitMQ to AWS SQS

1. Edit .env:

   # Optional: comment out to skip starting RabbitMQ container
   # LOCAL_DEV_RABBITMQ=1
   
   # Enable LocalStack (provides AWS SQS locally)
   LOCAL_DEV_LOCALSTACK=1

2. Edit .outpost.yaml to use SQS:

   mqs:
     # rabbitmq:
     #   server_url: "amqp://guest:guest@rabbitmq:5672"
     aws_sqs:
       endpoint: "http://localstack:4566"
       region: "us-east-1"
       access_key_id: "test"
       secret_access_key: "test"

3. Restart dependencies:

   make down/deps
   make up/deps

Available Options

Variable	Service
LOCAL_DEV_DRAGONFLY=1	Use Dragonfly instead of Redis
LOCAL_DEV_POSTGRES=1	PostgreSQL (log store)
LOCAL_DEV_CLICKHOUSE=1	ClickHouse (log store)
LOCAL_DEV_RABBITMQ=1	RabbitMQ
LOCAL_DEV_LOCALSTACK=1	LocalStack (AWS SQS/SNS/S3)
LOCAL_DEV_GCP=1	GCP PubSub emulator
LOCAL_DEV_REDIS_COMMANDER=28081	Redis Commander UI
LOCAL_DEV_PGADMIN=28082	pgAdmin UI
LOCAL_DEV_TABIX=28083	Tabix (ClickHouse UI)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
outpost-docs	Ready	Preview, Comment	Jan 3, 2026 9:36am
outpost-website	Ready	Preview, Comment	Jan 3, 2026 9:36am