---
title: "parity.json | Parity docs"
description: "Every field of parity.json, the one file Parity adds to an app, with the Citadel setting each one mirrors and its default."
url: https://parity.apps.wayne.edu/docs/reference/parity-json.html
llms: https://parity.apps.wayne.edu/llms.txt
generator: Squire agent-ready
---

# parity.json [#](https://parity.apps.wayne.edu/docs/reference/parity-json.html#parity-json)

The one file Parity adds to your app. Its fields mirror Citadel's app settings page, so filling it in is copying the dashboard. `parity init` writes it from what is in the folder; every field has a default except `name`.

It holds settings, never secrets. Commit it.

## An example [#](https://parity.apps.wayne.edu/docs/reference/parity-json.html#an-example)

What `parity init --print` writes for `testdata/hello`, the smallest app in Parity's repository:

```json
{
  "version": 1,
  "name": "hello",
  "image": "citadel/php-apache:8.5r3",
  "public_dir": "public",
  "mode": "mount",
  "build_script": "build.sh",
  "deployments": "deployments/",
  "health_check": "php health.php",
  "environment": "local",
  "server_name": "hello.apps.wayne.test",
  "time_zone": "America/Detroit",
  "http_port": 8080,
  "database": {
    "mysql": false
  },
  "sign_in": "none"
}
```

## Fields [#](https://parity.apps.wayne.edu/docs/reference/parity-json.html#fields)

