# app.json Schema

> Full reference for app.json — fields, types, examples, and what each one does.

`app.json` is an optional manifest at the root of your repo that tells Watasu how to bootstrap an app. It's the source of truth for [review apps](https://docs.watasu.io/workflows/review-apps.md), and useful anywhere you want repeatable provisioning.

## Top-level fields

| Field          | Type             | Purpose                                                                                                    |
| -------------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |
| `name`         | string           | Display name.                                                                                              |
| `description`  | string           | Short summary.                                                                                             |
| `logo`         | string (URL)     | Logo image.                                                                                                |
| `website`      | string (URL)     | Project website.                                                                                           |
| `repository`   | string (URL)     | Source repo URL.                                                                                           |
| `keywords`     | array of strings | Categorization keywords.                                                                                   |
| `success_url`  | string           | Path to redirect to after a successful bootstrap.                                                          |
| `env`          | object           | Default config vars (see [env](https://docs.watasu.io/reference/app-json.md#env)).                         |
| `addons`       | array            | Add-ons to provision (see [addons](https://docs.watasu.io/reference/app-json.md#addons)).                  |
| `formation`    | object           | Process formation defaults (see [formation](https://docs.watasu.io/reference/app-json.md#formation)).      |
| `scripts`      | object           | Lifecycle scripts (see [scripts](https://docs.watasu.io/reference/app-json.md#scripts)).                   |
| `environments` | object           | Per-environment overrides (see [environments](https://docs.watasu.io/reference/app-json.md#environments)). |

## env

Each entry sets a config var on bootstrap.

```json
"env": {
  "RAILS_ENV":   { "value": "production" },
  "SECRET_KEY":  { "generator": "secret" },
  "API_BASE":    { "required": true, "description": "External API base URL" }
}
```

| Key           | Purpose                                                      |
| ------------- | ------------------------------------------------------------ |
| `value`       | Literal value to set.                                        |
| `generator`   | Generator to use (e.g. `secret` for a random string).        |
| `required`    | If `true`, bootstrap fails unless the user supplies a value. |
| `description` | Human-readable hint shown to the user during bootstrap.      |

## addons

Each entry provisions and attaches an add-on. You can use a plain string for the default plan or `service:plan` for a specific tier.

```json
"addons": [
  "postgresql",
  "postgresql:standard-0",
  "valkey:hobby-1",
  "object-storage"
]
```

For the full plan catalog, see [Add-on Plans](https://docs.watasu.io/reference/addon-plans.md).

## formation

Sets initial replica counts and pod sizes per process type.

```json
"formation": {
  "web":    { "quantity": 1, "size": "standard-1x" },
  "worker": { "quantity": 1, "size": "standard-1x" }
}
```

| Key        | Purpose                                                                                                             |
| ---------- | ------------------------------------------------------------------------------------------------------------------- |
| `quantity` | Replica count.                                                                                                      |
| `size`     | Pod size (`hobby`, `standard-1x` … `standard-16x`). See [Pod Sizes](https://docs.watasu.io/reference/pod-sizes.md). |

## environments

Override `env`, `addons`, `formation`, or `scripts` for a specific environment. The most common use is giving review apps a leaner setup than the defaults:

```json
"environments": {
  "review": {
    "addons": ["postgresql:hobby-0"],
    "formation": {
      "web": { "quantity": 1, "size": "hobby" }
    }
  }
}
```

Environment blocks are merged over the top-level fields — anything you don't override keeps its top-level value. Review apps use the environment name `review`.

## scripts

Lifecycle scripts that Watasu runs at specific points.

```json
"scripts": {
  "postdeploy":   "bundle exec rails db:prepare && bundle exec rails db:seed",
  "pr-predestroy": "bundle exec rails app:cleanup"
}
```

| Script          | When it runs                                                            |
| --------------- | ----------------------------------------------------------------------- |
| `postdeploy`    | Once after the first successful deploy. Use for migrations and seeding. |
| `pr-predestroy` | Before a review app is torn down. Use for external cleanup.             |

Keep both scripts idempotent — they may run more than once over an app's lifetime, especially `postdeploy`.

## Full example

```json
{
  "name": "Example App",
  "description": "A Watasu app with a database, cache, and review-app setup",
  "repository": "https://github.com/example/example-app",
  "keywords": ["rails", "example"],
  "env": {
    "RAILS_ENV":         { "value": "production" },
    "RAILS_MASTER_KEY":  { "required": true, "description": "Rails encrypted credentials key" },
    "SECRET_KEY_BASE":   { "generator": "secret" }
  },
  "addons": [
    "postgresql:hobby-0",
    "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"
  }
}
```

## Tips

* Don't put real secrets in `app.json`. Use `generator: secret` or `required: true` instead.
* For review apps, lean on small plans (`postgresql:hobby-0`, `valkey:hobby-0`) — they don't need production sizing.
* Test the file with a real PR. Most issues only surface when an actual review app spins up.

[View this page on the web](https://docs.watasu.io/reference/app-json/)