Skip to main content

Running in Staging

Sagaweaw works in staging environments out of the box. There is no code change between local, staging, and production — only configuration changes.

How it works​

Sagaweaw needs two things to run in any environment:

  1. A PostgreSQL (or MySQL) database — for its own tables (sagas, saga_steps, saga_events, dead_letters), created automatically by the embedded Flyway migration on startup.
  2. An observability token — to protect the /api/sagas endpoints.

That's it. The same application binary runs in all three environments.

Typical environment setup​

Local       →  Docker Compose PostgreSQL   +  sagaweaw.observability.token=dev-token
Staging     →  RDS / Cloud SQL / Supabase  +  sagaweaw.observability.token=${SAGAWEAW_TOKEN_STAGING}
Production  →  RDS / Cloud SQL             +  sagaweaw.observability.token=${SAGAWEAW_TOKEN_PROD}

Staging configuration​

Add these to your staging application.properties or environment variables:

# application-staging.properties

# Points to your staging database — same one your app already uses
spring.datasource.url=jdbc:postgresql://<staging-host>:5432/<your-db>
spring.datasource.username=${DB_USER}
spring.datasource.password=${DB_PASSWORD}

# A separate token for staging — generate with: openssl rand -hex 32
sagaweaw.observability.token=${SAGAWEAW_TOKEN_STAGING}

sagaweaw.kafka.enabled=false

Flyway creates the sagaweaw tables in your staging database on the first startup. They live alongside your application's own tables with no conflict — sagaweaw uses its own sagaweaw_schema_history table to track its migrations independently.

Accessing the dashboard in staging​

The dashboard at http://your-staging-host:8484 connects to your staging application using the staging token. You can also use the embedded mode at http://your-staging-host:8080/sagaweaw if you have sagaweaw.dashboard.mode=embedded configured.

To inspect sagas via REST from your local machine:

curl -H "X-Sagaweaw-Token: $SAGAWEAW_TOKEN_STAGING" \
     https://your-staging-api.example.com/api/sagas

No code changes required​

Your saga definitions, step logic, context classes, and SagaManager calls are identical across all environments. The only thing that changes is where the database is and what token protects the API.

Tip

Use separate tokens per environment. This ensures that if someone has access to staging observability, they don't automatically have access to production.