# Configuration

> Manage runtime configuration with config vars, plus app.json for repeatable bootstraps.

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

```bash
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

```bash
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:

```bash
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:

```bash
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

```bash
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

```bash
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](https://docs.watasu.io/reference/addon-env-vars.md).

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](https://docs.watasu.io/workflows/review-apps.md), it's required** — Watasu uses it to spin up each PR's preview environment.

### Minimal example

```json
{
  "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](https://docs.watasu.io/reference/app-json.md).

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

[View this page on the web](https://docs.watasu.io/apps/configuration/)