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#
| 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#
- Image. Citadel's image is looked up and checked against the catalog. Without it,
parity upstops and says how to get it (parity image get), or that Citadel has not published a download for it yet. - Build. The app image is built from the Dockerfile Citadel's generator would write for this app, step for step.
build.shruns as root with/bin/sh, as on Citadel. - MySQL, when
parity.jsonasks for it, until it answers. - 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). - 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#
- 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
-modifiedwhen the folder has uncommitted changes.
Set it with mode in parity.json, or parity init --mode bake.
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 |
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#
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:
[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#
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.