Configuration

Two things shape an app’s runtime configuration on Watasu: config vars for the day-to-day, and app.json when you want bootstrap to be repeatable (especially for review apps).

Config vars

Config vars are environment variables Watasu injects into your processes at runtime. They’re the right home for:

• secrets (API keys, signing keys)
• credentials and connection URLs
• per-environment hostnames
• feature flags
• runtime tuning knobs

List

watasu config --app my-app

Shows the effective environment, including vars provided by attached add-ons.

Set one or many

watasu config:set SECRET_KEY_BASE=replace-me API_URL=https://api.example.com --app my-app

You can pass any number of KEY=value pairs in a single call. Each config:set triggers a new release.

Load from a file

watasu config:set --file .env --app my-app

Useful for bulk-importing local development settings during initial setup.

Unset

watasu config:unset API_URL --app my-app

Add-on managed vars

Some config vars are owned by attached add-ons:

• PostgreSQL → DATABASE_URL, PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD
• Valkey → REDIS_URL
• Object Storage → S3_BUCKET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL, and friends

The full list lives in Reference → Add-on Environment Variables.

You can read these like any other config var, but don’t overwrite them — the add-on will reset them on its next reconcile, and the override window in between will likely break your app.

app.json

app.json is an optional manifest at the root of your repo. It tells Watasu how to bootstrap an app from scratch — config defaults, add-ons to provision, formation defaults, and post-deploy scripts.

For most flows it’s optional. For review apps, it’s required — Watasu uses it to spin up each PR’s preview environment.

Minimal example

{
  "name": "Example App",
  "description": "Example Watasu app",
  "env": {
    "RAILS_ENV": { "value": "production" }
  },
  "addons": [
    "postgresql",
    "valkey:hobby-1"
  ],
  "formation": {
    "web":    { "quantity": 1, "size": "standard-1x" },
    "worker": { "quantity": 1, "size": "standard-1x" }
  },
  "scripts": {
    "postdeploy":   "bundle exec rails db:prepare",
    "pr-predestroy": "bundle exec rails app:cleanup"
  }
}

What gets used

Field	What Watasu does with it
env	Sets config vars on bootstrap
addons	Provisions and attaches the listed add-ons
formation	Applies replica counts and pod sizes
scripts.postdeploy	Runs once after the first successful deploy
scripts.pr-predestroy	Runs when a review app is being torn down

The full schema, including metadata fields, is in Reference → app.json Schema.

Tips

• Keep postdeploy idempotent. It might run more than once over an app’s lifetime.
• Don’t bake secrets into app.json. Use plain config vars for those, set out-of-band.
• Test the file by creating a real review app from a real PR — that’s where it actually exercises end-to-end.