Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.strait.dev/llms.txt

Use this file to discover all available pages before exploring further.

Follow these steps to set up Strait locally and run your first job. You’ll have a production-grade job orchestration service running in under 10 minutes.

​
Prerequisites

Before you begin, ensure you have:
1

Go 1.26+

Required to build and run Strait from source. Verify with go version. Download from golang.org/dl.
2

Docker and Docker Compose

Required to run PostgreSQL, Redis, and Sequin locally. Verify with docker --version and docker compose version. Download from docker.com.
3

curl (optional)

For API interaction examples. Most users can use the CLI instead. Verify with curl --version.

​
Step 1: Clone and Start Infrastructure

Docker Compose will start PostgreSQL 18, Redis 8, and Sequin in isolated containers. Ports exposed: PostgreSQL (5432), Redis (6379), Strait API (8080).
# Clone the repository
git clone https://github.com/leonardomso/strait.git
cd strait

# Start all services
docker compose -f apps/strait/docker-compose.yml up -d

# Verify services are running
docker compose -f apps/strait/docker-compose.yml ps
Expected output: 
NAME              STATUS
strait      Up
postgres           Up
redis             Up
sequin            Up

​
Step 2: Set Environment Variables

Configure necessary environment variables for Strait to connect to infrastructure.
Strait validates required environment variables on startup. Missing variables cause a clear error message with configuration instructions.
# Database connection - required
export DATABASE_URL=postgres://strait:strait@localhost:5432/strait?sslmode=disable

# Redis connection - required
export REDIS_URL=redis://localhost:6379

# Internal API secret - required (minimum 32 characters)
export INTERNAL_SECRET=your-secret-here-change-this-in-production

# JWT signing key - required (minimum 32 characters)
export JWT_SIGNING_KEY=your-jwt-key-must-be-at-least-32-chars-long

# Optional: Log level (debug, info, warn, error)
# export LOG_LEVEL=info
Never commit secrets to version control. Use environment variables, secret managers (AWS Secrets Manager, HashiCorp Vault), or .env files added to .gitignore.

​
Step 3: Build and Run Strait

Build Strait binary and start it in all mode (API + worker combined). 
# Build the server from source
cd apps/strait && go build -o strait ./cmd/strait

# Run in all mode (API + worker in one process)
./strait --mode all
Startup Process:
  1. Connect to PostgreSQL and apply any pending migrations automatically
  2. Open HTTP server on port 8080
  3. Start worker pool and scheduler background tasks
  4. Print startup banner with configuration summary
Separate Modes: Use --mode api or --mode worker for horizontal scaling in production.

​
Step 4: Create a Job

Create a new job definition via REST API or CLI. Jobs define the template for recurring tasks.
Jobs are the core unit of work. They define the endpoint URL, timeout, retry strategy, and other configuration. Runs are execution instances of jobs.
# Create a job
curl -X POST http://localhost:8080/v1/jobs \
  -H "Authorization: Bearer your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_123",
    "name": "Hello World",
    "slug": "hello-world",
    "endpoint_url": "https://httpbin.org/post",
    "timeout_secs": 60,
    "max_attempts": 3
  }'
Expected response: 
{
  "id": "job_abc123",
  "project_id": "proj_123",
  "name": "Hello World",
  "slug": "hello-world",
  "endpoint_url": "https://httpbin.org/post",
  "created_at": "2026-03-09T10:00:00Z"
}
Use the CLI for most operations. It handles authentication, pagination, and output formatting automatically. See CLI Reference for all commands.

​
Step 5: Trigger a Job

Trigger a run for the job you just created. Strait will enqueue the run and a worker will dispatch it to the endpoint. 
# Trigger with a payload
curl -X POST http://localhost:8080/v1/jobs/hello-world/trigger \
  -H "Authorization: Bearer your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "greeting": "Hello from Strait!"
    }
  }'
Expected response: 
{
  "id": "run_xyz789",
  "job_id": "job_abc123",
  "status": "queued",
  "priority": 0,
  "created_at": "2026-03-09T10:05:00Z",
  "scheduled_at": null
  "next_retry_at": null
}
1

Dequeued

Worker claims the run using SELECT FOR UPDATE SKIP LOCKED and transitions to dequeued state.
2

Executing

Worker sends HTTP POST to https://httpbin.org/post with the payload.
3

Completed

If the endpoint returns 2xx, run transitions to completed and result is stored.
4

Failed / Retrying

If the endpoint returns non-2xx, run is scheduled for retry using exponential backoff.

​
Step 6: Watch the Run

Monitor the status of your job run in real-time. 
# Get run status
curl http://localhost:8080/v1/runs/run_xyz789 \
  -H "Authorization: Bearer your-secret-here"

# Or use the CLI watch command
./strait runs watch run_xyz789
Run lifecycle states: queued → dequeued → executing → completed or failed.
Real-time updates: Subscribe to Server-Sent Events via the /v1/runs/{runID}/stream endpoint for live status updates without polling.

​
Step 7: Create a Simple Workflow

Workflows allow you to chain multiple jobs together in a DAG (Directed Acyclic Graph). Steps can depend on outputs from parent steps. 
# Create a workflow with two sequential steps
curl -X POST http://localhost:8080/v1/workflows \
  -H "Authorization: Bearer your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_123",
    "name": "Data Pipeline",
    "slug": "data-pipeline",
    "steps": [
      {
        "step_ref": "extract",
        "job_id": "job_abc123",
        "payload": {"action": "extract"}
      },
      {
        "step_ref": "transform",
        "job_id": "job_abc123",
        "depends_on": ["extract"],
        "payload": {"action": "transform"}
      }
    ]
  }'
Workflow Execution: When triggered, Strait creates a workflow_run. Step extract executes first, then transform executes only after extract completes. The DAG engine handles fan-in automatically when multiple steps depend on the same parent.

​
Troubleshooting

1

PostgreSQL Connection Issues

2

Job Not Picked Up

3

Endpoint Timeouts

4

Repeated Failures

5

SSRF Blocking

​
Common Mistakes

Mistake 1: Committing secrets to git. Always use environment variables or secret managers. Add .env to .gitignore.
Mistake 2: Using weak INTERNAL_SECRET. Generate a cryptographically secure secret with at least 32 characters. Use different secrets for development vs. production.
Mistake 3: Insufficient JWT_SIGNING_KEY. The key must be at least 32 characters for HS256 algorithm security. Generate with openssl rand -base64 32 or use a password manager.
Mistake 4: Not checking worker pool capacity. Monitor queue depth with strait stats. If jobs are queuing faster than workers can process, increase pool size via WORKER_POOL_SIZE environment variable.

​
What’s Next?

Architecture Deep Dive

Learn about queue mechanics, the 13-state FSM, workflow engine, and why we chose our technology stack.

Concepts

Understand jobs, runs, workflows, scheduling, retry strategies, and cost budgets in depth.

CLI Reference

Master 48+ CLI commands with shell completion, contexts, aliases, and output formats.

API Documentation

REST API endpoints for job management, workflow orchestration, and SDK interactions.

​
Next Steps

Jobs

Learn how jobs work in Strait.

Workflows

Build multi-step workflow DAGs.

SDKs

Choose your language and start building.

Deployment

Deploy Strait to production.