Local Development Setup

This guide covers setting up the local development environment for Orcha, including MiniStack for AWS service emulation and PostgreSQL for the database.

MiniStack is a free, MIT-licensed drop-in replacement for LocalStack. The container is configured with PERSIST_STATE=1 and a mounted volume at ./volumes/ministack, so S3 objects, SQS queues, SSM parameters, secrets and KMS keys survive bb dev:down. Use bb dev:reset for a fresh slate.

Prerequisites

Docker - For running MiniStack and PostgreSQL
Babashka - For running project tasks (brew install borkdude/brew/babashka or see babashka.org)
Clojure CLI - For running the application (brew install clojure/tools/clojure)
AWS CLI - For running AWS commands against MiniStack via bb dev:aws-cli (brew install awscli)

Quick Start

# Start dev environment (MiniStack + PostgreSQL)
bb dev:up

# Seed MiniStack with Orcha's AWS resources (first boot, or whenever you add one)
bb dev:seed

# Start REPL with dev profile
clj -A:dev

# In REPL, test all services
(require '[aws :as aws])
(aws/test-all!)

Babashka Tasks

Run bb tasks to see all available tasks:

Development Environment

Task	Description
`bb dev:up`	Start MiniStack + PostgreSQL. Run `bb dev:seed` afterwards to create/refresh AWS resources.
`bb dev:down`	Stop containers (postgres and MiniStack state persist in Docker volumes)
`bb dev:reset`	Stop containers and delete all data (fresh start — re-run `bb dev:seed` afterwards)
`bb dev:status`	Show container status
`bb dev:logs`	Tail all container logs
`bb dev:seed`	Seed MiniStack with Orcha's AWS resources. Idempotent; run on first boot and after adding new SSM params / queues / buckets.
`bb dev:aws-cli`	Run AWS CLI against MiniStack (e.g., `bb dev:aws-cli s3 ls`)

Database

Task	Description
`bb db:psql`	Connect to PostgreSQL with psql
`bb db:logs`	Tail PostgreSQL logs

Services

PostgreSQL

Host: localhost
Port: 5432
Database: orcha
User: postgres
Auth: trust (no password required)

Connect via psql:

bb db:psql
# or
psql -h localhost -U postgres -d orcha

MiniStack (AWS Emulation)

After bb dev:up followed by bb dev:seed, MiniStack has:

S3 Bucket

Name: v1-orcha-documents-local
Purpose: PDF document storage

SQS Queues

Main Queue: v1-orcha-documents (visibility timeout: 600s)
Dead Letter Queue: v1-orcha-dlq (after 3 failed attempts)

Secrets Manager

v1-orcha/db-password - Database credentials (JSON)

SSM Parameter Store

/v1-orcha/ocr-api-key - OCR service API key
/v1-orcha/llm-api-key - LLM service API key
/v1-orcha/external-service-api-key - External service API key
/v1-orcha/receiver-api-key - Receiver API key (auto-generated UUID)

Common Operations

Reset Everything (Fresh Start)

Delete all data and start fresh:

bb dev:reset
bb dev:up

This deletes both the MiniStack and PostgreSQL Docker volumes.

Adding New AWS Resources

To add a new SSM parameter, KMS key, bucket, or queue:

Edit scripts/ministack-seed/ssm-parameters.json (for SSM params) or scripts/ministack-seed/seed.sh (for other resources).
Commit.
Run bb dev:seed — the script is idempotent, so it only creates what's missing.

bb dev:up does not auto-seed; this is deliberate so the output of the seed step is always visible to the person running it. The script is mounted into the container at /opt/orcha-seed/ and invoked on demand.

Note: deletes are not handled by the script. To remove a resource from a running MiniStack, do it manually with bb dev:aws-cli (e.g., bb dev:aws-cli ssm delete-parameter --name /v1-orcha/foo), or do a full bb dev:reset for a clean slate.

Reset MiniStack Only

If you want to reset AWS resources but keep PostgreSQL data:

docker-compose stop ministack
rm -rf volumes/ministack
docker-compose up -d ministack --wait
bb dev:seed

A plain docker-compose restart preserves state on disk; delete the mount directory to actually wipe resources, then re-seed.

Reset PostgreSQL Only

If you want to reset the database but keep AWS resources:

docker-compose stop postgres
docker volume rm orcha_postgres_data
docker-compose up -d postgres --wait

Check Service Health

# Container status
bb dev:status

# MiniStack health
curl http://localhost:4566/_ministack/health

# PostgreSQL health
docker exec orcha-postgres pg_isready -U postgres -d orcha

Testing Connectivity

From the REPL:

(require '[aws :as aws])

;; Run all tests (PostgreSQL + AWS)
(aws/test-all!)

;; --- PostgreSQL ---
(aws/db-query-one ["SELECT version()"])
(aws/db-query ["SELECT current_database(), current_user"])

;; --- S3 ---
(aws/s3-put-object "test.txt" "Hello World")
(aws/s3-get-object "test.txt")
(aws/s3-list-objects "")

;; --- SQS ---
(aws/sqs-send-message {:document-id "123"})
(aws/sqs-receive-messages 10)

;; --- Secrets Manager ---
(aws/get-secret "v1-orcha/db-password")

;; --- SSM Parameter Store ---
(aws/get-parameter "/v1-orcha/ocr-api-key")

Logging

Development (Default)

Output: Plain text to stdout
Level: DEBUG for com.getorcha.*, INFO for others
Config: resources/log4j2.xml

Example output:

2025-01-15 10:30:00.123 [main] DEBUG com.getorcha.erp - Processing request...

Production

Output: JSON to /var/log/orcha/app.log
Level: INFO
Config: resources/log4j2-prod.xml
Activate: -Dlog4j2.configurationFile=classpath:log4j2-prod.xml

Troubleshooting

Containers Won't Start

Check if Docker is running: docker ps
Check if ports are in use: lsof -i :4566 or lsof -i :5432
View container logs: bb dev:logs

PostgreSQL Connection Refused

Verify container is running: bb dev:status
Check container health: docker exec orcha-postgres pg_isready
View PostgreSQL logs: bb db:logs

AWS CLI Commands Fail

Use the bb dev:aws-cli task which handles credentials automatically:

bb dev:aws-cli s3 ls
bb dev:aws-cli sqs list-queues

Or set credentials manually for direct AWS CLI usage:

export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=eu-central-1

REPL Can't Connect

Verify containers are running: bb dev:status
Check endpoints:
- MiniStack: curl http://localhost:4566/_ministack/health
- PostgreSQL: psql -h localhost -U postgres -d orcha -c "SELECT 1"
Ensure you're using the :dev alias: clj -A:dev

File Structure

orcha/
├── bb.edn                    # Babashka tasks
├── docker-compose.yml        # MiniStack + PostgreSQL config
├── scripts/
│   └── ministack-seed/
│       ├── seed.sh           # Idempotent MiniStack seed (run via bb dev:seed)
│       └── ssm-parameters.json
│           └── ssm-parameters.json
├── dev/
│   ├── user.clj              # REPL startup
│   └── aws.clj               # Test utilities (AWS + PostgreSQL)
├── resources/
│   ├── log4j2.xml            # Dev logging config
│   ├── log4j2-prod.xml       # Prod logging config
│   └── JsonLayout.json       # JSON log format template
└── docs/
    └── local-development.md  # This file