| Field | Citadel's setting | Default |
| --- | --- | --- |
| `version` | (Parity's) the file format | `1` |
| `name` | the app (names the containers: compose project `parity-<name>`) | the folder's name |
| `image` | base image | `citadel/php-apache:8.5r3` |
| `public_dir` | public directory, relative to the app | `public` when there is one, else `.` |
| `mode` | (Parity's) `mount` or `bake` | `mount` |
| `build_script` | build script | `build.sh` when there is one |
| `deployments` | deployments folder | `deployments/` when there is one |
| `health_check` | health check command, run from the app folder | `php health.php` or `./health-check` when there is one |
| `cron` | cron entries: `name` (short name), `schedule` (five fields), `command` (see [Cron entries](https://parity.apps.wayne.edu/docs/reference/parity-json.html#cron-entries)) | Laravel's scheduler when the app schedules anything, else none |
| `writable` | writable paths: Apache's group, group-writable, as Citadel's deploy leaves them (baked into the image in bake mode; set as the container starts in mount mode) | Laravel's `storage` and `bootstrap/cache` |
| `config_files` | configuration files: `path` and `required_keys` | none |
| `environment` | environment | `local` |
| `server_name` | host name | `<name>.apps.wayne.test` |
| `time_zone` | time zone | `America/Detroit` |
| `http_port` | (Parity's) the proxy's port on 127.0.0.1 | `8080` |
| `https` | (Parity's) serve https for `server_name` (and `localhost`) on 127.0.0.1:8443, a fixed port, with a leaf from the app's local CA; `http_port` and `database.port` must not be 8443 while it is on | `false` |
| `database` | MySQL: `mysql` (yes or no), `name`, local `port` | no MySQL; when yes, database `app` on port `3307` |
| `sign_in` | (Parity's) `none`, `fake` (SESAME's fake driver) or `cas` (see [Sign-in](https://parity.apps.wayne.edu/docs/reference/parity-json.html#sign-in)) | `none` |
| `fake_user` | (Parity's) who the fake driver signs in | `jdoe` |
| `test.requests` | (Parity's) extra requests for `parity test`: `path`, `status`, `contains` | none |
| `test.tools` | (Parity's) commands `parity test` runs in the app container as user `citadel`, in order, before its HTTP checks; the first failure stops the run | none |

## Rules [#](https://parity.apps.wayne.edu/docs/reference/parity-json.html#rules)

- **Unknown fields are an error**, so a typo is caught rather than ignored.
- **Paths** may not hold `$`, backquotes, double quotes or line breaks, and `health_check` is one line, because they land in a Dockerfile and a shell.
- **Required keys** in `config_files` are named the way the file names them: `section.key` for ini files, `NAME` for env files, `a.b` for JSON. `parity check` says whether each is filled in and never prints a value. A configuration file is never baked into an image.

## Mount or bake [#](https://parity.apps.wayne.edu/docs/reference/parity-json.html#mount-or-bake)

- **mount** (for developers): your folder is mounted at `/citadel/src`, as Citadel mounts it. Edit, reload.
- **bake** (for testers): your code is copied into the image, so a tester tests one exact commit, and Parity says which (with `-modified` when the folder has changes). `writable` names the folders Apache may write to.

## Sign-in [#](https://parity.apps.wayne.edu/docs/reference/parity-json.html#sign-in)

`sign_in` puts SESAME's own settings in the app container's environment (`.parity/app.env`). A real environment variable beats `.env` in Laravel and in SESAME's raw PHP settings, so your `.env` keeps whatever it says and Parity never writes to it.

| `sign_in` | The app gets | Needs |
| --- | --- | --- |
| `none` | nothing; the app's own settings decide | nothing |
| `fake` | `SESAME_DRIVER=fake`, `SESAME_FAKE_USERNAME` (`fake_user`, default `jdoe`) | a local `environment` (below) |
| `cas` | `SESAME_DRIVER=cas`, `SESAME_CAS_SERVICE_URL=https://<server_name>/login` (SESAME's Laravel `/login` route) | `server_name` on wayne.edu, pointed at 127.0.0.1 in your hosts file, and `"https": true`, so Parity serves https for `server_name` on 127.0.0.1:8443 |

`fake` needs `environment` set to `local`, `development`, `dev`, `testing` or `test`, because SESAME's fake driver refuses to boot anywhere else. CAS sends its ticket back only to an https address on a name it knows. `SESAME_CAS_BASE_URL` is left to the app's settings or the playbook, which carry the university's CAS server. For `cas`, set `"https": true`: Parity serves https for `server_name` on 127.0.0.1:8443, and one run of `parity trust` makes your browser trust the app's local CA. The hosts-file step stays, because CAS must see a name it knows. `fake` is the everyday local choice.

```json
{
  "sign_in": "fake",
  "fake_user": "jdoe"
}
```

## Cron entries [#](https://parity.apps.wayne.edu/docs/reference/parity-json.html#cron-entries)

Citadel offers apps no queue worker and no long-running services. It offers cron entries, each a short name, a schedule and a command. Citadel's host runs each one as `docker exec -u prisoner <your app container> <command>` and keeps its output in `logs/cron-jobs/<name>.stdout.log` and `<name>.stderr.log`. Parity does the same, inside the app container, as `prisoner`, with the container's environment, from `/citadel/src`:

```json
"cron": [
  {
    "name": "schedule",
    "schedule": "* * * * *",
    "command": "php artisan schedule:run"
  }
]
```

- **The schedule takes what Citadel's dashboard takes:** minute and hour as `*`, `*/N` or a list (`0,30`); day of month, month and day of week as `*` or a list (Sunday is `0` or `7`). No ranges, no `MON`, no `@hourly`. If your crontab has a range, it now has a list.
- **The command is one simple command.** Citadel writes it into the host's crontab after `docker exec`, so the host's shell reads the line: a `;`, `&&`, `|`, `>` or `$` there would act on the host, outside your app. Parity refuses those. Put the steps in a script in the app and name it (`sh bin/nightly.sh`).
- **Output:** `parity logs cron:<name>` shows the two files, as Citadel's dashboard does, and `parity logs app` shows each run as it happens ([parity logs](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-logs)).
- **How Parity runs them:** a small loop (`.parity/cron/cron.php`, in PHP because every Citadel image has PHP) starts as `prisoner` beside Apache once Citadel's entrypoint has run the deployments, and starts each due entry with `/bin/sh` at the top of the minute, as cron does. Copying Citadel exactly, with a sidecar that runs `docker exec`, would need the container engine's socket inside a container (root on your computer). The loop gives the command the same container, user, environment and folder without it.
- **Queues:** there is no worker service, on Citadel or here. A Laravel app drains its queue from the scheduler:
  ```php
  Schedule::command('queue:work --stop-when-empty --tries=5 --timeout=600')
      ->everyMinute()
      ->withoutOverlapping(15)
      ->runInBackground();
  ```
  `parity init` (and `--from-squire`) proposes the `schedule` entry above when `routes/console.php`, `bootstrap/app.php` or `app/Console/Kernel.php` schedules anything, or the Squire kit has a scheduler service. `--no-cron` leaves it out.

## Test requests [#](https://parity.apps.wayne.edu/docs/reference/parity-json.html#test-requests)

```json
{
  "test": {
    "requests": [
      { "path": "/rooms.php?building=STATE", "status": 200, "contains": "State Hall" },
      { "path": "/admin/", "status": 302 }
    ]
  }
}
```

A request passes on any answer below 500 unless it names a `status`, and must contain `contains` when it names one. Redirects are not followed, so a redirect is checked as the redirect.

## Test tools [#](https://parity.apps.wayne.edu/docs/reference/parity-json.html#test-tools)

```json
{
  "test": {
    "tools": [["composer", "ci"], ["php", "artisan", "test"]]
  }
}
```

Each entry is one command as an argument list. `parity test` runs the tools in the app container as user `citadel`, in the order listed, before its HTTP checks, with their output going straight to your terminal. The first failing tool stops the run: the later tools and the HTTP checks do not run, and `parity test` exits 1.
