---
title: "How Parity works | Parity docs"
description: "The three containers parity up starts, mount and bake, what lands in .parity/, and how the output changes between a terminal and a CI log."
url: https://parity.apps.wayne.edu/docs/guides/how-it-works.html
llms: https://parity.apps.wayne.edu/llms.txt
generator: Squire agent-ready
---

# How Parity works [#](https://parity.apps.wayne.edu/docs/guides/how-it-works.html#how-parity-works)

`parity up` starts three containers, writes everything it needs into `.parity/`, and copies Citadel's own files rather than imitating them. This page explains each part.

## The three pieces [#](https://parity.apps.wayne.edu/docs/guides/how-it-works.html#the-three-pieces)

| Piece | What it is | Like Citadel because |
| --- | --- | --- |
| app | Citadel's own PHP image (for example `citadel/php-apache:8.5r3`), Citadel's `vhost.conf` and `php.ini`, your `build.sh` run the way Citadel runs it, your `deployments/` run once each by Citadel's entrypoint, your health check on Citadel's timing, your cron entries run in the app container as `prisoner` | it is Citadel's image and Citadel's files, not a lookalike |
| proxy | HAProxy in front, adding `X-Forwarded-For` and `X-Forwarded-Proto` and stripping nothing | Citadel's proxy does the same, so an app that trusts the wrong hop is caught here |
| mysql | MySQL 5.6.51, on a loopback port only | it is the version of Citadel's shared database server |

The proxy listens on `127.0.0.1` at `http_port` (8080 unless you change it) and MySQL on `127.0.0.1` at `database.port` (3307). Neither is reachable from another computer.

With `"https": true`, the proxy gains a second frontend: an `https-in` listener on 127.0.0.1:8443, a fixed port, that ends TLS and sends `X-Forwarded-Proto: https` to the app, the way Citadel's proxy sends `http` for its HTTP front end. It serves a leaf certificate signed by the app's local CA, one per app, name-constrained to `server_name` and `localhost`. The CA lives in Parity's per-user config folder (`ca/<app>`): `parity up` makes it and renews the leaf when 7 days are left, the key never leaves the folder (mode 0600), and only the leaf lands in the gitignored `.parity/tls/leaf.pem`. `parity trust` puts `ca.crt` in your certificate stores so the browser stops warning.

## What happens on parity up [#](https://parity.apps.wayne.edu/docs/guides/how-it-works.html#what-happens-on-parity-up)

1. **Image.** Citadel's image is looked up and checked against the catalog. Without it, `parity up` stops and says how to get it (`parity image get`), or that Citadel has not published a download for it yet.
2. **Build.** The app image is built from the Dockerfile Citadel's generator would write for this app, step for step. `build.sh` runs as root with `/bin/sh`, as on Citadel.
3. **MySQL**, when `parity.json` asks for it, until it answers.
4. **App.** Citadel's entrypoint runs each file in `deployments/` once, then Apache starts and Parity waits for the health check (up to `--wait`, 5 minutes by default; Citadel allows 5 minutes and 15 seconds).
5. **Proxy**, then the address.

A failure shows the last lines that explain it. The whole build and compose output is in `.parity/up.log` (`--verbose` shows it as it happens).

## Mount and bake [#](https://parity.apps.wayne.edu/docs/guides/how-it-works.html#mount-and-bake)

- **mount** (for developers): your folder is mounted at `/citadel/src`, as Citadel mounts it. Edit a file, reload the page.
- **bake** (for testers): your code is copied into the image, so a tester tests one exact commit. Parity prints which commit, with `-modified` when the folder has uncommitted changes.

Set it with `mode` in `parity.json`, or `parity init --mode bake`.

## The .parity folder [#](https://parity.apps.wayne.edu/docs/guides/how-it-works.html#the-parity-folder)

Everything Parity writes goes into `.parity/` in the app. It ignores itself in git and is rewritten on every `parity up`:

| File | What it is |
| --- | --- |
| `compose.yaml` | the three containers, as compose project `parity-<name>` |
| `app.Dockerfile` | the Dockerfile Citadel's generator would write for this app |
| `vhost.conf`, `php.ini` | Citadel's own, copied unchanged from Citadel's repository (MIT) |
| `haproxy.cfg` | the proxy's settings |
| `up.log` | the build and compose output of the last `parity up` |
| `mysql.env` | the local MySQL passwords, made once and kept so the database keeps opening |
| `app.env` | the app container's environment: Laravel's `DB_*` names for the local MySQL, then SESAME's names for `sign_in` |
| `cron/` | the cron loop and its table, when the app has [cron entries](https://parity.apps.wayne.edu/docs/reference/parity-json.html#cron-entries) |

`app.env` beats the app's own `.env`, which Parity never touches. On Citadel the app reads its own configuration file instead. Because each app is its own compose project, two apps never collide; give them different ports.

## Output in a terminal and in a log [#](https://parity.apps.wayne.edu/docs/guides/how-it-works.html#output-in-a-terminal-and-in-a-log)

On a terminal Parity uses color, symbols and live spinners. It drops them on its own when the output is a pipe, a file or a CI log, and prints plain tags instead:

```text
  [FAIL] No container engine is installed (Parity looked for docker and podman).
  [ OK ] No Windows line endings in the files Citadel runs.
```

| You want | Use |
| --- | --- |
| plain tags on a terminal | `--plain` anywhere on the line, or `PARITY_PLAIN=1` |
| no color, symbols kept | `NO_COLOR=1` |
| symbols and color in a log | `PARITY_STYLE=fancy` |
| something for a script | `--json` on `check`, `status`, `test`, `image list`, `version` |

In the classic Windows console Parity turns on its color mode and uses symbols the console's fonts have.

## Why a Go program [#](https://parity.apps.wayne.edu/docs/guides/how-it-works.html#why-a-go-program)

Parity must run where there is no PHP, drive the container engine and check OS settings. That is where PHP would be silly, so the command line is Go: one static binary per OS and architecture, standard library first. The templates are embedded in the binary, so upgrading Parity upgrades every app's stack and nothing drifts in your repository. The decision is recorded in the stack's ADR-0022.
