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

Each var is either plain (readable by anyone with Manage on the app) or secret (readable and editable only by the app owner). Plain or secret, the value is always injected into the running process unchanged — your app code never sees a redacted value.

List

watasu config --app my-app

Shows the effective environment, including vars provided by attached add-ons. Secret vars you don’t own are shown with a redacted value (••••••••) so you can still see the key list.

Set one or many

watasu config:set 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.

By default, new vars are created as plain, and re-setting an existing var preserves its current secret/plain state.

Mark a var as a secret

Use --secret when you want a value only the app owner can read or change:

watasu config:set STRIPE_SECRET_KEY=sk_live_xxx --secret --app my-app

--secret works for both new and existing vars — running it on an existing plain var promotes it to secret.

Demote a secret back to plain

Use --plain to remove the secret marker. The value stays the same, but the var becomes readable and editable by any maintainer:

watasu config:set API_URL=https://api.example.com --plain --app my-app

--secret and --plain are mutually exclusive. Omit both to leave the secret state untouched.

Load from a file

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

Useful for bulk-importing local development settings during initial setup. Combine with --secret to mark every var in the file as a secret on import.

Unset

watasu config:unset API_URL --app my-app

Only the app owner can unset a secret var. Maintainers can unset plain vars.

Ownership and visibility at a glance

Role	Plain var	Secret var (owned elsewhere)
App owner	Read & write	Read & write (full access)
Maintainer (non-owner)	Read & write	Key visible, value redacted, cannot edit or unset
View/Deploy/Operate-only	No config-var management access unless also granted Manage	No config-var management access unless also granted Manage
App runtime / release	Real value injected	Real value injected
App build	May be available to the builder	Not injected into builder inputs

The redaction is a UI and API guardrail for humans; your processes always receive the real value at runtime. Builds receive plain app vars and add-on-managed vars, but app-owned secret vars stay runtime/release-only.

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 secret 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.