🚀 Integration Quick Start

Get SEA™ integration infrastructure running locally in minutes.


Prerequisites

Tool Version Purpose
Docker 24+ Container runtime
docker-compose 2.20+ Service orchestration
nats-cli 0.1+ NATS management
just 1.0+ Task runner

1. Start Infrastructure

1
2
3
4
5
# Start all integration services
docker-compose up -d nats postgres

# Verify services are healthy
docker-compose ps

Expected Output

1
2
3
NAME                STATUS              PORTS
sea-nats            running             4222:4222, 8222:8222
sea-postgres        running             5432:5432

2. Initialize JetStream

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Create SEA_EVENTS stream
nats stream add SEA_EVENTS \
  --subjects "sea.event.>" \
  --retention limits \
  --max-age 7d \
  --max-bytes 10GB \
  --storage file

# Create default consumer
nats consumer add SEA_EVENTS sea__default \
  --filter "sea.event.>" \
  --ack explicit \
  --wait 120s \
  --max-deliver 20 \
  --pull

3. Run Database Migrations

1
2
3
4
5
6
# Apply outbox/inbox tables
just db-migrate

# Verify tables exist
psql $DATABASE_URL -c "\dt *outbox*"
psql $DATABASE_URL -c "\dt *inbox*"

4. Start Workers

1
2
3
4
5
# Start the messaging worker
just run-mq-worker

# In another terminal, start the handler service
just run-handlers

5. Test Integration

Publish a Test Event

1
2
3
4
5
6
7
8
# Insert an event into the outbox
psql $DATABASE_URL -c "
INSERT INTO outbox_events (id, aggregate_type, aggregate_id, event_type, payload)
VALUES (gen_random_uuid(), 'Test', 'test-1', 'test_created', '{\"message\": \"Hello\"}');
"

# Watch the worker logs
docker logs -f sea-mq-worker

Verify Delivery

1
2
3
4
# Check stream message count
nats stream info SEA_EVENTS

# Should show: Messages: 1

Common Issues

Issue Solution
connection refused on 4222 Ensure NATS container is running
stream not found Run JetStream initialization
Events stuck in outbox Check publish_error column for details

Next Steps