# Parity: everything in one file > Parity runs Citadel's own PHP image, Citadel's proxy and MySQL 5.6 on your Windows, macOS or Linux computer, so an app that works locally works on Citadel. One program, one parity.json, no PHP needed. The README and the Markdown twin of every page, joined. The index is https://parity.apps.wayne.edu/llms.txt. Written by Squire's agent-ready kit; do not edit. --- ## README Source: https://git.wayne.edu/enterprise-apps/parity/blob/HEAD/README.md ## Parity **Run Citadel on your own computer.** Citadel's PHP image, Citadel's proxy and MySQL 5.6, on your laptop, so an app that works here works on Citadel. "Works on my machine" finally means something, because your machine is now Citadel's twin. Parity is one program, `parity`, for Windows, macOS and Linux (x64 and arm64). It needs a container engine, Podman Desktop (recommended, free) or Docker Desktop if you already have it, and nothing else: no PHP, no Composer, no files in your app beyond one `parity.json`. `parity check` also knows the other engines people already run (see [Docker or Podman](#docker-or-podman)). > Parity is a mirror, not a portrait: it shows Citadel as Citadel is, including the parts you would rather it did not. ### Quick start In your app's folder: ```text parity check tells you what to fix, one finding per line, with the fix under it parity init writes parity.json (your app's Citadel settings) parity image get downloads Citadel's image and checks it is Citadel's, byte for byte parity up builds and starts the app behind the proxy, then prints its address parity test smoke tests the running app through the proxy parity down stops it (your data stays) ``` Parity runs Citadel's own image and nothing else, because the whole point is to match Citadel. If Citadel has not published a download for your app's image yet, Parity says so and tells you what to do next. It will not hand you a look-alike and call it a twin; Citadel would never fall for that, and neither should you. Rather click than type? The desktop app comes after 1.0. It is not released yet: it is one window over the same Go code these commands run, and the [front page](https://parity.apps.wayne.edu/#commands) shows its screens next to each command's printout ([the desktop app guide](https://parity.apps.wayne.edu/docs/guides/desktop-app.html) has more). ### Install | OS | Install | |---|---| | Windows (PowerShell) | `irm https://parity.apps.wayne.edu/install.ps1 \| iex` | | macOS, Linux | `curl -fsSL https://parity.apps.wayne.edu/install.sh \| sh` | | Any | a download per OS and arch from `https://parity.apps.wayne.edu/downloads/`, with `checksums.txt` | The installers fetch the newest release, check its sha256 against the release's `checksums.txt` before installing anything, and need no administrator. That check catches a corrupted or partial download. It does not prove the download is genuine: `checksums.txt` comes from the same site as the archive, so a site serving a bad archive could serve a matching sum too. Signing comes before the desktop app, which follows 1.0. - **Windows** puts `parity.exe` in `%LOCALAPPDATA%\Programs\parity` and adds that folder to your own (user) PATH, once: a second run updates `parity.exe` and says it is already on your PATH. - **macOS and Linux** put `parity` in `~/.local/bin`. The script never edits your shell's profile. If `~/.local/bin` is not on your PATH it prints the one line to add, then you open a new terminal: ```text bash or zsh (~/.bashrc or ~/.zshrc): export PATH="$HOME/.local/bin:$PATH" fish (~/.config/fish/config.fish): fish_add_path "$HOME/.local/bin" ``` A folder you name with `--dir` (or `PARITY_INSTALL_DIR`) wins. If you cannot write it (`/usr/local/bin`, say), sudo asks for your password for the copy, and only for the copy. A version, a folder, or no PATH change (`-NoPath` on Windows; `PARITY_NO_PATH=1` on either, which on macOS and Linux drops the hint): ```text & ([scriptblock]::Create((irm https://parity.apps.wayne.edu/install.ps1))) -Version 0.1.0 -InstallDir C:\tools\parity -NoPath curl -fsSL https://parity.apps.wayne.edu/install.sh | sh -s -- --version 0.1.0 --dir ~/bin curl -fsSL https://parity.apps.wayne.edu/install.sh | PARITY_NO_PATH=1 sh ``` The files are `parity___.tar.gz` (`.zip` on Windows) for `windows`, `darwin` and `linux`, each `amd64` and `arm64`, on Parity's site under `downloads//` (and `downloads/latest/` for the newest). Or build it from this repository (below), or take a binary from a pipeline's `build` job. 0.1.0 ships unsigned, with checksums. Signed binaries come before the desktop app, which follows 1.0. Until then, a zip downloaded in a browser may meet SmartScreen ("More info", then "Run anyway", or `Unblock-File parity.exe`), and on a Mac an archive downloaded in a browser needs `xattr -d com.apple.quarantine parity`. The installers avoid both. ### Docker or Podman Parity drives either, and recommends **Podman**: it is free (Docker Desktop needs a paid subscription at a university this size), it runs rootless by default, and Podman Desktop gives Windows and macOS a window to run it from. Docker Desktop works as well as ever, and so does any engine that answers the `docker` command (Rancher Desktop, OrbStack, Colima, Docker Engine); Parity just stops suggesting them. Either way the bubble sits in the middle. | OS | Install Podman | |---|---| | Windows | `winget install --id RedHat.Podman-Desktop -e`, then open Podman Desktop and let it set up Podman and its machine (WSL 2) | | macOS | `brew install --cask podman-desktop`, then the same | | Linux | your distribution's packages: `sudo dnf install podman docker-compose` (Fedora, RHEL) or `sudo apt-get install podman docker-compose-v2` (Ubuntu), then `systemctl --user enable --now podman.socket` | - **Which one Parity uses:** the engine that is running. With both running it takes Docker, so an existing Docker setup keeps its databases, and `parity check` names the other. `parity engine podman` (or `docker`) saves a choice for every app and the desktop app; `PARITY_ENGINE` overrides it for one terminal; `auto` is the default. - **Compose:** Parity drives Docker Compose v2 on both engines; on Podman, `podman compose` runs it. podman-compose (the Python program) is a different tool, and Parity refuses it rather than half-work with it: `parity check` says how to get Docker Compose. On Linux, Compose reaches Podman through Podman's API socket, which the `systemctl` line above starts. Builds on Podman use the classic builder, because BuildKit's builder container cannot see the images Podman holds; Parity sets that for you. - **Rootless Podman and your files (mount mode):** rootless means the container's root is you, not the computer's root. Parity runs the app with `userns_mode: keep-id`, mapped to the image's `citadel` user, so inside the container your files belong to `citadel`, as the source owner on Citadel, and the container still starts as root, as on Citadel. As it starts, Parity gives the writable paths to Apache's group, group-writable, as Citadel's deploy does, so Apache (`prisoner`), the deployments (`citadel`) and the cron entries (`prisoner`) can all write them. Files Apache writes show on your side with a high user id from your subuid range; you can still delete them. Parity does not use Podman's `:U` mount option, which would hand your folder on your own disk to the container's ids. - **Health checks:** Docker checks a starting container every 3 seconds (`start_interval`); Podman has no such setting and, after a failed first check, waits the full 5 minutes. So on Podman `parity up` asks for a check while it waits. - **Windows:** Podman runs in its own WSL 2 machine. Your folders are mounted into it, so a Windows path works as it is, ports on `localhost` reach your browser, and edits show on the next request. A folder on the Windows disk is slow in mount mode, because every file read crosses into WSL 2; `parity check` warns about it (`mount-speed`). Use bake mode for `parity test`, or keep the app in the WSL filesystem. Inside the container, files on the Windows disk show as one owner with every permission (WSL's drvfs), so ownership questions do not come up. If `parity check` says the machine is running but Podman in it is not answering, it says what to do: on a PC that also runs Ubuntu with systemd in WSL, the two distros' user 1000 can collide (WSL distros share one cgroup tree). - **Apple Silicon:** Citadel's images are amd64 only. Podman's machine runs them with Rosetta when Rosetta is on (Podman 5.6 shipped with it off), else on slower QEMU emulation, which works. `parity check` gives the steps to turn Rosetta on (macOS 26 or later). The Podman path is proven end to end on Linux (rootful and rootless, through `podman compose` and through `docker compose` on Podman's socket) and on Windows (Podman Desktop's rootless machine and Docker Desktop, mount and bake, on Citadel's real 8.5r3 image, 2026-11-10). macOS is the run still owed on the release checklist ([MAINTAINING.md](https://git.wayne.edu/enterprise-apps/parity/blob/HEAD/MAINTAINING.md), "Checklist runs"). ### What Parity runs | 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; with `"https": true` it also serves https for `server_name` (and `localhost`) on 127.0.0.1:8443 | 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 (no JSON columns, indexed strings stop at 191 characters) | Two ways to put your code in the app container, set by `mode` in `parity.json`: - **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). ### Commands Exit codes, as PROCTOR and Squire: **0** pass, **1** findings or a failed test, **2** cannot run (usage, no engine, no config). `--json` on the read commands is the stable contract. | Command | Status | |---|---| | `parity check [--json]` | works: engine (Podman, machine or native, rootless or rootful; Docker Desktop; anything that answers the `docker` command) and any other engine that is here, `PARITY_ENGINE`, Docker Compose v2 (and Podman's API socket on Linux), Linux containers mode, WSL 2, arm64 emulation (Rosetta, QEMU), Windows line endings in the files Citadel runs; with a `parity.json` and a running engine it ends with the same side-by-side as `parity status` | | `parity init [--from-squire] [--print]` | works: writes `parity.json` from what is in the folder (with Laravel's scheduler as a cron entry when the app schedules anything); flags `--image`, `--public-dir`, `--mode`, `--mysql`, `--no-mysql`, `--sign-in`, `--health-check`, `--no-cron`, `--port`, `--name`, `--force` | | `parity up [--verbose] [--wait 5m]` | works: Citadel's image (checked against the catalog), the build, MySQL 5.6.51, the app's deployments and health check, the proxy, then the address. Exit 1 when the app's own build, deployments or health check failed, 2 when Parity could not run it (no engine, no image, a port taken) | | `parity status [--json]` | works: each piece and its health, then your machine and Citadel side by side (image, image id, PHP, platform, php.ini, MySQL, Node, PHP extensions). Exit 0 when all run and are healthy, 1 when not | | `parity logs [app\|mysql\|proxy\|cron:] [-f] [--tail 100] [--apache]` | works; `--apache` shows Apache's own logs from `/citadel/logs/apache`, where Citadel keeps them; `cron:` shows a cron entry's stdout and stderr files from `/citadel/logs/cron-jobs` | | `parity shell [--user citadel] [command...]` | works: a shell (or one command) in the app container, in `/citadel/src` | | `parity down [--volumes]` | works: stops the app; the database stays unless `--volumes` | | `parity image list [--json]` | works: the Citadel images Parity knows, and whether each is here and matches | | `parity image get [tag] [--file x.tar] [--git] [--https] [--keep] [--force]` | works: downloads Citadel's image with your own git.wayne.edu access, checks its sha256 and image id, loads it | | `parity image verify [tag] [--file x.tar]` | works: the image here (or a tar) against Citadel's. Exit 1 when it differs | | `parity test [--json]` | works: the front page through the proxy, the app's health check, the requests in `parity.json`, and no PHP fatal error in Apache's log while it ran. Exit 1 when any fails | | `parity trust [--remove]` | works: puts the app's local https certificate authority in this computer's certificate stores, so the browser stops warning about the app's https address on 127.0.0.1:8443; Windows and macOS work on your user store, Linux prints the sudo commands and updates Chrome's NSS database when it can; `--remove` takes it out again | | `parity run [--user citadel] [--] command [args...]` | works: runs a tool (`composer ci`, `php artisan test`, `npm run build`) in the app container as user citadel and returns its exit code; in bake mode it says the files it writes vanish on the next `parity up` | | `parity engine [podman\|docker\|auto] [--json]` | works: says which engine Parity uses and why, or saves the choice for this computer (the desktop app reads the same setting); `PARITY_ENGINE` still wins where it is set | | `parity version [--json]` | works | `parity check` prints one line per finding and, under each one that needs it, the one fix Parity recommends for your OS. It changes nothing. On this Windows PC with Docker Desktop: ```text Parity check C:\Users\you\Development\my-app ✓ Docker Desktop 29.9.2 is running (linux/amd64, context desktop-linux). ✓ Docker Compose 5.6.1 is here. ✓ Linux containers, on WSL 2. ✓ This machine runs Citadel's amd64 images natively. Ready. This computer can be Citadel's twin. ``` With a `parity.json`, `parity check` and `parity status` end with your machine and Citadel side by side, row for row what the desktop app shows. Node and the PHP extensions come from `php -m` and `node -v` in the running app container (or else the app image), compared with the catalog: Node is Close when only the minor differs, an extension that is missing Differs and one Citadel lacks is Close. The `--json` output does not change. ```text Your machine and Citadel citadel/php-apache:8.5r3 YOUR MACHINE CITADEL ✓ Image citadel/php-apache:8.5r3 citadel/php-apache:8.5r3 match ✓ Image id sha256:950dcf67937a sha256:950dcf67937a match ✓ PHP 8.5.12 8.5.12 match ✓ Platform linux/amd64 linux/amd64 match ✓ php.ini Citadel's php8.ini Citadel's php8.ini match ✓ MySQL 5.6.51 5.6.51 match ✓ Node 22.23.4 22.23.4 match ✓ PHP extensions 50 loaded 50 loaded match Node and PHP extensions read from the app image. Matches Citadel. ``` `parity up` brings each piece to life in turn and says what it did. On the same PC, `testdata/hello` with Citadel's own image (a terminal shows a spinner on the step in progress; times show for steps over 2 seconds): ```text Parity up hello on citadel/php-apache:8.5r3 ✓ Image citadel/php-apache:8.5r3 matches Citadel (950dcf67937a) ✓ Build app image built; build.sh ran as root with /bin/sh 4s ✓ MySQL 5.6.51 is ready on 127.0.0.1:3307, database hello 10s ✓ App deployments ran, and healthy: php health.php said yes 4s ✓ Proxy HAProxy answers, adding X-Forwarded-For and X-Forwarded-Proto as Citadel's does hello is up at http://localhost:8080 Citadel's twin is awake. Edits in this folder show on the next request. MySQL 127.0.0.1:3307, database hello, user app (password in .parity/app.env) Logs parity logs -f Stop parity down ``` When the image is not on this computer, `parity up` stops at the Image line with exit 2. The hint is `parity image get`, or, when Citadel has not published a download for that tag yet, a line that says so: pick an image Parity can get, or ask the Citadel team to publish it. #### Getting Citadel's image Citadel's images are `docker save` tars in git LFS in `enterprise-apps/images` on git.wayne.edu, so getting one takes your own access there. `parity image get` tries, in order: a tar you name with `--file` (downloaded from the project's page in your browser), a personal access token in `PARITY_GITLAB_TOKEN` (`read_repository` is enough), then git LFS over SSH with your own key (`--https` for git's credential manager instead). The git route needs git LFS set up once: install git-lfs (it ships with Git for Windows and Homebrew has `git-lfs`), then run `git lfs install`; without it git fetches a small pointer file and Parity says so. Only the one tar is fetched, never the whole repository. Whatever the route, the tar's sha256 and the loaded image's id must match the catalog inside Parity before Parity calls it Citadel's: ```text Parity image get citadel/php-apache:8.5r3 ✓ Fetch 379 MB with git LFS from git.wayne.edu (enterprise-apps/images) 30s ✓ sha256 61cbd26f1912 matches Citadel's tar ✓ Load loaded into docker 28s ✓ Id 950dcf67937a matches Citadel citadel/php-apache:8.5r3 is Citadel's own, byte for byte. Next: parity up ``` The download goes to your cache folder and is deleted once loaded (`--keep` keeps it). A token is read from the environment only and never printed. #### Testing it `parity test` asks the running app what Citadel's users would. On `testdata/hello`: ```text Parity test hello at http://localhost:8080 ✓ GET / 200 in 8ms ✓ Health check php health.php said yes ✓ GET / 200, has "Citadel's twin" ✓ GET / 200, has "X-Forwarded-Proto: http" ✓ GET / 200, has "MySQL 5.6.51" ✓ PHP errors no fatal errors while testing All 6 passed. Citadel would not notice the difference. ``` A request in `test.requests` 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. #### What `parity up` writes Everything goes into `.parity/` in the app, which ignores itself in git and is rewritten on every `parity up`: `compose.yaml`, `app.Dockerfile` (the Dockerfile Citadel's generator would write for this app, step for step), Citadel's own `vhost.conf` and `php.ini` (copied unchanged from Citadel's repository, MIT), the proxy's `haproxy.cfg`, `up.log` (the build and compose output), the local MySQL passwords in `mysql.env` (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`), and `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. The containers are the compose project `parity-`, so two apps never collide (give them different ports). #### Output 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 (plain `[ OK ]`, `[WARN]`, `[FAIL]` tags), when `NO_COLOR` is set (no color), and with `--plain` anywhere on the line (or `PARITY_PLAIN=1`). `PARITY_STYLE=fancy` keeps symbols and color in a log. In the classic Windows console Parity turns on its color mode and uses symbols the console's fonts have. ### 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; everything has a default but `name`. | Field | Citadel's setting | Default | |---|---|---| | `name` | the app (names the containers) | 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; for Laravel, the `health:` route in `bootstrap/app.php` (`/up`); else Apache must answer `/` | | `cron` | cron entries: `name` (short name), `schedule` (five fields), `command` (see [Cron entries](#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` (ini `section.key`, env `NAME`, json `a.b`) | none | | `environment`, `server_name`, `time_zone` | environment, host name, time zone | `local`, `.apps.wayne.test`, `America/Detroit` | | `http_port` | (Parity's) the proxy's port on 127.0.0.1 | `8080` | | `database` | MySQL: `mysql` yes or no, `name`, local `port` | no MySQL; when yes, `app` on `3307` | | `sign_in` | (Parity's) `none`, `fake` (SESAME's fake driver) or `cas` (see [Sign-in](#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 | It holds settings, never secrets. Configuration files are checked for their required keys by name; Parity never prints a value. Unknown fields are an error, so a typo is caught rather than ignored. #### 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`) | `environment` of `local`, `development`, `dev`, `testing` or `test`, because SESAME's fake driver refuses to boot anywhere else | | `cas` | `SESAME_DRIVER=cas`, `SESAME_CAS_SERVICE_URL=https:///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: 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` in `parity.json`: Parity then 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 still the everyday local choice. #### 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 ` and keeps its output in `logs/cron-jobs/.stdout.log` and `.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`). Citadel's schedules are level-headed: no ranges, no `MON`, no `@hourly`. If your crontab has a range, it now has a list, and a moment of quiet reflection. - **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:` shows the two files, as Citadel's dashboard does. `parity logs app` shows each run as it happens: `cron: >` the command started, `|` a line of its output, `!` a line of its errors, `<` how it ended. - **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. Parity could have copied Citadel's mechanism exactly, with a sidecar that runs `docker exec`, but that needs the container engine's socket inside a container (root on your computer) and a different socket under rootless Podman. 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, which is what Citrus does in `routes/console.php`: ```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. #### Node and Vite Citadel's images carry Node (22 in `8.5r3`), so there is no Node service: build the front end in the app container, as the user who owns the code, the way a deployment script would on Citadel: ```text parity shell --user citadel sh -c 'npm ci && npm run build' ``` The built files land in your folder (mount mode) and Apache serves them on the next request. Vite's dev server and hot reload are not part of Citadel, so run `npm run dev` on your own computer if you want them. #### Road to 1.0 The 1.0 command set: `check`, `init` (with `--from-squire`), `up`, `down`, `status`, `logs`, `shell`, `test`, `trust`, `image list|get|verify`, `engine` and `version`. Before the tag: - One real `parity up` and `parity test` on an Apple Silicon Mac, with Podman and with Docker. Windows is done (2026-11-10, Podman and Docker Desktop); that run found three bugs, all fixed before 1.0 (see the CHANGELOG). `go run ./tools/checklist -engine podman` (then `-engine docker`) runs the whole check on that Mac and prints the row for MAINTAINING's table. - 1.0 ships unsigned, with checksums, like 0.1.0. - Citadel's 8.4r5 image is the one outside dependency: until its tar exists, 1.0 offers 8.5r3 only. #### Local HTTPS With `"https": true` in `parity.json`, Parity serves https for `server_name` (and `localhost`) on 127.0.0.1:8443, a fixed port, with a leaf from the app's own local CA: one CA per app, name-constrained to the app's names, kept in your config folder, its key never leaving it. Run `parity trust` once per computer and the browser stops warning; `parity trust --remove` takes it out again. In CI nobody has run `parity trust`, and that is fine: `parity test` loads the home page over https pinned to the app's CA, and `parity check`'s `https.trust` finding warns but never fails, so an untrusted CA keeps CI green. #### After 1.0 - **Commands:** `reset`, `eject`, `image pin` and `image build`. - **The desktop app**, one window over the same Go code. Signing (Authenticode, Apple Developer ID) comes before it. - **Packages:** winget, Homebrew and deb/rpm. A second database is not on the list: Parity runs one MySQL 5.6, as Citadel gives one database per app. An app that reads a second database (a one-time import from an older app, say) points that connection at a test copy its data owner approves, in its own settings. #### Coming from Squire's parity kit `parity init --from-squire`, in the folder with `docker-compose.squire.yml`, carries the kit's settings over (base image, public folder, ports, database name, time zone, deployments) from the compose file, `.env.squire.example` and `.env.squire`. Passwords and every other variable are left behind by name: Parity makes its own local passwords. It lists the kit's files and deletes none of them. Two differences to expect: Parity runs Citadel's own `php.ini`, not the kit's hardened one, because that is what Citadel runs; and the kit's portable `scheduler` and `worker` services become one cron entry, `php artisan schedule:run` every minute, because Citadel has cron and no services. ### Fake data only Parity ships no data connectors, no credentials and no data. `parity test` runs on your app's own fake fixtures. A local copy may point only at a test database its data owner approves, never production, and never real student or employee data copied to a laptop (FERPA). Parity never prints a configuration value and never bakes a configuration file into an image. ### Where it fits in WELD WELD is the Wayne State application stack. Parity is its "run Citadel locally" layer. | Part | Job | |---|---| | WayneUI (project 0) | The interface layer every app renders | | CREED | The version policy | | PROCTOR | Measures an app against that policy | | Preflight | The CI templates | | SESAME | Sign-in; its fake driver is how a local copy signs in without CAS | | HELMET | The baseline runtime | | Pinstripe | The coding standard | | Sourdough | The starters (each app's README tells you to run `parity init --from-squire`, which writes `parity.json`) | | Booster | Moves apps forward; a PHP upgrade is exactly when Citadel's real image matters | | Squire | Gets the app onto Citadel (`build.sh`, `deployments/`, `release.sh`); Parity runs those files the way Citadel does | | Parity | This project: Citadel on your computer | Parity depends on nothing in the stack. Squire's docs point at Parity; nothing calls it. ### Why it is built this way Recorded in the stack's ADR-0022 (accepted 2026-11-09): - Parity is its own project because people will use it without Squire: Squire gets the app onto Citadel, Parity runs Citadel on your computer. - The command line is Go, one static binary per OS and arch, because it must run where there is no PHP, drive the container engine and check OS settings. That is where PHP would be silly. Standard library first. - Configuration is `parity.json`, mirroring Citadel's app settings, so filling it in is copying the dashboard. - Templates are embedded in the binary and rendered into a gitignored `.parity/` folder, so upgrading Parity upgrades every app's stack and nothing drifts in your repository. - Citadel's images come from the Git LFS tars in `enterprise-apps/images` on git.wayne.edu, checked by sha256 and image id from a catalog inside the binary. - CI is split: Linux on git.wayne.edu on every push; Windows and macOS on a private GitHub mirror on tags; a real Mac and this Windows PC prove `up` before each release. ### Build it With Go 1.26 or newer: ```text go test ./... go build -o parity ./cmd/parity (parity.exe on Windows) go run ./tools/build all six binaries into dist/, with checksums.txt go run ./tools/checklist the release checklist's up, test and down on this computer (MAINTAINING.md) ``` Or with Docker only, the same image CI uses: ```text docker run --rm -v "${PWD}:/src" -w /src -v stack-go-cache:/go -e GOCACHE=/go/build-cache golang:1.26.11-trixie@sha256:fa340cb59ebeb1d53ac1cccfc334201d938fe5f3458003cccb767096d8e032b8 go run ./tools/build ``` ### Where the code lives The canonical repository is [enterprise-apps/parity](https://git.wayne.edu/enterprise-apps/parity) on git.wayne.edu: issues, merge requests and tags happen there. A private GitHub repository receives a push mirror for Windows and macOS CI only; nobody pushes to it. The website and docs, https://parity.apps.wayne.edu/, are built from `site/` and `docs/` in this repository (MAINTAINING.md, "The site"). Maintaining, releasing and the release checklist: [MAINTAINING.md](https://git.wayne.edu/enterprise-apps/parity/blob/HEAD/MAINTAINING.md). Changes: [CHANGELOG.md](https://git.wayne.edu/enterprise-apps/parity/blob/HEAD/CHANGELOG.md). License: MIT. Parity: because "it worked locally" should be a promise, not an alibi. --- Source: https://parity.apps.wayne.edu/ Citadel, on your own computer WELD stack ## Parity Run Citadel on your own computer. Citadel's own PHP image, Citadel's proxy and MySQL 5.6, running on your laptop. An app that works here works on Citadel, so "works on my machine" finally means something: your machine is Citadel's twin. One program for Windows, macOS and Linux. It needs a container engine (Podman or Docker) and one `parity.json` in your app. No PHP, no Composer, nothing else installed. [Install Parity](https://parity.apps.wayne.edu/#install) [Read the docs](https://parity.apps.wayne.edu/docs/) Your machine Compared Citadel Status Image 8.5r3 same as Image 8.5r3 Match id 950dcf67937a same as id 950dcf67937a Match PHP 8.5.12 same as PHP 8.5.12 Match oci8 on same as oci8 on Match MySQL 5.6.51 same as MySQL 5.6.51 Match X-Forwarded-\* same as X-Forwarded-\* Match Matches Citadel. All 6 rows match. Up at http://localhost:8080 Your machine and Citadel, fact by fact, for `testdata/hello` on Citadel's own image. The image id is the proof: same id, same bytes. - **1** program, `parity`, with no PHP to install - **6** builds: Windows, macOS and Linux, each on x64 and arm64 - **5.6.51** the MySQL Citadel's shared server runs - **0** secrets in `parity.json`, ever Side by side ### Your machine, and Citadel, in the mirror. Parity reads both sides the same way and lines up the facts. Citadel's image is checked by its sha256 and its image id against a catalog inside Parity, so "Match" means the same bytes, not the same label. Switch to your own build of the same tag to see the mirror crack: the same label, other bytes, and Parity says so. What Your machine Compared Citadel Status Image citadel/php-apache:8.5r3 same as citadel/php-apache:8.5r3 Match Image id 950dcf67937a same as 950dcf67937a Match PHP 8.5.12 same as 8.5.12 Match Oracle, imagick, mail oci8, imagick, ssmtp same as oci8, imagick, ssmtp Match vhost.conf and php.ini copied from Citadel, unchanged same as the same files Match Users citadel owns the code, prisoner runs Apache same as the same two Match Build build.sh as root, with /bin/sh same as build.sh as root, with /bin/sh Match Deployments deployments/, each once same as deployments/, each once Match Cron entries as prisoner, in /citadel/src, on the minute same as as prisoner, in /citadel/src, on the minute Match Proxy headers X-Forwarded-For and X-Forwarded-Proto, from HAProxy 3.0 same as the same two, from HAProxy 1.5 Match MySQL 5.6.51, on 127.0.0.1 only same as 5.6.51, shared Match Matches Citadel. All 11 rows match. An image can wear Citadel's tag and still not be Citadel's. Built from the same files on another day, it picks up a newer PHP patch and an image id of its own, so Parity calls it "not the build Citadel runs", and `parity image get` swaps in Citadel's own. Parity runs Citadel's images and nothing else. A day with Parity ### Check, then up. Run these in your app's folder. Every printout below is real, from a Windows PC with Docker Desktop and the `testdata/hello` app in Parity's repository. In a pipe or a CI log the symbols turn into plain `[ OK ]` tags. Exit codes match PROCTOR's and Squire's: 0 pass, 1 findings or a failed test, 2 cannot run. Terminal or app, same Parity: the app's buttons call the same Go code these commands run, so the two cannot disagree. The app is not out yet; its screens are from the work in progress, with sample apps. **1 parity check tells you what to fix, one finding per line, with the fix under it** ``` > parity check Parity check C:\Users\you\Development\my-app ✓ Docker Desktop 29.9.2 is running (linux/amd64, context desktop-linux). ✓ Docker Compose 5.6.1 is here. ✓ Linux containers, on WSL 2. ✓ This machine runs Citadel's amd64 images natively. Ready. This computer can be Citadel's twin. ``` ![Parity's app on its first screen, Check this computer: four green checks (Docker Desktop 29.9.2 is running, Docker Compose 5.6.1 is here, Linux containers on WSL 2, Citadel's amd64 images run natively) beside a small mirror of this computer and Citadel that reads Matches Citadel.](https://parity.apps.wayne.edu/assets/app/check-light.webp) **Check this computer**, the screen the app opens on. The same four checks. [Full size: Check this computer](https://parity.apps.wayne.edu/assets/app/check-light.webp) **2 parity init writes parity.json, your app's Citadel settings** ``` > parity init --print { "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" } ``` ![Parity's app, Add an app, asking which folder the app is in: the parity.json Parity would write for hello, shown in full (the image citadel/php-apache:8.5r3, mount mode, port 8080, no MySQL, no sign-in), with Write parity.json and Cancel buttons under it.](https://parity.apps.wayne.edu/assets/app/init-light.webp) **Add an app**. Nothing is written until you press Write parity.json. [Full size: Add an app](https://parity.apps.wayne.edu/assets/app/init-light.webp) **3 parity image get downloads Citadel's image and checks it is Citadel's, byte for byte** ``` > parity image get Parity image get citadel/php-apache:8.5r3 ✓ Fetch 379 MB with git LFS from git.wayne.edu (enterprise-apps/images) 30s ✓ sha256 61cbd26f1912 matches Citadel's tar ✓ Load loaded into docker 28s ✓ Id 950dcf67937a matches Citadel citadel/php-apache:8.5r3 is Citadel's own, byte for byte. Next: parity up ``` ![Parity's app, Settings, Citadel images: citadel/php-apache:8.5r3 with four checked steps (download 379 MB with git LFS, check the file's sha256, load it into the engine, check the image id 950dcf67937a) and the line Matches Citadel, byte for byte. Below it, the Appearance settings for theme and motion.](https://parity.apps.wayne.edu/assets/app/get-light.webp) **Settings, Citadel images**. Get and Verify, with the same four steps. [Full size: Citadel images](https://parity.apps.wayne.edu/assets/app/get-light.webp) **4 parity up starts Citadel's twin: image, build, MySQL, app, proxy, then the address** ``` > parity up Parity up hello on citadel/php-apache:8.5r3 ✓ Image citadel/php-apache:8.5r3 matches Citadel (950dcf67937a) ✓ Build app image built; build.sh ran as root with /bin/sh 4s ✓ MySQL 5.6.51 is ready on 127.0.0.1:3307, database hello 10s ✓ App deployments ran, and healthy: php health.php said yes 4s ✓ Proxy HAProxy answers, adding X-Forwarded-For and X-Forwarded-Proto as Citadel's does hello is up at http://localhost:8080 Citadel's twin is awake. Edits in this folder show on the next request. ``` ![Parity's app with hello running: a Running, match badge, Stop, Open in browser and Run test buttons, the address http://localhost:8080, and the side by side mirror of this computer and Citadel (image, image id, PHP 8.5.12, platform, php.ini, MySQL 5.6.51, Node, PHP extensions), every row Match, ending in Matches Citadel.](https://parity.apps.wayne.edu/assets/app/up-light.webp) **hello, up and matching**. Start and Stop are one button. [Full size: hello, up and matching](https://parity.apps.wayne.edu/assets/app/up-light.webp) **5 parity test smoke tests the running app through the proxy** ``` > parity test Parity test hello at http://localhost:8080 ✓ GET / 200 in 8ms ✓ Health check php health.php said yes ✓ GET / 200, has "Citadel's twin" ✓ GET / 200, has "X-Forwarded-Proto: http" ✓ GET / 200, has "MySQL 5.6.51" ✓ PHP errors no fatal errors while testing All 6 passed. Citadel would not notice the difference. ``` ![Parity's app, the Tests tab for hello: All 6 passed, Citadel would not notice the difference, with the six checks listed (GET / in 8 ms, the health check, three pages with the right content, no fatal PHP errors) and a Run again button.](https://parity.apps.wayne.edu/assets/app/test-light.webp) **Tests**. Run test is the same smoke test, and the same six lines. [Full size: Tests](https://parity.apps.wayne.edu/assets/app/test-light.webp) **? parity help every command, in its own words** ``` > parity help Parity: run Citadel on your own computer. Usage: parity [-C folder] [options] [--plain] Commands: check tell you what to fix before Parity can run Citadel here, one finding per line init write parity.json, the app's Citadel settings (--from-squire reads a Squire kit) up run the app the way Citadel runs it, behind the proxy status show how the app, MySQL and the proxy are doing image list, get or verify Citadel's images (get downloads one and checks it is Citadel's) logs show the app's output (-f follows; --apache shows Apache's own logs; deployments shows the deployment scripts' logs) test smoke test the running app through the proxy (plus the requests in parity.json) shell open a shell in the app container down stop the app (the database stays; --volumes empties it) engine show or save which container engine Parity uses (podman, docker or auto) version print Parity's version Exit codes: 0 pass, 1 findings or a failed test, 2 cannot run. Run `parity --help` for a command's options. ``` ![Parity's app with its command list open over hello, Type a command: Stop hello, Open hello in the browser, Test hello, Show hello's logs, Show hello's parity.json, switch to another app, Add an app and Check this computer, each with the parity command it matches shown on the right.](https://parity.apps.wayne.edu/assets/app/help-light.webp) **Ctrl K** lists every command, each with its `parity` twin. [Full size: the command list](https://parity.apps.wayne.edu/assets/app/help-light.webp) #### No Citadel image yet? Parity runs Citadel's own image and nothing else. If Citadel has not published a download for your app's image yet, Parity says so: pick an image it can get, or ask the Citadel team to publish it. [More on images](https://parity.apps.wayne.edu/docs/guides/images.html#when-citadel-has-not-published-an-image-yet). #### Mount or bake In **mount** mode your folder is mounted at `/citadel/src`, as Citadel mounts it: edit, reload. In **bake** mode the code is copied into the image, so a tester tests one exact commit, and Parity says which. #### Done for the day `parity down` stops it. Your local database stays until you add `--volumes`. Everything Parity writes lives in `.parity/`, which ignores itself in git. Get Parity ### One line per computer. On Windows the install line puts `parity` on your PATH. On macOS and Linux it goes in `~/.local/bin`, and if that folder is not on your PATH yet, the script prints the one line to add (it never edits your shell profile). Then open a new terminal and run `parity check`; it says what, if anything, to fix first. **Windows** In PowerShell: `irm https://parity.apps.wayne.edu/install.ps1 | iex` Needs a container engine on WSL 2: Podman Desktop (recommended, free), or Docker Desktop if you already have it. Podman Desktop: `winget install --id RedHat.Podman-Desktop -e`. Windows on Arm runs Citadel's amd64 images under QEMU emulation, which is slow but real. **macOS** In Terminal: `curl -fsSL https://parity.apps.wayne.edu/install.sh | sh` Needs a container engine: Podman Desktop (recommended, free), or Docker Desktop if you already have it. Podman Desktop: `brew install --cask podman-desktop`. On Apple Silicon, Citadel's amd64 images run emulated; `parity check` says what your engine needs. **Linux** In a shell: `curl -fsSL https://parity.apps.wayne.edu/install.sh | sh` Needs a container engine: Podman (recommended, free, from your distribution's package), or Docker Engine with its Compose plugin if you already have it. On arm64, install QEMU's amd64 emulation once; `parity check` prints the line. #### Or take the file yourself Each archive holds one program, `parity` (`parity.exe` on Windows), with its README, license and changelog. Check it against [checksums.txt](https://parity.apps.wayne.edu/downloads/latest/checksums.txt). 0.1.0 ships unsigned, and so will 1.0; signed binaries come before the desktop app, which follows 1.0. **Downloads of the newest Parity release** | Computer | x64 (Intel, AMD) | arm64 | | --- | --- | --- | | Windows | [parity_windows_amd64.zip](https://parity.apps.wayne.edu/downloads/latest/parity_windows_amd64.zip) | [parity_windows_arm64.zip](https://parity.apps.wayne.edu/downloads/latest/parity_windows_arm64.zip) | | macOS | [parity_darwin_amd64.tar.gz](https://parity.apps.wayne.edu/downloads/latest/parity_darwin_amd64.tar.gz) | [parity_darwin_arm64.tar.gz](https://parity.apps.wayne.edu/downloads/latest/parity_darwin_arm64.tar.gz) | | Linux | [parity_linux_amd64.tar.gz](https://parity.apps.wayne.edu/downloads/latest/parity_linux_amd64.tar.gz) | [parity_linux_arm64.tar.gz](https://parity.apps.wayne.edu/downloads/latest/parity_linux_arm64.tar.gz) | Moving over ### Coming from Squire's parity kit? Parity grew up inside [Squire](https://squire.apps.wayne.edu/) as `squire init --only=parity`. It moved out because people want to run Citadel locally without the rest of the deploy kit. In the folder with `docker-compose.squire.yml`: `parity init --from-squire` It carries the kit's settings over (base image, public folder, ports, database name, time zone, deployments) and leaves every password behind by name: Parity makes its own local ones. It lists the kit's files and deletes none of them. Two differences to expect: Parity runs Citadel's own `php.ini`, not the kit's hardened one, because that is what Citadel runs; and the kit's `scheduler` and `worker` services become one cron entry, because Citadel has cron and no services. [The whole move](https://parity.apps.wayne.edu/docs/guides/from-squire.html) Plainly ### What Parity will not do. - ### Run a look-alike Parity runs Citadel's own images only. "Matches Citadel" needs the tar's sha256 and the loaded image's id to match the catalog; an image with Citadel's tag and other bytes never gets that line, however close it is. - ### Print a configuration value Configuration files are checked for their required keys by name. Values are never printed and never baked into an image. `parity.json` holds settings, never secrets. - ### Bring real data home Parity ships no data, no connectors and no credentials. A local copy may point only at a test database its data owner approves, never production, and never real student or employee data on a laptop (FERPA). - ### Hide the rough edges Citadel runs MySQL 5.6: no JSON columns, and indexed strings stop at 191 characters. Parity runs the same, so you meet those limits here first. For your coding agent ### Hand it to your agent. Two prompts for whatever coding agent you use: one to get an app running on Parity, one to move an app off Squire's parity kit. Copy one, or open it in your tool. Each starts with `parity check`, which changes nothing. #### Get started with Parity Checks the computer, writes `parity.json`, brings the app up on Citadel's image and smoke tests it. It asks before changing anything outside the app. A prompt for your coding agent. Copy it as it stands: ```text You are a coding agent helping me run the PHP app in this folder on Parity, at Wayne State University. Parity runs Citadel (the university's PHP hosting platform) on this computer: Citadel's own Apache and PHP image, its proxy headers and MySQL 5.6, driven by one program, parity, and one settings file, parity.json. It is part of WELD, the Wayne State application stack. Read first: - https://parity.apps.wayne.edu/llms.txt, the index of Parity's pages, each one as Markdown; llms-full.txt beside it holds the README and every page. Fetch what you need; do not work from memory. - ADVISOR, the stack's MCP server, if it is connected: read_project_docs for parity, and list_stack_rules for this app's shape. If it is not connected, say so and work from the pages. How to add it: https://advisor.apps.wayne.edu/llms.txt - This app's composer.json, .env.example and any build.sh, deployments/ or health check it has. Task: 1. If parity is not installed, install it with the line for this computer from https://parity.apps.wayne.edu/#install and open a new terminal. 2. Run parity check and report each finding with its fix. Do not apply a fix that changes this computer (an engine setting, git config) until I say so. 3. Run parity init --print and show me the parity.json it would write. Say which values it guessed and why. Write it with parity init once I agree. 4. Run parity image list. If Citadel's image is not here, run parity image get; if parity says Citadel has not published a download for the app's image yet, stop and tell me; do not swap in another image. 5. Run parity up, then parity test, and report the address and every result. Constraints: - Fake data only. Never point the app at a production database or copy real student or employee data to this computer (FERPA). - Never print, copy or commit a configuration value or password; parity.json holds settings, never secrets. - Never call an image Citadel's unless parity says it matches Citadel. Never commit or push. - Ask me before you guess: a PHP version the app does not state, a missing configuration file, or a port that is taken. Output: the check findings, the parity.json, the up and test printouts, then your questions. ``` #### Move from Squire's parity kit Carries the kit's settings into `parity.json`, proves the app comes up on Parity, and leaves the kit's files for you to remove. A prompt for your coding agent. Copy it as it stands: ```text You are a coding agent moving the app in this folder from Squire's parity kit (docker-compose.squire.yml, .squire/, scripts/parity.sh and scripts/parity.ps1) to Parity, at Wayne State University. Parity is the stack's own way to run Citadel locally; it grew out of the kit. Read first: - https://parity.apps.wayne.edu/llms.txt, then the docs page Coming from Squire's parity kit, which it lists. - ADVISOR, the stack's MCP server, if it is connected: read_project_docs for parity and squire. If it is not connected, say so and work from the pages. Task: 1. Run parity check and report what it finds. 2. In the folder with docker-compose.squire.yml, run parity init --from-squire --print and show me the parity.json it would write, and the kit files it lists. Then write it with parity init --from-squire. 3. Run parity up, then parity test, and compare the result with what the kit gave: say what differs (Parity runs Citadel's own php.ini, not the kit's hardened one). 4. List the kit's files I could remove once I am happy, and what in the README or CI still points at them. Remove nothing yourself. Constraints: - Passwords stay behind: Parity makes its own local ones. Never copy a value from .env.squire into parity.json or anywhere else. - Keep Squire's release files (build.sh, deployments/, scripts/release.sh, health.php): Citadel still needs them. Only the parity kit is replaced. - Never commit or push. Ask me before you guess. Output: the check findings, the parity.json, the up and test printouts, the list of kit files, then your questions. ``` The agent reads the same pages you do: [llms.txt](https://parity.apps.wayne.edu/llms.txt) lists them, [llms-full.txt](https://parity.apps.wayne.edu/llms-full.txt) holds them all in one file, and this page has a [Markdown twin](https://parity.apps.wayne.edu/index.md). Nothing here phones home. The buttons only copy text or open the tool you picked. Where it fits ### Parity's place in WELD. WELD is the Wayne State application stack. Parity is its "run Citadel locally" layer. It depends on nothing else in the stack, so any Citadel app can use it, stack or not. - [WayneUI](https://wayneui.apps.wayne.edu/)The interface layer every app renders, this page included. - [CREED](https://creed.apps.wayne.edu/)The version policy. - [PROCTOR](https://proctor.apps.wayne.edu/)Measures an app against that policy. - [Preflight](https://preflight.apps.wayne.edu/)The CI templates; this site's accessibility gate is one of them. - [SESAME](https://sesame.apps.wayne.edu/)Sign-in. Its fake driver is how a local copy signs in without CAS. - [HELMET](https://helmet.apps.wayne.edu/)The baseline runtime: headers, sessions, `/up`. - [Pinstripe](https://pinstripe.apps.wayne.edu/)The coding standard. - [Sourdough](https://sourdough.apps.wayne.edu/)The starters. Every app ships a Squire kit, which `parity init` reads. - [Booster](https://booster.apps.wayne.edu/)Moves apps forward. A PHP upgrade is exactly when Citadel's real image matters. - [Squire](https://squire.apps.wayne.edu/)Gets the app onto Citadel. Parity runs Squire's `build.sh` and `deployments/` the way Citadel does. - ParityCitadel on your computer.You are here - [Rollcall](https://rollcall.apps.wayne.edu/)Every app answers "present", with its PHP version. - [ADVISOR](https://advisor.apps.wayne.edu/)An MCP server your agent can ask about the stack. - [Drawbridge](https://drawbridge.apps.wayne.edu/)The sign-in gateway. - [WELD](https://weld.apps.wayne.edu/)The stack's name, and its Laravel and Vue starter. Next ### The road to 1.0. The command line does the whole job today, and 1.0 is these same commands, promised. What stands between here and the tag is proof: `parity up` and `parity test` on real computers, with Citadel's own image, each engine in turn. - **Linux** Podman, rootful and rootlessProven - **Windows** Podman Desktop, mount and bakeProven - **Windows** Docker DesktopProven - **macOS** Apple Silicon, Podman and Docker DesktopNext - 1.0 Today's commands, as a promise: `check`, `init`, `up`, `down`, `status`, `logs`, `shell`, `test`, `trust`, `image` and `engine`, and local HTTPS on 127.0.0.1:8443 from a name-constrained certificate authority of your own, so an app that forces HTTPS (or signs in with CAS) is tested as it is. Unsigned, with checksums, like 0.1.0. - After 1.0 A desktop app for people who never open a terminal: the same commands as buttons, and the same mirror reading "Matches Citadel." Signed binaries for Windows and macOS come first. [See its screens beside the commands.](https://parity.apps.wayne.edu/#commands) - Later `reset`, `eject`, `image pin` and `image build`; winget, Homebrew and deb or rpm packages. --- Source: https://parity.apps.wayne.edu/docs/changelog.html ## Changelog [#](https://parity.apps.wayne.edu/docs/changelog.html#changelog) All notable changes to Parity are recorded here. The format follows Keep a Changelog. ### \[Unreleased\] [#](https://parity.apps.wayne.edu/docs/changelog.html#unreleased) - Changed: `deploy/` requires PROCTOR `^0.16` (was `^0.15`, which does not allow 0.16), whose `ci-pipelines` check no longer asks for a GitHub workflow (D-069). - Fixed: on Apple Silicon with Docker Desktop, a Rosetta setting Parity cannot read (newer builds store it elsewhere) is now an info line in `parity check`, not a warning nobody can clear; `UseRosetta` is read too. - Fixed: the docs pages set their text in the body face (Lato) again, not the display serif, and a code block's Copy button sits in a gutter beside the code instead of covering the end of its first line. - Site: the front page's road to 1.0 lists `trust` and local HTTPS under 1.0, no longer under "Later". - Docs: local HTTPS (`"https": true`, `parity trust`, the `https.trust` check) in the README, the parity.json and commands references, the FAQ and troubleshooting; it is part of 1.0 now, not after it. - Added: `parity check` warns (`https.trust`) when your user store does not trust the app's local CA yet, and `parity test` also loads the home page over https, pinned to that CA. - Added: `parity trust` (and `parity trust --remove`) puts the app's local https certificate authority in your user store on Windows and macOS, and prints the commands for Linux. - Added (internal): with `"https": true` the stack's HAProxy serves https on 127.0.0.1:8443 with a leaf from the app's local CA (renewed when 7 days are left); `parity trust` comes next. - Added (internal): parity.json accepts `"https": true` and checks its port (8443) against `http_port` and `database.port`; serving it comes in the next slices. - Added (internal): a per-app local CA for the coming `"https": true` (one CA per app, name-constrained, keys in the per-user config dir). - Added: `test.tools` in parity.json: commands `parity test` runs in the app container (as user citadel) before its HTTP checks; the first failing tool stops the run. - Added: `parity check` checks the running app too: APP_KEY, writable folders, the database and pending migrations. With the app stopped it says so and skips them. - Added: `parity run -- ` runs a tool (composer ci, php artisan test, npm run build) in the app container as user citadel and returns its exit code. In bake mode it says the files it writes vanish on the next `parity up`. - Changed: with no `parity.json`, `parity up` and `parity check` say one line naming the right next command (`parity init --from-squire` when the folder has Squire's kit, `parity init` otherwise), and `parity check` now fails there instead of warning. - Changed: mount mode keeps `vendor/` and `node_modules/` in per-project named volumes laid over the bind mount, so the kit's release steps never rewrite the developer's own copies (D-091); `parity init` says so instead of warning. - Docs: the git LFS image route says to run `git lfs install` once. - Security: CI and release builds use Go 1.26.11 (was 1.26.10), which fixes GO-2026-6859 (an HTTP/1 server crash from a header race in net/http's MaxBytesReader). govulncheck flagged it on main; `parity` itself only makes HTTP requests, but the release binaries are built with the fixed Go. - Added (maintainers): `go run ./tools/checklist` runs the release checklist's real-machine steps on the computer it runs on: it builds `parity` from the checkout and, on a scratch copy of `testdata/hello` in each mode, runs `check`, `image get` when Citadel's image is missing, `up`, `test` at once and 30, 60, 90 and 120 seconds later, `status` (the mirror must match Citadel) and `down --volumes`, then prints the row for MAINTAINING's "Checklist runs" table. One command for the Mac run that 1.0 waits on, the same on Windows and Linux. - Tests: the terminal voice (`internal/term`: style detection, the three symbol sets, colors, the live spinner and progress bar, and what the desktop app's observer hears) is covered at 92% (was 37%), race-clean. - Added: `parity init --health-check` sets Citadel's health check: a command (`php deploy/health.php`), or a path such as `/up`, which becomes a check that Apache answers it. Without it, init guesses as before. - Changed: the deploy kit is Squire 0.10.8 (was 0.10.7): 0.10.8 moves no template and no kit file (the last template move was the 0.10.7 `.gitattributes`, the last docs and agent-ready tool change was 0.10.6), so `deploy/.squire.json` records the new version and every kit file stays as it is. - Fixed: `parity test` no longer fails a healthy app when the engine's own connection drops for a moment (Podman on Windows: `exited 125: unable to connect to Podman socket ... ssh: handshake failed`). Its reads in the container (the health check, and the log reads) try once more after two seconds when the engine's client, not the container, failed; a second drop says so instead of blaming the app. Found in a 30-run loop on the Windows checklist run. - Site: the front page's "Next" section is now "The road to 1.0": the release-checklist runs per OS (Linux and Windows proven with Citadel's real image, macOS next) and what comes at 1.0, after it and later. The desktop app is labeled "After 1.0" (was "Coming in 0.2.0"), and the installers' unsigned note says the same. MAINTAINING gains a "Checklist runs" table with the 2026-11-10 Windows runs. - Fixed: on Podman the proxy lost the app about a minute after `parity up` and answered 503 (`DNS timeout status` in `parity logs proxy`). HAProxy asked Docker's DNS address (127.0.0.11) on every engine; it now reads the nameserver each engine writes into the container (`parse-resolv-conf`), so Docker and Podman both keep finding the app. Found on the Windows checklist run with Podman 5.8.9. - Fixed: `parity up` signs in to MySQL as the app before it starts the app, and stops at the MySQL step (exit 2, with the way out) when the database volume was made with other passwords or for another database name. MySQL's health check passes even when access is denied, so a deleted `.parity/` (git clean -x, a fresh clone) or a second folder with the same app name used to come up "healthy" with every page saying it cannot reach the database. Found on the Windows release-checklist run. - Docs: the README, MAINTAINING and the guides say what 1.0 promises (today's commands) and what follows it (reset, eject, image pin and build, local HTTPS, the desktop app), as decided on 2026-11-10. - Changed: the deploy layer requires PROCTOR ^0.15 (locked 0.15.0, was ^0.12): 0.13 checks the release cooldown against the CREED policy and 0.14 adds `script-pair`; 0.15 adds `mysql56-ci`; all of these only warn, nothing breaks. - Changed: the deploy layer requires PROCTOR ^0.12 (locked 0.12.0, was ^0.11): two new warning-only checks, nothing breaks. - Site: the front page's stale facts are current (the `parity help` printout lists `engine` and `logs deployments`, and the stack list says the starters ship a Squire kit, which `parity init --from-squire` reads, not a `parity.json`). - Added: `parity test` notes (`Proxy trust`, a warning that does not fail the run) when HELMET logged rejected forwarded headers while it ran, and says to set HELMET_PROXIES for Parity's proxy; `--json` results gain an optional `warn` field. - Fixed: `parity up` warns, instead of failing with "does not answer on port", when HAProxy is up but the app's front page is slower than the probe; a refused connection still fails. - Added: `parity check` warns (`vite-hot`) when the public folder has Vite's `hot` file, and `parity test` fails a front page that loads its assets from Vite's dev server (localhost:5173), which Citadel never runs. - Added: `parity init --from-squire` warns when mount mode will run the kit's deployments (and so Composer, npm and migrations) in the developer's own folder, and names bake mode or SQUIRE_NPM=skip and SQUIRE_MIGRATE=0 as the ways out. - Added: `parity init` uses a Laravel app's declared health route (`health: '/up'` in `bootstrap/app.php`) as the health check, instead of asking Apache for `/`. - Added: `parity check` warns (`mount-speed`) when a Windows folder runs in mount mode on a Linux-container engine, which is slow; it names bake mode and the WSL filesystem as the ways out. - Changed: the deploy kit is Squire 0.10.7 (was 0.10.6): it ships a `.gitattributes` that pins line endings, so the deploy layer clears PROCTOR's line-ending warnings. - Changed: the docs and agent-ready kits and the deploy kit are Squire 0.10.6 (was 0.10.5): the docs builder and agent-ready generator see every file on Docker Desktop mounts. - Site: `assets/stack-env.js` knows Parity, so a pre-production page links Parity's pre-production site and a dev page links its local `site/` folder. Until now Parity, of all parts, was the one link that ignored its environment. - Fixed: messages no longer name a parity edit command, which never existed; they point to the image field in parity.json and parity image list. - Removed: the stand-in image and `parity up --fallback`. Parity runs Citadel's own images only; an image Citadel has not published yet says so. - Docs: the GUI, guides and front page no longer mention the stand-in; a missing image says Citadel has not published it yet. - Added: the site shows the desktop app beside the terminal. A "Terminal or app" switch on the front page pairs each command's printout with the same step in the app, labeled "Coming in 0.2.0" (the app is not released yet), and a new guide, "The desktop app (0.2.0)", shows three more screens. Screens are from the work in progress, with sample apps. - Fixed: a failed deployment's own log now ends `parity up`'s message, and `parity logs deployments` shows it; an image with no download says so at once instead of sending you to parity image get. - Fixed: `parity init --from-squire` keeps the kit's image only when Parity can get it, adds the scheduler only when the app schedules something, and drops the example host name. - Fixed: the site's downloads folders are readable by the web server; they were created owner-only, so every /downloads/ URL answered 403. - Changed: a plain `go build` from a checkout now says `parity 0.2.0-dev`. Release binaries still take their version from the tag. - Added (0.2.0 preview): the desktop app in `gui/`, its own Go module on Wails v2.17.1, so the `parity` command stays free of Wails, WebView and cgo. Every button runs the same Go code as the command: app list, app home with your machine and Citadel side by side (Match, Close or Differs per row), start and stop with live steps, logs streamed with local passwords hidden, `parity test` results, `parity check`, cron entries and settings. Build it with `wails build` (see `gui/README.md`); opening a shell still hands over the command. - Added: `parity engine [podman|docker|auto]` says which container engine Parity uses and why, or saves the choice for you on this computer (`parity/settings.json` in your config folder; `PARITY_APP_CONFIG_DIR` moves it). Every command, `parity check` and the desktop app use it; `PARITY_ENGINE` still wins where it is set, and both say so. `--json` is the stable contract. A settings file Parity cannot read counts as no choice, and `parity engine` says what is wrong with it. - Added: the mirror compares Node and PHP extensions too. Parity asks the running app container (or else the app image, or else Citadel's base image here) for `php -m` and `node -v`, once per image id, and compares them with the catalog: Node is Close when only the minor or patch differs and Differs across a major; a missing extension Differs and an extra one is Close, each listed under the extension row and counted as one difference. The catalog records 8.5r3's Node (22.23.4) and its 50 extensions, read from the real image. - Added: `parity status` and `parity check` end with the same mirror as text, row for row what the desktop app shows, when there is a `parity.json` and the engine runs. The `--json` output is unchanged. - Added (desktop app): Settings lists Podman and Docker each on its own line, Podman first and recommended: on PATH or not, running, version, Compose, rootless or rootful, and Podman's machine on Windows and macOS (a machine that runs with no Podman service answering in it says so, rather than "stopped"). A missing or stopped engine shows `parity check`'s own fix steps (both come from `check.EngineFix`), with a button to Podman Desktop's download page. - Added (desktop app): an engine picker in Settings. Podman (first, recommended), Docker, or whichever answers; an engine that is not installed cannot be picked. The choice is the one `parity engine` saves, so the window and every terminal agree. When `PARITY_ENGINE` is set where the window started, the window says it wins and which engine that leaves in use. - Added (desktop app): ports in Settings. Each app's HTTP and MySQL port, saved to its `parity.json` with the code `parity init` writes with; Check ports asks the way `parity up` does (free, in use by this app, or taken, and two apps on one port). A problem shows beside its field and nothing is written; a running app is offered a Restart. - Added (desktop app): Citadel's images in Settings. Verify is `parity image verify`; Get is `parity image get`, with download, sha256, load and image id as live steps, the download's progress, and Stop. Use a file takes a tar you downloaded in the browser. A failed step shows its reason and the fix beside the image. - Added (desktop app): the window fits beside an editor down to 640 px wide, with no sideways scroll and nothing cut short. - Added (desktop app): sign-in (none, fake with its user, or CAS) and cron entries change on the app's parity.json tab. Parity writes `parity.json` with the code `parity init` writes with, after the same checks the command runs (Citadel's schedule rules; no `;`, `&&`, `|`, `>` or `$` in a command), and shows each problem beside its field. A running app gets a notice and a Restart button (`parity down`, then `parity up`; the database stays). - Changed: the catalog's 8.5r3 note. The image has opcache (PHP 8.5 builds it in); the note said it had none. - Changed: the site's deploy layer uses Squire's 0.10.5 kit and current stack packages. - Changed: the site CI job runs Composer 2.11.1 (was 2.10.3, which is no longer maintained). - CI: Preflight 0.9.0 (secret-detection, a11y, proctor), up from 0.5.0. ### \[0.1.0\] - 2026-11-09 [#](https://parity.apps.wayne.edu/docs/changelog.html#0-1-0-2026-11-09) The first release. Parity runs Citadel on your own computer, for any PHP app, with or without Squire: - **Citadel's stack, piece by piece:** Citadel's real PHP image (`citadel/php-apache:8.5r3`, fetched with your own git.wayne.edu access and checked against Citadel's by sha256 and image id) or a stand-in built from the official PHP image and labeled as one; Citadel's own `vhost.conf` and `php.ini`; HAProxy saying what Citadel's proxy says; MySQL 5.6.51; the app's `build.sh`, `deployments/` and health check run the way Citadel runs them. - **Commands:** `check`, `init` (with `--from-squire`), `up`, `status`, `logs`, `shell`, `test`, `down`, `image list|get|verify` and `version`. Exit codes 0 pass, 1 findings, 2 cannot run; `--json` on the read commands is the stable contract. - **One file per OS:** six static binaries (Windows, macOS and Linux, each x64 and arm64), as `parity_0.1.0__.tar.gz` (`.zip` on Windows) with `checksums.txt`, installed by `install.ps1` or `install.sh`. Unsigned in 0.1.0; signing comes before the desktop app, which follows 1.0. - **Not yet:** `reset`, `eject`, `image pin|build`, HTTPS with a local certificate authority, and the desktop app. Citadel's 8.4r5 image is known by its stand-in only until its tar is published. - Added: Parity's site (`site/`), ready for Citadel at parity.apps.wayne.edu. The front page holds your machine up to Citadel in a mirror, row by row (Match, Close or Differs), with an install line per OS, the real printouts, the six downloads and two prompts for a coding agent. The docs (getting started, every command, `parity.json`, Citadel's images, moving from Squire, how it works, troubleshooting, FAQ and this changelog) wear the same header, built from `docs/` by `site-build/` with Squire's docs builder, with `llms.txt`, `llms-full.txt` and a Markdown twin of every page. `deploy/` serves it on Citadel behind HELMET with Squire's release kit, and CI runs Preflight's accessibility gate on every page. - Added: `sign_in` now does something. `fake` gives the app `SESAME_DRIVER=fake` and `SESAME_FAKE_USERNAME` (new `fake_user`, default `jdoe`) and needs a local, dev or test `environment`; `cas` gives `SESAME_DRIVER=cas` and `SESAME_CAS_SERVICE_URL=https:///login` and needs `server_name` on wayne.edu. Both go into `.parity/app.env`, never the app's `.env`. - Added: `cron` in `parity.json`, Citadel's cron entries (short name, schedule, command), checked against the rules Citadel's dashboard uses and run inside the app container as `prisoner` by a small loop beside Apache, with Citadel's per-name stdout and stderr files. `parity logs cron:` shows them. `parity init` and `--from-squire` propose `php artisan schedule:run` every minute when the app schedules anything (`--no-cron` leaves it out). No queue worker service, on purpose: Citadel has none, so a queue drains from the scheduler. The README has a `parity shell` recipe for `npm ci && npm run build`, and says a second database is out of scope for 0.1.0. - Added: release packaging. GoReleaser (v2.20.0, `.goreleaser.yaml`) builds the six archives and `checksums.txt` in git.wayne.edu CI on every tag, with the version and commit stamped into `parity version`; `tools/downloads` lays out the tree Parity's site serves (`downloads//`, and `downloads/latest/` with version-free names and a `VERSION` file for releases), refusing any archive that does not match its checksum; the `release` job puts the files in the project's package registry and makes the GitLab Release with curl. A snapshot runs on main whenever the release files change. - Added: `install.ps1` (Windows PowerShell 5.1 and 7: `%LOCALAPPDATA%\Programs\parity`, your user PATH, no administrator) and `install.sh` (macOS and Linux: `~/.local/bin`, or the folder you name, with sudo only when you name one you cannot write). Both take a version or default to the latest release, check the sha256 against the release's `checksums.txt` before installing (which catches a corrupted or partial download, not tampering: both files come from the same site), and say plainly what to do about SmartScreen or macOS quarantine while the binaries are unsigned. - Added: `install.sh` never edits a shell profile. When its folder is not on PATH it prints the one line to add, for bash or zsh and for fish; `PARITY_NO_PATH=1` drops that hint. Its body runs from `main` on the last line, so a `curl | sh` cut short runs nothing, and a failed copy leaves no `parity.new` behind. A failed fetch of `latest/VERSION` now says so, rather than complaining about an empty version. - Added: `install.ps1` decides from the user PATH in the registry, not the session's PATH, so a folder added to one terminal by hand still gets written; it says "Added" only when it changed PATH, and "already on your PATH" otherwise. A failed fetch of `latest/VERSION` says which address it tried. - Added: installer tests (`test/install/`). A small Go file server serves a snapshot's downloads tree on 127.0.0.1, and the tests run each installer against it: the piped install, `parity version`, PATH exactly once after two runs, `PARITY_NO_PATH`, a tampered archive and a missing `VERSION` refused, and (for `install.sh`) a script cut short at six points. git.wayne.edu runs `install.sh` in `package` and `package-snapshot` (now automatic on any branch that changes the release files or the installers); the GitHub mirror runs `install.ps1` on Windows PowerShell 5.1 and PowerShell 7 against the runner's real user PATH, and `install.sh` on macOS. - Added: `parity image list`, `get` and `verify`. `get` fetches Citadel's image with the user's own git.wayne.edu access (a tar from the browser with `--file`, a token in `PARITY_GITLAB_TOKEN` through GitLab's API, or git LFS over SSH or HTTPS, fetching only the one file), with a progress bar, then checks the tar's sha256 and the loaded image's id against the catalog ("matches Citadel") before calling it done. `verify` checks the image here, or a tar. - Added: `parity test` (with `--json`): the front page through the proxy, the app's own health check, the requests in `parity.json`, and no PHP fatal or parse error in Apache's log while it ran. The GitHub Linux job runs it after `parity up --fallback`. - Added: Podman, recommended (ADR-0022). `parity check` reports Podman (machine or native, rootless or rootful), Docker Desktop and any other engine that is here; with none, it suggests Podman Desktop first and Docker Desktop second. `PARITY_ENGINE=docker|podman` picks one (`auto` by default: the running one, Docker first). Docker Compose v2 is the one Compose on both engines: podman-compose is named and refused, and on Linux the check knocks on Podman's API socket. A podman machine that runs with no Podman service answering says so, and why. Proven on Podman 5.8.9, rootful and rootless, through `podman compose` and `docker compose`; a level with two bubbles, both in the middle. - Added: rootless Podman in mount mode runs the app with `userns_mode: keep-id` (the image's `citadel` ids) as root, and the writable paths go to Apache's group, group-writable, as the container starts, as Citadel's deploy does. Apache, the deployments and the cron entries can all write them; your folder stays yours. - Changed: images are written in full (`docker.io/library/mysql:5.6.51@sha256:...`), because Podman refuses short names. On Podman, builds use the classic builder (BuildKit's builder container cannot see Podman's images), so Citadel's `vhost.conf` and `php.ini` come from `.parity/citadel` inside the build context rather than a second build context. The catalog also knows each image's config digest, the id Podman reports. - Fixed: in bake mode a writable path was owned by `prisoner`, so a deployment (run as `citadel`) could not write it. It is now `citadel:prisoner` and group-writable, as on Citadel. Bake images also leave `.parity` out. - Fixed: `parity logs cron:` and the build, logs and shell commands run in the engine's Compose environment, so Podman's "Executing external compose provider" banner stays out of the output. - Added: `parity up`. It writes `.parity/` from `parity.json` (the compose file; the Dockerfile Citadel's generator would write; Citadel's own `vhost.conf` and `php.ini`, copied unchanged from Citadel's repository with their MIT license; HAProxy's settings; local MySQL passwords made once and kept) and brings the app up one piece at a time, each with a live line: Citadel's image, checked against Parity's catalog ("matches Citadel"), the build with the build script run as root with `/bin/sh`, MySQL 5.6.51, the app (deployments, Apache, the health check at Citadel's 5 minute and 15 second timing, answered in seconds locally), and HAProxy, then the address. A failure shows the last lines that explain it; everything is in `.parity/up.log`. `--fallback` builds a stand-in base from the official PHP image (the same users, modules, extensions, Node and Citadel's own entrypoint, without oci8, imagick and ssmtp) and says so. On arm64 Citadel's amd64 image runs under emulation. - Added: `parity status` (with `--json`), `parity logs` (`-f`, `--tail`, `--apache` for Apache's own logs), `parity shell` and `parity down` (`--volumes` empties the local database). - Added: `parity check` checks Citadel's image (here, and the build Citadel runs) and the ports `parity up` needs. - Added: the image catalog inside Parity: `citadel/php-apache:8.5r3` (image id, the tar in `enterprise-apps/images` with its sha256 and size) and the fallback bases for PHP 8.5 and 8.4. - Added: the GitHub workflow runs `parity up --fallback` on `testdata/hello` on Linux, end to end. - Changed: paths in `parity.json` may not hold `$`, backquotes, double quotes or line breaks, and `health_check` is one line, because they land in a Dockerfile and a shell. - Added: `parity.json` (format version 1), the app's Citadel settings: image, public folder, mode (`mount` or `bake`), build script, deployments, health check, writable paths, configuration files with required keys, MySQL, sign-in, ports and test requests. Unknown fields are an error. - Added: `parity init` writes it from the folder's layout (public folder, `build.sh`, `deployments/`, `health.php` or `health-check`, Laravel's writable folders, MySQL from `.env.example`), with flags to override and `--print` to preview. `--from-squire` carries a Squire parity kit's settings over and leaves its passwords behind by name; a kit in `deploy/` is pointed at. - Added: `parity check` reads `parity.json`: problems in it, the files it names for the line-ending check, and the configuration files (present, required keys filled in, values never printed). - Added: `testdata/hello`, the smallest app that shows Parity runs Citadel. - Added: `parity check` (with `--json`). It finds the engine (Docker Desktop, Rancher Desktop, Podman, OrbStack, Colima, Docker Engine, through `docker` or `podman`), Compose v2, Windows containers mode, Docker Desktop off WSL 2, arm64 emulation (Rosetta in Docker Desktop, OrbStack, Colima, Rancher Desktop; QEMU binfmt on Linux; Windows on Arm) and Windows line endings in the files Citadel runs (`build.sh`, `deployments/`, `health-check`, `*.sh`), with one fix per finding for the OS. Exit 0 pass, 1 findings, 2 cannot run. - Added: styled output. Color, symbols and spinners on a terminal; plain `[ OK ]` tags in a pipe or CI log, with `--plain` or `PARITY_PLAIN=1`; no color with `NO_COLOR`; `PARITY_STYLE=fancy` keeps symbols in a log. The classic Windows console gets VT mode switched on and symbols from its own fonts. - Added: the repository. `parity version` (with `--json`), the Go module `git.wayne.edu/enterprise-apps/parity`, `tools/build` for the six targets with `checksums.txt`, git.wayne.edu CI (gofmt, vet, tests, govulncheck, secret detection, cross-compiled binaries) and the GitHub workflow for Windows and macOS on tags. --- Source: https://parity.apps.wayne.edu/docs/faq.html ## FAQ [#](https://parity.apps.wayne.edu/docs/faq.html#faq) Short answers, with a link to the long one where there is one. ### Do I need PHP or Composer on my computer? [#](https://parity.apps.wayne.edu/docs/faq.html#do-i-need-php-or-composer-on-my-computer) No. PHP, Apache and the extensions come from Citadel's image, inside the container. Composer runs where your `build.sh` runs it, inside the build, as on Citadel. ### Is this the same as Squire? [#](https://parity.apps.wayne.edu/docs/faq.html#is-this-the-same-as-squire) No, and they work together. Squire gets the app onto Citadel (`build.sh`, `deployments/`, `release.sh`). Parity runs Citadel on your computer, and runs those same files the way Citadel does. Parity used to be Squire's parity kit: [Coming from Squire](https://parity.apps.wayne.edu/docs/guides/from-squire.html). ### Does my app have to use the WELD stack? [#](https://parity.apps.wayne.edu/docs/faq.html#does-my-app-have-to-use-the-weld-stack) No. Parity depends on nothing in the stack. Any PHP app that runs on Citadel can use it, from a 2009 folder of PHP files to a current Laravel app. ### Why not just use the official PHP image? [#](https://parity.apps.wayne.edu/docs/faq.html#why-not-just-use-the-official-php-image) Because Citadel does not. Citadel's image has its own users, modules, extensions, Oracle client and entrypoint, and its own `php.ini`. An app that works on the official image can still fail on Citadel. So Parity runs Citadel's own image, byte for byte, and nothing else. When Citadel has not published a download for a tag yet, Parity says so rather than run a look-alike ([Citadel's images](https://parity.apps.wayne.edu/docs/guides/images.html#when-citadel-has-not-published-an-image-yet)). ### Can I connect to Oracle or Banner? [#](https://parity.apps.wayne.edu/docs/faq.html#can-i-connect-to-oracle-or-banner) Not with Parity's help. Parity ships no connectors, no credentials and no data. Citadel's image includes the Oracle client, so code that uses oci8 loads, but a local copy may point only at a test database its data owner approves, never production, and never real student or employee data on a laptop (FERPA). ### How do I sign in locally? [#](https://parity.apps.wayne.edu/docs/faq.html#how-do-i-sign-in-locally) Set `sign_in` to `fake` in `parity.json` to use SESAME's fake driver, which signs you in as `fake_user` (`jdoe` unless you say otherwise) without CAS. Parity puts the settings in the app container's environment and never touches your `.env`. `cas` is for an app that must talk to the real CAS: it needs a wayne.edu `server_name` 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. [Sign-in](https://parity.apps.wayne.edu/docs/reference/parity-json.html#sign-in) has the details. ### How do I run a queue worker or a scheduled job? [#](https://parity.apps.wayne.edu/docs/faq.html#how-do-i-run-a-queue-worker-or-a-scheduled-job) The way Citadel does: with a [cron entry](https://parity.apps.wayne.edu/docs/reference/parity-json.html#cron-entries). Citadel has no worker service, so a Laravel app runs `php artisan schedule:run` every minute and drains its queue from the scheduler. `parity init` proposes that entry when the app schedules anything. ### How do I build the front end? [#](https://parity.apps.wayne.edu/docs/faq.html#how-do-i-build-the-front-end) Citadel's images carry Node (22 in `8.5r3`), so build in the app container, as the user who owns the code, the way a deployment script would on Citadel: ```text parity shell --user citadel sh -c 'npm ci && npm run build' ``` The built files land in your folder and Apache serves them on the next request. Vite's dev server and hot reload are not part of Citadel, so run `npm run dev` on your own computer if you want them. ### Can my app use a second database? [#](https://parity.apps.wayne.edu/docs/faq.html#can-my-app-use-a-second-database) Not in 1.0. Parity runs one MySQL 5.6, as Citadel gives one database per app. An app that reads a second database (a one-time import from an older app, say) points that connection at a test copy its data owner approves, in its own settings. ### What about HTTPS? [#](https://parity.apps.wayne.edu/docs/faq.html#what-about-https) Set `"https": true` in `parity.json` and Parity serves https for `server_name` (and `localhost`) on 127.0.0.1:8443, a fixed port, with a leaf from the app's own local CA: one CA per app, name-constrained to the app's names, kept in Parity's per-user config folder, its key never leaving it. The https frontend sends `X-Forwarded-Proto: https`; plain http on `http_port` keeps working. Run `parity trust` once per computer and the browser stops warning (on Linux it prints the sudo commands for your distro, and Firefox always takes a manual import). `parity check` then shows `https.trust`: OK when your user store trusts the CA, a warning with `Fix: parity trust` when it does not, and it never fails, so CI stays green. `parity test` loads the home page over https pinned to the app's CA, which a CI machine never trusts system-wide. [Commands](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-trust) has the details. ### Can I run two apps at once? [#](https://parity.apps.wayne.edu/docs/faq.html#can-i-run-two-apps-at-once) Yes. Each app is its own compose project (`parity-`). Give them different `http_port` values, and different `database.port` values if both use MySQL. ### Where is my data? [#](https://parity.apps.wayne.edu/docs/faq.html#where-is-my-data) In a volume of the app's compose project. `parity down` keeps it; `parity down --volumes` empties it. ### Can I use Parity in CI? [#](https://parity.apps.wayne.edu/docs/faq.html#can-i-use-parity-in-ci) Yes. Without a terminal it prints plain tags, and `--json` on `check`, `status`, `test`, `image list` and `version` is the stable contract. Exit codes are 0 pass, 1 findings or a failed test, 2 cannot run. A runner needs a container engine and Compose, and Citadel's image. Parity's own CI runs on runners that cannot fetch Citadel's image, so it builds a test-only image for its end-to-end job; that image is a fixture for Parity's tests, not something to run your app on. ### Is there an app for people who never open a terminal? [#](https://parity.apps.wayne.edu/docs/faq.html#is-there-an-app-for-people-who-never-open-a-terminal) After 1.0: a desktop app with the same commands as buttons. Each button names the `parity` command it runs, so the app teaches the command line without asking anyone to use it. It is not released yet; [the desktop app guide](https://parity.apps.wayne.edu/docs/guides/desktop-app.html) shows its screens from the work in progress. ### Where do I report a problem? [#](https://parity.apps.wayne.edu/docs/faq.html#where-do-i-report-a-problem) In the [repository's issues](https://git.wayne.edu/enterprise-apps/parity/-/issues) on git.wayne.edu. Include the output of `parity check --plain` and `parity version`. --- Source: https://parity.apps.wayne.edu/docs/guides/desktop-app.html ## The desktop app (after 1.0) [#](https://parity.apps.wayne.edu/docs/guides/desktop-app.html#the-desktop-app-after-1-0) Note The desktop app is not released yet. It comes after 1.0. Today Parity is the `parity` command, and everything on this page can be done with it now. The screens below are from the work in progress, with sample apps. Its code is in the repository's `gui/` folder; there is no download until it ships. The app is for people who never open a terminal. It is one window over the same Go code the `parity` command runs: each button calls the code its command calls, and nothing in the window decides anything on its own. So the window and the command cannot disagree, and a screen always says which command it matches ("In a terminal: `parity status`"). ### Your app, up and matching [#](https://parity.apps.wayne.edu/docs/guides/desktop-app.html#your-app-up-and-matching) The app's home shows one app: its state, Start or Stop (one button), Open in browser and Run test, the address, and the same side by side mirror the front page shows, one row per fact, reading "Matches Citadel." when every row does. ![Parity's app with hello running: a Running, match badge, Stop, Open in browser and Run test buttons, the address http://localhost:8080, and the side by side mirror of this computer and Citadel (image, image id, PHP 8.5.12, platform, php.ini, MySQL 5.6.51, Node, PHP extensions), every row Match, ending in Matches Citadel.](https://parity.apps.wayne.edu/assets/app/up-light.webp) The Overview tab, the same reading as `parity status`. ### Logs [#](https://parity.apps.wayne.edu/docs/guides/desktop-app.html#logs) The Logs tab is `parity logs -f` with a filter: all of it, or only the app, the proxy, MySQL or Parity's own lines. The local passwords Parity made for the app show as `hidden`, here as in the terminal. ![Parity's app, the Logs tab for hello: buttons to show all lines or only app, proxy, mysql or parity lines, a line filter and a Follow switch, a note that Parity hides the local passwords it made for the app, and sixteen log lines with the time and the source on each, one database password shown as hidden.](https://parity.apps.wayne.edu/assets/app/logs-light.webp) The Logs tab, following as new lines arrive. ### parity.json, without a text editor [#](https://parity.apps.wayne.edu/docs/guides/desktop-app.html#parity-json-without-a-text-editor) The parity.json tab sets what the file sets: how sign-in works here (none, SESAME's fake sign-in, or Wayne State CAS as on Citadel), and the cron entries Citadel runs in the app container. The whole file sits under it, to read or copy; the [parity.json reference](https://parity.apps.wayne.edu/docs/reference/parity-json.html) covers every key. ![Parity's app, the parity.json tab for hello: a sign-in card with three choices (no sign-in, fake sign-in with SESAME, selected, signed in as jdoe, and Wayne State CAS), a cron entries card with nightly-report at 30 2 \* \* \* running php bin/report.php and a form to add one, and the start of the parity.json file below.](https://parity.apps.wayne.edu/assets/app/config-light.webp) The parity.json tab, writing the same file you can edit by hand. ### The rest [#](https://parity.apps.wayne.edu/docs/guides/desktop-app.html#the-rest) - **Check this computer** is the first screen: the same checks as `parity check`. - **Add an app** proposes the parity.json `parity init` would write and writes nothing until you say so. - **Settings** picks the engine (Docker or Podman), checks the ports, and gets or verifies Citadel's images with the same steps as `parity image get` and `parity image verify`. - **Ctrl K** lists every command, each with the `parity` command it matches. The front page shows each of these next to its terminal printout: [Check, then up](https://parity.apps.wayne.edu/#commands). --- Source: https://parity.apps.wayne.edu/docs/guides/from-squire.html ## Coming from Squire's parity kit [#](https://parity.apps.wayne.edu/docs/guides/from-squire.html#coming-from-squire-s-parity-kit) Parity grew up inside [Squire](https://squire.apps.wayne.edu/) as `squire init --only=parity`: a compose file, a `.squire/` folder and two scripts. It moved out because people want to run Citadel locally without the rest of the deploy kit. Parity does the same job as one program, with nothing to copy into your app but `parity.json`. Squire keeps its release files (`build.sh`, `deployments/`, `scripts/release.sh`, `health.php`): Citadel still needs them, and Parity runs them the way Citadel does. Only the parity kit is replaced. ### The move [#](https://parity.apps.wayne.edu/docs/guides/from-squire.html#the-move) In the folder with `docker-compose.squire.yml` (the app's root, or `deploy/` when the kit lives there): ```text parity check parity init --from-squire --print parity init --from-squire parity up parity test ``` `--print` shows the `parity.json` it would write and the kit files it found, without writing anything. ### What carries over [#](https://parity.apps.wayne.edu/docs/guides/from-squire.html#what-carries-over) Parity reads `docker-compose.squire.yml`, `.env.squire.example` and `.env.squire`, and carries these settings by name: | Squire setting | parity.json field | | --- | --- | | `SQUIRE_PROJECT` | `name` | | `SQUIRE_BASE_IMAGE` | `image` | | `SQUIRE_PUBLIC_DIR` | `public_dir` | | `SQUIRE_DEPLOYMENTS` | `deployments` | | `SQUIRE_TZ` | `time_zone` | | `SQUIRE_SERVER_NAME` | `server_name` | | `SQUIRE_ENVIRONMENT` | `environment` | | `SQUIRE_HTTP_PORT` | `http_port` | | `SQUIRE_DB_NAME`, `SQUIRE_DB_PORT` | `database.name`, `database.port` | ### What stays behind [#](https://parity.apps.wayne.edu/docs/guides/from-squire.html#what-stays-behind) **Every password, and every other variable.** Parity notes their names and skips their values: nothing from `.env.squire` beyond the table above is read, stored or printed. Parity makes its own local MySQL passwords in `.parity/`, once, and keeps them. ### The kit's files [#](https://parity.apps.wayne.edu/docs/guides/from-squire.html#the-kit-s-files) Parity lists them and deletes none. Once you are happy with Parity, you can remove them yourself: - `docker-compose.squire.yml` - `.squire/` (Dockerfile, vhost.conf, php.ini, php-web.ini, haproxy.cfg, the fallback files) - `scripts/parity.sh` and `scripts/parity.ps1` Look for anything in the README or CI that still runs them. ### What to expect to differ [#](https://parity.apps.wayne.edu/docs/guides/from-squire.html#what-to-expect-to-differ) - **php.ini.** The kit ran a hardened `php.ini` of its own. Parity runs Citadel's own `php.ini` and `vhost.conf`, copied unchanged, because that is what Citadel runs. A setting the kit tightened may be looser here, as it is on Citadel. - **The scheduler and the worker.** The kit's portable `scheduler` and `worker` services become one [cron entry](https://parity.apps.wayne.edu/docs/reference/parity-json.html#cron-entries), `php artisan schedule:run` every minute, because Citadel has cron and no services. The queue drains from the scheduler. - **The image.** The kit can build its own fallback base when Citadel's image is out of reach. Parity has no such path: it runs Citadel's own image only, so get it with `parity image get` before the first `parity up`. - **Where things live.** Everything Parity writes is in `.parity/`, which ignores itself in git and is rewritten on every `parity up`. --- Source: https://parity.apps.wayne.edu/docs/guides/how-it-works.html ## 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/`): `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-` | | `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. --- Source: https://parity.apps.wayne.edu/docs/guides/images.html ## Citadel's images [#](https://parity.apps.wayne.edu/docs/guides/images.html#citadel-s-images) Citadel runs every PHP app on one of its own Apache and PHP images. Parity runs the same image, byte for byte, and proves it before saying so. This page covers the catalog, the download, the check, and what Parity says when Citadel has not published an image yet. ### The catalog [#](https://parity.apps.wayne.edu/docs/guides/images.html#the-catalog) Parity carries a catalog of Citadel's images inside the binary: each tag with its image id, the tar it comes from, and that tar's sha256 and size. `parity image list` shows it, and whether each image is on this computer and matches: ```text Parity image list the Citadel images Parity knows [INFO] citadel/php-apache:8.5r3 not here; parity image get downloads it (379 MB) [INFO] citadel/php-apache:8.4r5 not here; Citadel has not published a download for it yet ``` | Tag | PHP | Status | | --- | --- | --- | | `citadel/php-apache:8.5r3` | 8.5.12 | downloadable and checked | | `citadel/php-apache:8.4r5` | 8.4.27 | no download yet, until Citadel publishes its tar | A new Citadel image means a new Parity release with a new catalog entry. `--json` gives the full image ids. ### Getting one [#](https://parity.apps.wayne.edu/docs/guides/images.html#getting-one) Citadel's images are `docker save` tars kept in git LFS in `enterprise-apps/images` on git.wayne.edu, so getting one takes your own access there. `parity image get` fetches only the one tar, never the whole repository, and tries these routes in order: 1. **A tar you downloaded yourself**, named with `--file`. Download it from the project's page in your browser, then `parity image get --file `. The check is the same as for any other route. 2. **A personal access token** in `PARITY_GITLAB_TOKEN`, used with GitLab's API. `read_repository` is enough. Parity reads it from the environment only and never prints it. 3. **git LFS over SSH** with your own key. Add `--https` to clone over HTTPS instead, so git's credential manager signs you in. `--git` picks this route even when a token is set. The git route needs git LFS set up once: install git-lfs (it ships with Git for Windows and Homebrew has `git-lfs`), then run `git lfs install`. Without it git fetches a small pointer file instead of the tar, and the error "git fetched a pointer, not the image" means exactly this. The download goes to your user cache folder and is deleted once loaded; `--keep` keeps it. ```text Parity image get citadel/php-apache:8.5r3 ✓ Fetch 379 MB with git LFS from git.wayne.edu (enterprise-apps/images) 30s ✓ sha256 61cbd26f1912 matches Citadel's tar ✓ Load loaded into docker 28s ✓ Id 950dcf67937a matches Citadel citadel/php-apache:8.5r3 is Citadel's own, byte for byte. Next: parity up ``` ### What "matches Citadel" means [#](https://parity.apps.wayne.edu/docs/guides/images.html#what-matches-citadel-means) Two checks, both against the catalog: - **the tar's sha256**, before it is loaded, so a damaged or different download never reaches the engine; - **the loaded image's id**, after, so the image the engine holds is the one Citadel runs. Only an image that passes both is called Citadel's, in `parity image get`, `parity up` and `parity check`. An image with Citadel's tag and a different id is reported as "not the build Citadel runs", and `parity image get` replaces it. `parity image verify` repeats the check at any time, on the image here or on a tar with `--file`. Exit 1 when it differs. ### When Citadel has not published an image yet [#](https://parity.apps.wayne.edu/docs/guides/images.html#when-citadel-has-not-published-an-image-yet) Parity runs Citadel's own images and nothing else. That is the point: an app that works here works on Citadel. So when Citadel has not published the tar for a tag yet, Parity has nothing to download, and it says so instead of guessing. `parity up` and `parity check` print: ```text ✗ Image citadel/php-apache:8.4r5 is not on this computer yet. Citadel has not published a download for citadel/php-apache:8.4r5 yet. Set image in parity.json to one that parity image list can get, or ask the Citadel team to publish it. ``` `parity up` stops there with exit 2, as it does for any missing image. There are two ways on: - **Pick an image Parity can get.** Set `image` in `parity.json` to a tag that `parity image list` can download (today, `citadel/php-apache:8.5r3`), then run `parity image get` and `parity up`. In the desktop app, the Images screen shows which tags have a download. - **Ask the Citadel team to publish it.** Once its tar is in `enterprise-apps/images`, the next Parity release adds it to the catalog and `parity image get` downloads it. An image you built or pulled yourself under Citadel's tag still runs. Parity says it is not in the catalog, or not the build Citadel runs, so you know it cannot vouch for it. On an arm64 computer (Apple Silicon, Windows on Arm, an arm64 Linux box), Citadel's amd64 image runs under Rosetta or QEMU emulation. [Troubleshooting](https://parity.apps.wayne.edu/docs/troubleshooting.html#arm64-computers) has the steps. --- Source: https://parity.apps.wayne.edu/docs/ ## Parity [#](https://parity.apps.wayne.edu/docs/#parity) Parity runs Citadel on your own computer: Citadel's own PHP image, Citadel's proxy headers and MySQL 5.6, driven by one program, `parity`, and one settings file in your app, `parity.json`. An app that works under Parity works on Citadel, because the parts that decide that are Citadel's own. This page gets an app running. [Install](https://parity.apps.wayne.edu/docs/install.html) has every way to get the program; [Commands](https://parity.apps.wayne.edu/docs/reference/commands.html) has every option. ### What you need [#](https://parity.apps.wayne.edu/docs/#what-you-need) - **Windows, macOS or Linux**, on x64 or arm64. - **A container engine.** Podman Desktop (recommended, free), or Docker Desktop if you already have it. On Linux, Podman from your distribution, or Docker Engine with its Compose plugin. On Windows the engine runs on WSL 2. - **Your app's folder.** Nothing else: no PHP, no Composer, no Node on your computer. Parity brings Citadel's. ### Five commands [#](https://parity.apps.wayne.edu/docs/#five-commands) Run these in your app's folder. ```text parity check what to fix first, one finding per line, with the fix under it parity init writes parity.json, your app's Citadel settings parity image get downloads Citadel's image and checks it is Citadel's, byte for byte parity up builds and starts the app behind the proxy, then prints its address parity test smoke tests the running app through the proxy ``` `parity down` stops it at the end of the day. Your local database stays until you run `parity down --volumes`. #### 1. Check the computer [#](https://parity.apps.wayne.edu/docs/#1-check-the-computer) `parity check` looks at the engine, Compose, Linux containers, WSL 2 on Windows, amd64 emulation on arm64, line endings in the files Citadel runs, and the ports Parity needs. It changes nothing. ```text Parity check C:\Users\you\Development\my-app ✓ Docker Desktop 29.9.2 is running (linux/amd64, context desktop-linux). ✓ Docker Compose 5.6.1 is here. ✓ Linux containers, on WSL 2. ✓ This machine runs Citadel's amd64 images natively. Ready. This computer can be Citadel's twin. ``` When something needs fixing, each finding has its fix under it, for your OS. Fix the first one and run it again. [Troubleshooting](https://parity.apps.wayne.edu/docs/troubleshooting.html) explains the common ones. #### 2. Write parity.json [#](https://parity.apps.wayne.edu/docs/#2-write-parity-json) `parity init` reads the folder (public folder, `build.sh`, `deployments/`, a health check, Laravel's writable folders, MySQL from `.env.example`) and writes `parity.json`. Preview it first with `parity init --print`. The fields mirror Citadel's app settings page, so checking it is a matter of holding it next to the dashboard. [parity.json](https://parity.apps.wayne.edu/docs/reference/parity-json.html) lists every field. Coming from Squire's parity kit? Run `parity init --from-squire` instead: [Coming from Squire](https://parity.apps.wayne.edu/docs/guides/from-squire.html). #### 3. Get Citadel's image [#](https://parity.apps.wayne.edu/docs/#3-get-citadel-s-image) `parity image get` downloads Citadel's image with your own git.wayne.edu access, then checks the file's sha256 and the loaded image's id against the catalog inside Parity. Only then does Parity call it Citadel's. [Citadel's images](https://parity.apps.wayne.edu/docs/guides/images.html) covers the three ways to download it. Parity runs Citadel's own image and nothing else, so this step comes first. If Citadel has not published a download for your app's image yet, Parity says so and tells you what to do next ([When Citadel has not published an image yet](https://parity.apps.wayne.edu/docs/guides/images.html#when-citadel-has-not-published-an-image-yet)). #### 4. Bring it up [#](https://parity.apps.wayne.edu/docs/#4-bring-it-up) `parity up` builds the app the way Citadel builds it, runs `deployments/`, starts MySQL and the proxy, waits for the health check, and prints the address: ```text Parity up hello on citadel/php-apache:8.5r3 ✓ Image citadel/php-apache:8.5r3 matches Citadel (950dcf67937a) ✓ Build app image built; build.sh ran as root with /bin/sh 4s ✓ MySQL 5.6.51 is ready on 127.0.0.1:3307, database hello 10s ✓ App deployments ran, and healthy: php health.php said yes 4s ✓ Proxy HAProxy answers, adding X-Forwarded-For and X-Forwarded-Proto as Citadel's does hello is up at http://localhost:8080 ``` #### 5. Test it [#](https://parity.apps.wayne.edu/docs/#5-test-it) `parity test` requests the front page through the proxy, runs the app's health check, makes the requests listed in `parity.json`, and fails on any PHP fatal error in Apache's log while it ran. Exit 0 means all passed. ### Fake data only [#](https://parity.apps.wayne.edu/docs/#fake-data-only) Parity ships no data, no connectors and no credentials. A local copy may point only at a test database its data owner approves, never production, and never real student or employee data on a laptop (FERPA). Parity never prints a configuration value and never bakes a configuration file into an image. ### Where to go next [#](https://parity.apps.wayne.edu/docs/#where-to-go-next) - [How Parity works](https://parity.apps.wayne.edu/docs/guides/how-it-works.html): the three containers, mount and bake, and what lands in `.parity/`. - [FAQ](https://parity.apps.wayne.edu/docs/faq.html): the questions people ask first. - [Changelog](https://parity.apps.wayne.edu/docs/changelog.html): what changed in each release. --- Source: https://parity.apps.wayne.edu/docs/install.html ## Install [#](https://parity.apps.wayne.edu/docs/install.html#install) Parity is one program, `parity` (`parity.exe` on Windows). Install it with the line for your computer, then open a new terminal and run `parity check`. ### With one line [#](https://parity.apps.wayne.edu/docs/install.html#with-one-line) Windows ```powershell irm https://parity.apps.wayne.edu/install.ps1 | iex ``` macOS ```sh curl -fsSL https://parity.apps.wayne.edu/install.sh | sh ``` Linux ```sh curl -fsSL https://parity.apps.wayne.edu/install.sh | sh ``` The installers fetch the newest release, check its sha256 against the release's `checksums.txt` before installing anything, and need no administrator: - **Windows** puts `parity.exe` in `%LOCALAPPDATA%\Programs\parity` and adds that folder to your own (user) PATH, once. A second run updates `parity.exe` and says it is already on your PATH. - **macOS and Linux** put `parity` in `~/.local/bin`. The script never edits your shell's profile: if `~/.local/bin` is not on your PATH, it prints the one line to add, and you open a new terminal. ```text bash or zsh (~/.bashrc or ~/.zshrc): export PATH="$HOME/.local/bin:$PATH" fish (~/.config/fish/config.fish): fish_add_path "$HOME/.local/bin" ``` A folder you name with `--dir` (or `PARITY_INSTALL_DIR`) wins. If you cannot write it (`/usr/local/bin`, say), sudo asks for your password for the copy, and only for the copy. A version, a folder of your choosing, or no PATH change (`-NoPath` on Windows; `PARITY_NO_PATH=1` on either, which on macOS and Linux drops the hint): Windows ```powershell & ([scriptblock]::Create((irm https://parity.apps.wayne.edu/install.ps1))) -Version 0.1.0 -InstallDir C:\tools\parity -NoPath ``` macOS and Linux ```sh curl -fsSL https://parity.apps.wayne.edu/install.sh | sh -s -- --version 0.1.0 --dir ~/bin curl -fsSL https://parity.apps.wayne.edu/install.sh | PARITY_NO_PATH=1 sh ``` #### What the checksum proves [#](https://parity.apps.wayne.edu/docs/install.html#what-the-checksum-proves) It catches a corrupted or partial download. It does not prove the download is genuine: `checksums.txt` comes from the same site as the archive, so a site serving a bad archive could serve a matching sum too. Signed binaries come before the desktop app, which follows 1.0. ### A container engine [#](https://parity.apps.wayne.edu/docs/install.html#a-container-engine) Parity drives a container engine; it does not bring one. | Computer | Recommended | Also works | | --- | --- | --- | | Windows | Podman Desktop (free): `winget install --id RedHat.Podman-Desktop -e` | Docker Desktop, if you already have it | | macOS | Podman Desktop (free): `brew install --cask podman-desktop` | Docker Desktop, if you already have it | | Linux | Podman and Docker Compose, from your distribution (`sudo dnf install podman docker-compose` on Fedora and RHEL, `sudo apt-get install podman docker-compose-v2` on Ubuntu), then `systemctl --user enable --now podman.socket` | Docker Engine with its Compose plugin | With both installed, Parity uses the one that is running; `parity engine podman` (or `docker`) chooses for good ([Troubleshooting](https://parity.apps.wayne.edu/docs/troubleshooting.html#which-engine-and-licenses)). On Windows the engine runs Linux containers on WSL 2. On arm64 (Apple Silicon, Windows on Arm, arm64 Linux) Citadel's amd64 images run emulated; [Troubleshooting](https://parity.apps.wayne.edu/docs/troubleshooting.html#arm64-computers) has the details. `parity check` says what, if anything, your engine still needs. ### Take the file yourself [#](https://parity.apps.wayne.edu/docs/install.html#take-the-file-yourself) Each archive holds `parity` (`parity.exe` on Windows) with its README, license and changelog. The newest release is always at the same names: | Computer | x64 (Intel, AMD) | arm64 | | --- | --- | --- | | Windows | [parity_windows_amd64.zip](https://parity.apps.wayne.edu/downloads/latest/parity_windows_amd64.zip) | [parity_windows_arm64.zip](https://parity.apps.wayne.edu/downloads/latest/parity_windows_arm64.zip) | | macOS | [parity_darwin_amd64.tar.gz](https://parity.apps.wayne.edu/downloads/latest/parity_darwin_amd64.tar.gz) | [parity_darwin_arm64.tar.gz](https://parity.apps.wayne.edu/downloads/latest/parity_darwin_arm64.tar.gz) | | Linux | [parity_linux_amd64.tar.gz](https://parity.apps.wayne.edu/downloads/latest/parity_linux_amd64.tar.gz) | [parity_linux_arm64.tar.gz](https://parity.apps.wayne.edu/downloads/latest/parity_linux_arm64.tar.gz) | Check the file against [checksums.txt](https://parity.apps.wayne.edu/downloads/latest/checksums.txt). Every release also stays at `downloads//parity___`, with its own `checksums.txt`. 0.1.0 ships unsigned. A zip downloaded in a browser may meet SmartScreen on Windows ("More info", then "Run anyway", or `Unblock-File parity.exe`), and on a Mac an archive downloaded in a browser needs `xattr -d com.apple.quarantine parity`. The installers avoid both. Signed binaries come before the desktop app, which follows 1.0. ### Build it yourself [#](https://parity.apps.wayne.edu/docs/install.html#build-it-yourself) With Go 1.26 or newer, from a clone of [the repository](https://git.wayne.edu/enterprise-apps/parity): ```text go build -o parity ./cmd/parity (parity.exe on Windows) go run ./tools/build all six binaries into dist/, with checksums.txt ``` Or with a container engine only, using the image Parity's CI uses, pinned by digest, with Go's downloads and build cache in a named volume so a second build starts warm (with Podman, write `podman` for `docker`): ```text docker run --rm -v "${PWD}:/src" -w /src -v parity-go-cache:/go -e GOCACHE=/go/build-cache golang:1.26.11-trixie@sha256:fa340cb59ebeb1d53ac1cccfc334201d938fe5f3458003cccb767096d8e032b8 go run ./tools/build ``` Put the binary for your computer somewhere on your PATH and run `parity version`. ### Update and remove [#](https://parity.apps.wayne.edu/docs/install.html#update-and-remove) Run the install line again to update. To remove Parity, delete the program (and on Windows, its folder from your PATH). Parity keeps nothing else outside your apps, except downloaded image tars you asked it to keep with `parity image get --keep`, in your user cache folder. --- Source: https://parity.apps.wayne.edu/docs/reference/commands.html ## Commands [#](https://parity.apps.wayne.edu/docs/reference/commands.html#commands) Every command, with the options its own `--help` prints. Run `parity --help` for the same text in your terminal. Options take one dash or two (`-json` and `--json` are the same). ```text Usage: parity [-C folder] [options] [--plain] ``` | Command | What it does | | --- | --- | | `parity check` | tells you what to fix before Parity can run Citadel here, one finding per line | | `parity init` | writes `parity.json`, the app's Citadel settings (`--from-squire` reads a Squire kit) | | `parity up` | runs the app the way Citadel runs it, on Citadel's own image, behind the proxy | | `parity status` | shows how the app, MySQL and the proxy are doing | | `parity image` | lists, gets or verifies Citadel's images (`get` downloads one and checks it is Citadel's) | | `parity logs` | shows the app's output (`-f` follows; `--apache` shows Apache's own logs; `deployments` shows the deployment scripts' logs) | | `parity test` | smoke tests the running app through the proxy (plus the requests in `parity.json`) | | `parity trust` | puts the app's local https certificate authority in this computer's certificate stores (`--remove` takes it out again) | | `parity run` | runs a tool in the app container as user citadel (`composer ci`, `php artisan test`, `npm run build`) | | `parity shell` | opens a shell in the app container | | `parity down` | stops the app (the database stays; `--volumes` empties it) | | `parity engine` | shows or saves which container engine Parity uses (`podman`, `docker` or `auto`) | | `parity version` | prints Parity's version | ### Global options [#](https://parity.apps.wayne.edu/docs/reference/commands.html#global-options) | Option | What it does | | --- | --- | | `-C folder` | run as if started in that folder (the app's folder) | | `--plain` | plain output: `[ OK ]`, `[WARN]`, `[FAIL]` tags, no color, no spinners. Anywhere on the line | ### Exit codes [#](https://parity.apps.wayne.edu/docs/reference/commands.html#exit-codes) The same as PROCTOR's and Squire's, on every command: | Code | Meaning | | --- | --- | | `0` | pass | | `1` | findings, or a failed build, deployment, health check or test | | `2` | cannot run: a usage mistake, no engine, no `parity.json`, no image, a port taken | `--json` on the read commands (`check`, `status`, `test`, `image list`, `engine`, `version`) is the stable contract for scripts and CI. The human output may change between releases; the JSON keeps its keys. ### parity check [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-check) ```text Usage: parity check [--json] ``` | Option | What it does | | --- | --- | | `--json` | print JSON (the stable contract) | Checks the container engine (Podman, machine or native, rootless or rootful; Docker Desktop; anything that answers the `docker` command) and names any other engine that is here, Docker Compose v2 (and, on Linux, Podman's API socket), Linux containers, WSL 2 (Windows), amd64 emulation (arm64), Windows line endings in the files Citadel runs, and, with a `parity.json`, the file itself, its configuration files' required keys (by name, never values), Citadel's image and the ports. Changes nothing. With a `parity.json` and a running engine it ends with the mirror, the same rows as `parity status`. With the app running, it also asks the app itself, one finding per line (these run only while the app is up; with the app stopped it says so and skips them): - `app.key` (Laravel apps): `APP_KEY` is set in the local `.env` (its value is never printed). - `app.writable`: every folder in `writable` is in the app and writable by Apache. - `app.database`: the app can sign in to its MySQL. - `app.migrations` (Laravel apps with MySQL): no migrations are pending. Every command that talks to the engine uses `PARITY_ENGINE` when it is set (`podman`, `docker` or `auto`), else the choice saved with [`parity engine`](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-engine), else `auto`: the engine that is running, Docker first when both are. ### parity init [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-init) ```text Usage: parity init [options] ``` | Option | What it does | Default | | --- | --- | --- | | `--force` | overwrite an existing `parity.json` | | | `--from-squire` | read the app's Squire parity kit (settings by name; never passwords) | | | `--health-check string` | Citadel's health check: a command run in the app container (`php health.php`), or a path such as `/up` that Apache must answer | guessed: `health.php`, `health-check`, or a Laravel app's health route | | `--image string` | Citadel base image | `citadel/php-apache:8.5r3` | | `--mode string` | `mount` (your folder is mounted, for developers) or `bake` (code copied in, for testers) | `mount` | | `--mysql` | add MySQL 5.6 (Citadel's "MySQL: yes") | | | `--no-mysql` | no MySQL | | | `--name string` | app name (names the containers) | the folder's name | | `--no-cron` | leave out the Laravel scheduler's cron entry even when the app schedules something | | | `--port int` | local HTTP port for the proxy | `8080` | | `--print` | print the `parity.json` instead of writing it | | | `--public-dir string` | public folder, relative to the app (Citadel's "public directory") | `public` when there is one | | `--sign-in string` | `none`, `fake` (SESAME's fake driver) or `cas` | `none` | ### parity up [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-up) ```text Usage: parity up [--verbose] [--wait 5m] ``` | Option | What it does | Default | | --- | --- | --- | | `--verbose` | also show the build and compose output (it is always in `.parity/up.log`) | | | `--wait duration` | how long to wait for the app's health check | `5m0s` | Exit 1 when the app's own build, deployments or health check failed; 2 when Parity could not run it. An image that is not on this computer is exit 2: the hint is `parity image get`, or, when Citadel has not published a download for it yet, a line that says so ([Citadel's images](https://parity.apps.wayne.edu/docs/guides/images.html#when-citadel-has-not-published-an-image-yet)). Before it starts the app, the MySQL step signs in as the app does; a database volume made with other passwords, or for another database name, stops it there with exit 2 and the way out ([Troubleshooting](https://parity.apps.wayne.edu/docs/troubleshooting.html#mysql-refuses-the-app-s-password)). ### parity status [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-status) ```text Usage: parity status [--json] ``` | Option | What it does | | --- | --- | | `--json` | print JSON (the stable contract) | Shows each piece and its health, then the mirror: your machine and Citadel side by side, one row each for the image, the image id, PHP, the platform, `php.ini`, MySQL, Node and the PHP extensions, marked match, close or differs. ```text Your machine and Citadel citadel/php-apache:8.5r3 YOUR MACHINE CITADEL ✓ Image citadel/php-apache:8.5r3 citadel/php-apache:8.5r3 match ✓ Image id sha256:950dcf67937a sha256:950dcf67937a match ✓ PHP 8.5.12 8.5.12 match ✓ Platform linux/amd64 linux/amd64 match ✓ php.ini Citadel's php8.ini Citadel's php8.ini match ✓ MySQL 5.6.51 5.6.51 match ✓ Node 22.23.4 22.23.4 match ✓ PHP extensions 50 loaded 50 loaded match Node and PHP extensions read from the running app container. Matches Citadel. ``` Node and the extensions come from the running app container, or else the app's image, or else Citadel's image on this computer, asked once per image id. Node is close when only the minor or patch differs and differs across a major. A missing extension differs and an extra one is close; each is listed under the extension row. The `--json` output does not change. Exit 0 when every piece runs and is healthy, 1 when not. ### parity image [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-image) ```text Usage: parity image list [--json] parity image get [tag] [--file x.tar] [--git] [--https] [--keep] [--force] parity image verify [tag] [--file x.tar] ``` The tag defaults to the image in `parity.json`, or Parity's newest Citadel image. [Citadel's images](https://parity.apps.wayne.edu/docs/guides/images.html) explains the download routes and what "matches Citadel" checks. #### parity image list [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-image-list) | Option | What it does | | --- | --- | | `--json` | print JSON (the stable contract) | #### parity image get [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-image-get) | Option | What it does | | --- | --- | | `--file string` | use a tar you downloaded yourself (from the project's page in your browser) | | `--force` | load it again even when the image here already matches | | `--git` | download with git LFS over SSH with your own key, even when `PARITY_GITLAB_TOKEN` is set (without a token, git is the way) | | `--https` | with `--git`, clone over HTTPS (your git credential manager signs in) instead of SSH | | `--keep` | keep the downloaded tar in Parity's cache folder | #### parity image verify [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-image-verify) | Option | What it does | | --- | --- | | `--file string` | check a downloaded tar's sha256 instead of the loaded image | Exit 1 when the image (or tar) differs from Citadel's. ### parity logs [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-logs) ```text Usage: parity logs [app|mysql|proxy|cron:|deployments[:]] [-f] [--tail 100] [--apache] ``` | Option | What it does | Default | | --- | --- | --- | | `--apache` | Apache's error and access logs from `/citadel/logs/apache` (where Citadel keeps them) | | | `-f` | keep following (Ctrl+C stops) | | | `--tail int` | how many lines to start with | `100` | `cron:` shows one [cron entry](https://parity.apps.wayne.edu/docs/reference/parity-json.html#cron-entries)'s stdout and stderr files from `/citadel/logs/cron-jobs`, as Citadel's dashboard does. `parity logs app` shows each run as it happens: `cron: >` the command started, `|` a line of its output, `!` a line of its errors, `<` how it ended. `deployments` shows the deployment scripts' own logs from `/citadel/logs/deployments`: the newest `*.failed.log`, else the newest `*.log`; `deployments:` shows that file. They are read through the app container, so they show while the app is stopped after a failed deployment, which is also why `parity up` ends with the failed deployment's own log. ### parity test [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-test) ```text Usage: parity test [--json] ``` | Option | What it does | | --- | --- | | `--json` | print JSON (the stable contract) | Requests the front page through the proxy, runs the app's health check, makes the requests in `test.requests`, and fails on a PHP fatal or parse error in Apache's log while it ran. 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. When the engine's own connection drops before a check reaches the container (Podman on Windows, now and then), that check is tried once more; see [Podman lost its connection](https://parity.apps.wayne.edu/docs/troubleshooting.html#podman-lost-its-connection). ### parity trust [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-trust) ```text Usage: parity trust [--remove] ``` | Option | What it does | | --- | --- | | `--remove` | take the CA out of your user store again | Puts the app's local https certificate authority in this computer's certificate stores, so the browser stops warning about the app's https address on 127.0.0.1:8443. The CA lives in Parity's per-user config folder (`ca/`); only `ca.crt` goes anywhere, and the CA key never leaves that folder. Per operating system: - **Windows:** adds the CA to your user's Root store with `certutil -user` (no administrator needed); `--remove` deletes it by thumbprint. - **macOS:** adds it to your login keychain with `security add-trusted-cert -r trustRoot`; `--remove` deletes it by thumbprint. - **Linux:** the system store needs sudo, which Parity will not ask for, so it prints the two commands for you to run: `sudo cp` into `/usr/local/share/ca-certificates/` plus `sudo update-ca-certificates` (Debian and Ubuntu), or into `/etc/pki/ca-trust/source/anchors/` plus `sudo update-ca-trust extract` (Fedora and RHEL). When `certutil` is on your PATH and `~/.pki/nssdb` exists, Parity also updates that NSS database itself, because Chrome and Chromium read it. Firefox keeps its own store, so Parity prints the manual step: import `ca.crt` under Settings, Certificates, Authorities. Exit 0 when the store changed (or was printed, on Linux), 2 when it could not run: no `parity.json`, `"https"` off in it, a CA problem (for example `server_name` changed since the CA was made; delete the app's CA folder in Parity's config dir, then `parity up` again and `parity trust` once it exists), or a certificate-store command that failed. ### parity run [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-run) ```text Usage: parity run [--user citadel] [--] command [args...] ``` | Option | What it does | Default | | --- | --- | --- | | `--user string` | run as this user: `citadel` owns the code, so files the tool writes belong to it (root is `--user root`) | `citadel` | Runs one tool in the app container, in `/citadel/src`, the same container `parity up` runs: `composer ci`, `php artisan test`, `npm run build`, instead of a raw `docker run` line. Only flags before the command are Parity's (a leading `--` is accepted and dropped); everything after goes to the tool. The exit code is the command's own. In bake mode Parity says the files the command writes live in the container and vanish on the next `parity up`; in mount mode they land in your folder. ### parity shell [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-shell) ```text Usage: parity shell [--user citadel] [command...] ``` | Option | What it does | Default | | --- | --- | --- | | `--user string` | run as this user: `citadel` owns the code, `prisoner` runs Apache | `root`, as Citadel's build does | Opens in `/citadel/src`. With a command, runs just that command and exits with its code. ### parity down [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-down) ```text Usage: parity down [--volumes] ``` | Option | What it does | | --- | --- | | `--volumes` | also empty the local database and logs (fake data only, but it is gone) | ### parity engine [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-engine) ```text Usage: parity engine [podman|docker|auto] [--json] ``` | Option | What it does | | --- | --- | | `--json` | print JSON (the stable contract) | With no choice, says which engine Parity uses and why: `PARITY_ENGINE`, the saved choice, or the engine that answers. With one, saves it for you on this computer, not for the app, so every app and the desktop app's Settings use it too (they read and write the same `parity/settings.json` in your config folder; `PARITY_APP_CONFIG_DIR` moves it). `auto` clears the choice. `PARITY_ENGINE` still wins where it is set, and the command says so. Anything but `podman`, `docker` or `auto` is exit 2, and nothing is written. ### parity version [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-version) ```text Usage: parity version [--json] ``` | Option | What it does | | --- | --- | | `--json` | print JSON (the stable contract) | Prints the version, the commit it was built from, the Go version and the OS and architecture. ### Environment variables [#](https://parity.apps.wayne.edu/docs/reference/commands.html#environment-variables) | Variable | What it does | | --- | --- | | `PARITY_GITLAB_TOKEN` | a git.wayne.edu personal access token (`read_repository` is enough) for `parity image get`. Read from the environment only, never printed | | `PARITY_PLAIN` | `1` is the same as `--plain` | | `PARITY_STYLE` | `fancy` keeps symbols and color even in a pipe or a log | | `NO_COLOR` | any value turns color off and keeps the symbols | --- Source: https://parity.apps.wayne.edu/docs/reference/parity-json.html ## 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-`) | 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 | `.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:///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 ` and keeps its output in `logs/cron-jobs/.stdout.log` and `.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:` 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. --- Source: https://parity.apps.wayne.edu/docs/troubleshooting.html ## Troubleshooting [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#troubleshooting) Start with `parity check`. It prints one line per finding and, under each one that needs it, the fix for your OS. Fix the first one, then run it again. This page explains the common findings in more depth. ### No container engine [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#no-container-engine) > No container engine is installed (Parity looked for docker and podman). Parity drives an engine; it does not bring one. Install one: | Computer | Recommended | Also works | | --- | --- | --- | | Windows | Podman Desktop (free): `winget install --id RedHat.Podman-Desktop -e` | Docker Desktop, if you already have it | | macOS | Podman Desktop (free): `brew install --cask podman-desktop` | Docker Desktop, if you already have it | | Linux | Podman, from your distribution's package | Docker Engine with its Compose plugin | Open a new terminal afterwards and run `parity check` again. #### Which engine, and licenses [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#which-engine-and-licenses) Podman Desktop is free, which is why it is the recommendation. Docker Desktop's terms ask larger organizations for a paid subscription; if you already have Docker Desktop, Parity works with it as it is. On Linux, Podman and Docker Engine are both free. With both installed, Parity uses the one that is running, Docker first when both are, and `parity check` names the other ("Podman is here too"). To choose for good, save it once (the desktop app's Settings does the same): ```text parity engine podman ``` `parity engine` alone says which one Parity uses and why; `parity engine auto` goes back to the running one. For one terminal only, set `PARITY_ENGINE` to `podman` or `docker`; it wins over the saved choice: ```powershell $env:PARITY_ENGINE = "podman" ``` ```sh export PARITY_ENGINE=podman ``` ### The engine is not running [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#the-engine-is-not-running) Parity found the engine but could not reach it. Open the engine's app (or start its service) and wait until it says it is ready. With Podman on Windows or macOS, `podman machine start` starts the virtual machine it runs in. On Linux with Docker Engine, `sudo systemctl start docker`. #### Podman's machine runs, Podman in it does not answer [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#podman-s-machine-runs-podman-in-it-does-not-answer) > Podman's machine is running, but the Podman service inside it is not answering. Seen on Windows when another WSL distribution with systemd (Ubuntu, say) also has a user 1000: WSL distributions share one cgroup tree, so the machine's own user 1000 session cannot start (`podman machine ssh "systemctl status user@1000.service"` says "Device or resource busy"). Stop the other distribution (`wsl --terminate `), then `podman machine stop` and `podman machine start`. Or make the machine rootful: `podman machine stop`, `podman machine set --rootful`, `podman machine start`. ### Docker Compose v2 is missing [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#docker-compose-v2-is-missing) Parity needs Compose v2 to start the three containers. Docker Desktop includes it; update Docker Desktop if it is old. On Linux with Docker Engine, install the Compose plugin (`docker-compose-plugin` on Debian and Ubuntu). With Podman, Parity runs Docker Compose v2 through `podman compose`, which finds it on your PATH. podman-compose (the Python program) is a different tool, and Parity refuses it. On Linux, install Docker Compose from your distribution (`sudo dnf install docker-compose` on Fedora and RHEL, `sudo apt-get install docker-compose-v2` on Ubuntu). #### Podman's API socket is off [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#podman-s-api-socket-is-off) > Docker Compose is here, but Podman's API socket is off, and Compose talks to Podman through it. On Linux, Docker Compose reaches Podman through Podman's API socket, which systemd starts when asked: `systemctl --user enable --now podman.socket` (rootless, the usual case) or `sudo systemctl enable --now podman.socket` (rootful). On Windows and macOS the machine forwards it for you. ### Rootless Podman and file ownership [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#rootless-podman-and-file-ownership) Under rootless Podman the container's root is you. In mount mode Parity runs the app with `userns_mode: keep-id`, mapped to the image's `citadel` user, so inside the container your files belong to `citadel`, as the source owner on Citadel. As the container starts, Parity gives the `writable` paths to Apache's group, group-writable, as Citadel's deploy does, so Apache, the deployments and the cron entries can all write them. Files Apache writes show on your side with a high user id from your subuid range; you can still delete them. Parity never uses Podman's `:U` mount option, which would hand your folder to the container's ids on your own disk. ### Windows [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#windows) #### Windows containers [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#windows-containers) > The engine runs Windows containers; Citadel's images are Linux images. Switch the engine to Linux containers. In Docker Desktop: right-click its icon by the clock, "Switch to Linux containers...". #### Not on WSL 2 [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#not-on-wsl-2) > Docker Desktop is not using WSL 2 (it is on the older Hyper-V engine). Docker Desktop, Settings, General: turn on "Use the WSL 2 based engine", then Apply and restart. Podman Desktop uses WSL 2 on Windows by default. If WSL itself is missing, `wsl --install` in an administrator PowerShell installs it, after a restart. #### Podman lost its connection [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#podman-lost-its-connection) > Health check: could not ask the app: podman lost its connection twice Podman on Windows reaches its machine over SSH, and a busy WSL can drop that connection for a moment (`ssh: handshake failed` in the details). `parity test` tries each read once more after two seconds, so a single drop no longer fails a healthy app; this message means it dropped twice in a row. Run `parity test` again. If it keeps happening, `parity check` shows the engine, and `podman machine stop` then `podman machine start` resets the connection. ### Line endings [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#line-endings) > These files Citadel runs have Windows line endings (CRLF), which its shell cannot run: build.sh. Git on Windows often checks files out with CRLF line endings. Citadel's shell cannot run a script with them, so neither can Parity, and this is exactly the kind of thing Parity is for: it fails here, not on Citadel. The fix tells git to keep Unix line endings for those files, then checks them out again. On Windows: ```powershell Add-Content .gitattributes "*.sh text eol=lf" git add --renormalize . Remove-Item build.sh; git checkout -- build.sh ``` `parity check` prints the exact lines for your files. Commit `.gitattributes` so everyone gets the same endings. ### Pages load from localhost:5173 [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#pages-load-from-localhost-5173) While `npm run dev` runs, Laravel's Vite plugin writes a `public/hot` file, and every page then loads its scripts and styles from the dev server on `localhost:5173` instead of the built assets. Citadel never runs that dev server and `public/hot` is never deployed, so a page that looks fine through the dev server is not what Citadel serves. `parity check` warns (`vite-hot`) when the public folder has the `hot` file, and `parity test` fails a front page that loads its assets from the dev server. The fix: stop `npm run dev`, delete `public/hot`, and run `npm run build` (Citadel serves the built assets). ### A port is taken [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#a-port-is-taken) > 8080 taken by another program. Stop that program, or set `http_port` (or `database.port` for MySQL) in `parity.json` to a free port. Two Parity apps can run side by side on different ports. When the app that holds the port is this one, already running, `parity check` says so and there is nothing to fix. ### Port 8443 is taken [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#port-8443-is-taken) > Port 8443 is taken by another program. `parity up` says this when `"https": true` and another program already listens on 8443. Unlike `http_port` and `database.port`, Parity's https port is fixed at 8443, so there is no field to move it. Stop the other program, or set `"https": false` in `parity.json` if this app does not need local https. ### The browser still warns about the certificate [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#the-browser-still-warns-about-the-certificate) The app answers over https, but the browser still says the connection is not secure: this computer's certificate stores do not trust the app's local CA yet. Work through these: - **Run `parity trust`** once on this computer. On Windows and macOS it puts the CA in your user store, no admin needed. `parity check`'s `https.trust` finding says OK when your store trusts the CA, and warns with `Fix: parity trust` when it does not (it never fails, so CI stays green). - **Linux:** the system store needs sudo, which Parity will not ask for, so it prints the commands and you run the one that matches your distro: `sudo cp /usr/local/share/ca-certificates/parity-.crt && sudo update-ca-certificates` on Debian and Ubuntu, `sudo cp /etc/pki/ca-trust/source/anchors/parity-.crt && sudo update-ca-trust extract` on Fedora and RHEL. When `certutil` is on your PATH and `~/.pki/nssdb` exists, Parity also adds the CA to Chrome's NSS database itself. - **Firefox** keeps its own store on every OS: import the app's `ca.crt` (the path Parity prints) under Settings, Certificates, Authorities. If `server_name` changed since Parity made the CA, the CA will not sign for the new name: delete the CA folder Parity names, run `parity up` again, then `parity trust`. ### Citadel's image is not here [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#citadel-s-image-is-not-here) > citadel/php-apache:8.5r3 is not on this computer yet. Run `parity image get` ([Citadel's images](https://parity.apps.wayne.edu/docs/guides/images.html) has the three ways it downloads). > Citadel has not published a download for citadel/php-apache:8.4r5 yet. Parity runs Citadel's own images only, and this one has no download yet. Set `image` in `parity.json` to a tag that `parity image list` can download, or ask the Citadel team to publish it ([When Citadel has not published an image yet](https://parity.apps.wayne.edu/docs/guides/images.html#when-citadel-has-not-published-an-image-yet)). > citadel/php-apache:8.5r3 is here, but it is not the build Citadel runs. The image has Citadel's tag but a different id, usually from an old download or a local build. `parity image get` replaces it with Citadel's own. ### arm64 computers [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#arm64-computers) Citadel's images are amd64. On an arm64 computer they run emulated, under Rosetta or QEMU: slower, but real, and still Citadel's own image. - **Apple Silicon.** Docker Desktop runs amd64 images with Rosetta when "Use Rosetta for x86_64/amd64 emulation on Apple Silicon" is on (Settings, General); with it off, they run on slower QEMU emulation. Podman's machine uses Rosetta when it is turned on (macOS 26 or later), else QEMU. `parity check` says whether your engine uses Rosetta and gives the steps to turn it on; when it cannot read Docker Desktop's setting, it says so in an info line. - **Windows on Arm.** Citadel's images and MySQL 5.6 run under QEMU emulation, which is slow. Give the first `parity up` a few minutes. - **arm64 Linux.** Install QEMU's amd64 emulation once: `docker run --privileged --rm tonistiigi/binfmt --install amd64`. Without it, Citadel's image and MySQL 5.6 cannot start. ### The app does not come up [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#the-app-does-not-come-up) `parity up` shows the last lines that explain a failure, and the whole output is in `.parity/up.log`. Then: - **The build failed**: your `build.sh` failed the way it would on Citadel. Run `parity up --verbose` to watch it. - **A deployment failed**: a script in `deployments/` exited non-zero. `parity logs app` shows its output. - **The health check never passed**: `parity logs app --apache` shows Apache's error log, where a PHP fatal error lands. `parity shell` opens a shell in the container to look around. Exit 1 means your app's build, deployments or health check failed; exit 2 means Parity could not run it at all. ### The proxy step warns that the front page is slow [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#the-proxy-step-warns-that-the-front-page-is-slow) > HAProxy is up, but the app's front page took longer than 10 seconds to answer (its health check passed). parity logs app shows why. The proxy step starts HAProxy only after the app's own health check has passed, then asks it for `/`, waiting 10 seconds per try. A slow first page (cold caches, a slow first query) now warns instead of failing, because the proxy itself is fine. `parity logs app` shows what the page was doing while it took so long. ### MySQL refuses the app's password [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#mysql-refuses-the-app-s-password) > \[FAIL\] MySQL is running, but it refuses the app's password: its volume (parity-hello_mysql-data) was made with other passwords than .parity/mysql.env. MySQL's image reads `.parity/mysql.env` only once, when it first makes the database volume. After that the volume keeps the passwords it was made with. So when `.parity/` is deleted (`git clean -x`, a fresh clone of the same app) or a second folder runs an app with the same `name`, Parity writes new passwords and MySQL refuses them. Its health check still passes, because `mysqladmin ping` says yes even when access is denied, so `parity up` signs in as the app before it goes on, and stops here instead of leaving every page to say "Access denied". Three ways out: - `parity down --volumes`, then `parity up`: a fresh local database (its data is erased). - Put the old `.parity/mysql.env` back, if you still have it. - Give this copy its own `name` in `parity.json`, so it gets its own containers and volume (and its own ports). The same check catches a `database.name` changed after the volume was made ("database ... is not the app's"): MySQL made the database and the app's user once, for the old name. Start over with `parity down --volumes`, or set the name back. ### The running app's own checks [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#the-running-app-s-own-checks) With a `parity.json` and a running engine, `parity check` also asks the running app four things: whether `APP_KEY` is set (Laravel apps), whether the folders in `writable` are there and writable by Apache, whether the app can sign in to its MySQL, and whether any migrations are pending (Laravel apps with MySQL). With the app stopped it says so and skips them. The failures: #### APP_KEY is not set [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#app-key-is-not-set) > APP_KEY is not set. The local `.env` has no `APP_KEY`, or it is still the placeholder from `.env.example`, and Laravel cannot boot without one. Generate one for the local app: ```text parity run -- php artisan key:generate ``` Parity reads the value only to compare it; it never prints it. #### A writable folder is not writable by Apache [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#a-writable-folder-is-not-writable-by-apache) > storage is not writable by Apache. Each folder in `writable` is given to Apache's group, group-writable, as the app container starts. When one is not writable, start the app over so the entrypoint does it again: ```text parity down parity up ``` When the folder is not in the app at all, `parity check` warns instead ("is not in the app, so Parity could not check it"): create the folder, or remove it from `writable`. #### The app cannot sign in to its MySQL [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#the-app-cannot-sign-in-to-its-mysql) > ERROR 2002 (HY000): Can't connect to MySQL server on 'mysql' (111) `parity check` signs in to the local MySQL the way the app will, so a refused connection or a refused password shows up in the check, not on every page. It usually means the database volume was made before the current `.parity/mysql.env` (a deleted `.parity/`, a second folder with the same app name); [MySQL refuses the app's password](https://parity.apps.wayne.edu/docs/troubleshooting.html#mysql-refuses-the-app-s-password) has the three ways out, the first being: ```text parity down --volumes parity up ``` ### The front page answers 503 a minute after parity up [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#the-front-page-answers-503-a-minute-after-parity-up) > \[FAIL\] GET / answered 503, a server error and `parity logs proxy` says `backend app has no server available` or `DNS timeout status`. That is Parity 0.1.0 on Podman: its proxy asked Docker's DNS address for the app container on every engine, Podman's DNS lives elsewhere, and about a minute after `parity up` HAProxy gave up on the app. Releases after 0.1.0 ask whichever engine runs the proxy. Upgrade Parity, then `parity down` and `parity up` (or, until you can upgrade, `PARITY_ENGINE=docker`). ### parity test says Proxy trust [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#parity-test-says-proxy-trust) > \[WARN\] Proxy trust 1 request had forwarded headers HELMET did not trust: the app trusts another proxy address than Parity's. Set HELMET_PROXIES (or TRUSTED_PROXIES) in the app's local .env to Parity's proxy network; see docs/troubleshooting.md. This is a note, not a failure: `parity test` still passes. It means HELMET, the stack's security-headers package, saw `X-Forwarded-Proto` and `X-Forwarded-For` from an address it does not trust, and ignored them. On Citadel the `citadel` preset trusts `172.18.0.1`, Citadel's HAProxy, and stays right; on your machine Parity's proxy reaches the app from its own address, so the app reads every request as plain http from the proxy's address. To fix it, set `HELMET_PROXIES` (or the app's `TRUSTED_PROXIES`) in the local `.env` to the address Parity's proxy uses: `parity logs app` shows the log line, and its remote address is that address. ### Mount mode and the kit's deployments [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#mount-mode-and-the-kit-s-deployments) **My vendor/ or node_modules/ changed after parity up.** In mount mode the container works in your own folder, so the kit's deployments (which call `scripts/release.sh`) install Composer and npm packages and migrate there. `parity init --from-squire` warns about it. Use bake mode, or set `SQUIRE_NPM=skip` and `SQUIRE_MIGRATE=0` in `.env.squire` where skipping them is safe. ### No parity.json here [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#no-parity-json-here) `parity up` stops, and `parity check` counts it as a failure, each with one of these two lines naming the command that writes the file: ```text no parity.json in , but this app has Squire's kit. Run: parity init --from-squire no parity.json in . Run: parity init (it asks nothing; it guesses, and you edit). ``` The first is for a folder that has Squire's kit (docker-compose.squire.yml). The second is for a folder that does not. ### parity.json is refused [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#parity-json-is-refused) Parity reads `parity.json` before it starts anything, and says which field is wrong: - **A cron schedule "is not one Citadel takes".** Citadel's dashboard takes `*`, `*/N` or a list for minute and hour, and `*` or a list for the rest. Write a range as a list (`1,2,3,4,5`, not `1-5`), and a day as its number. - **A cron command with `;`, `&&`, `|`, `>` or `$`.** On Citadel that would run on the host, outside your app. Put the steps in a script in the app and name it. - **`sign_in "fake"` needs a local environment.** SESAME's fake driver refuses to boot anywhere else, so set `environment` to `local`, `development`, `dev`, `testing` or `test`. - **An unknown field.** A typo is caught rather than ignored. [parity.json](https://parity.apps.wayne.edu/docs/reference/parity-json.html) lists every field. ### A cron entry does nothing [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#a-cron-entry-does-nothing) `parity logs cron:` shows its stdout and stderr files, and `parity logs app` shows each run as it starts and ends. Entries start at the top of the minute, so give one a minute. They run as `prisoner` from `/citadel/src`, as on Citadel: a command that works in `parity shell` but not as a cron entry usually needs a file `prisoner` cannot read or write. ### Starting over [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#starting-over) `parity down --volumes` stops the app and empties the local database and logs (fake data only, but it is gone). `.parity/` is rewritten on every `parity up`, so deleting it is safe too, except for the local MySQL passwords: the next `parity up` makes new ones, and an old database volume will not open with them. Run `parity down --volumes` first. If you forgot, `parity up` says so at its MySQL step ([MySQL refuses the app's password](https://parity.apps.wayne.edu/docs/troubleshooting.html#mysql-refuses-the-app-s-password)).