Skip to content
Menu

Local parity#

To run your app on Citadel's own PHP image, behind Citadel's proxy, with MySQL 5.6 beside it, use Parity. The rest of this page is Squire's older parity kit, which is deprecated.

Use Parity#

Parity is the stack's tool for running Citadel on your computer: one program, parity, for Windows, macOS and Linux (x64 and arm64), for any app, with or without Squire. It runs on Docker or Podman (Podman is recommended) and needs no PHP or Composer on your computer. It uses Citadel's own PHP image (checked against Citadel's, byte for byte), Citadel's vhost.conf and php.ini, an HAProxy that adds the same forwarding headers, and MySQL 5.6. It runs the files Squire writes (build.sh, deployments/, the health check) the way Citadel does, applies the app's sign_in setting, and runs its Citadel-style cron entries. Its commands are check, init, up, down, status, logs, shell, image and test.

Coming from this kit, in the app's folder:

parity check                 # what to fix on this computer, one finding per line
parity init --from-squire    # writes parity.json from docker-compose.squire.yml and .env.squire
parity image get             # Citadel's image, checked against Citadel's
parity up                    # build, start, and print the address

parity init --from-squire carries the kit's settings over (base image, public folder, ports, database name, time zone, deployments) and leaves passwords and every other value behind; 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, and the kit's scheduler and worker services become one cron entry that runs Laravel's scheduler every minute, because Citadel has cron and no services. Parity's README has the install line for each OS and the full command list.

Squire still does its own job: it writes the files Citadel runs and checks them with squire doctor. Squire gets the app onto Citadel; Parity runs Citadel on your computer.

In CI, the same MySQL pin checks every merge: Preflight's mysql56-migrate component (0.6.0) runs the app's migrations against mysql:5.6.51 on an amd64 runner, and PROCTOR's mysql56-ci check warns when an app with migrations has no such job. Parity catches a bad migration on your computer; the pipeline catches the one that slipped past.

The parity kit is deprecated#

The rest of this page sets up the kit for teams that still use it: your app on the Citadel image, behind an HA-Proxy that adds the same forwarding headers, with MySQL 5.6.51 beside it. Finish Citadel setup first if you have not run squire init yet.

Requirements#

Needs Docker with Compose v2. Windows needs Docker Desktop with the WSL 2 backend; no shell other than PowerShell is required.

On Windows, keep the source in the WSL 2 filesystem. Advice, not a requirement: keep the app's source tree inside the WSL 2 Linux filesystem (for example under ~/src in your WSL distribution) and run scripts/parity.sh from there, not from a Windows folder such as C:\Users\you\... reached through /mnt/c. Bind mounts from the Windows side are much slower (Composer and npm installs feel it most), and file ownership and permissions do not map cleanly; that is the cause of the Permission denied failure described under the bind-mount question (OPEN_QUESTIONS 15). The PowerShell scripts\parity.ps1 still works from a Windows folder, only slower.

Engines and licenses#

Squire needs any engine that runs Docker Compose v2 compatible files. The ones named here:

  • Docker Engine on Linux: open source, Apache 2.0.
  • Docker Desktop on Windows with the WSL 2 backend: a commercial product, free for small business, personal and educational use, and paid for larger organizations, so check your own license.
  • Podman with a Compose v2 compatible provider, and Colima on macOS: expected to work, not tested here.

Only Docker Desktop and Docker Engine have been run.

Starting parity#

# Linux and macOS
cp .env.squire.example .env.squire     # then set the passwords
scripts/parity.sh up                   # or: scripts/parity.sh up --fallback

# Windows (PowerShell 5.1 or 7)
Copy-Item .env.squire.example .env.squire
scripts\parity.ps1 up                  # or: scripts\parity.ps1 up -Fallback

Give each app its own SQUIRE_PROJECT in .env.squire. Apps on one name are one compose project: they share the database and the record of which deployments/ files already ran, so the second app's release is skipped as already run (see Troubleshooting). up warns while the name is the default squire-app.

parity.ps1 has been run end to end on Windows PowerShell 5.1 (2026-11-10, on the fallback and on Citadel's citadel/php-apache:8.5r3); CI runs it on PowerShell 7. An app made before that fix gets it with squire update: on 5.1 the old script stopped on a raw NativeCommandError where it meant to say the base image is missing.

Commands: up, down, reset (also removes volumes), logs [service], shell [service], status, pin (prints the digests of the images you have pulled, so you can pin them).

What it starts#

It starts the app container from the Citadel image (built by Citadel's build_images command, or pulled from wherever you keep it) with your source mounted at /citadel/src, runs your deployments/ as the citadel user the way Citadel does, and puts an HA-Proxy in front that adds the same forwarding headers. MySQL 5.6.51 is reachable from the app as host mysql and from your machine on 127.0.0.1:3307. Containers drop capabilities, set no-new-privileges, and carry memory and process limits. The database port is bound to loopback only. The Vue layer's compose file adds a Node 22 service, pinned to the same major as the Citadel image, for frontend tooling.

The compose file's portable profile starts nothing on a plain up. Named, it runs the portable image instead: the code baked in, one image as migrate, web, worker and scheduler, as a non-root user in group 0 on 8080, the way a platform other than Citadel runs it.

No access to the real image?#

--fallback builds an approximation from the official php image plus Citadel's extensions. It is good for trying Squire out and not for proving parity. If the build step fails with a permission error writing vendor/, the source folder is not writable by the container's citadel user (uid 1000 by default); on Linux set SQUIRE_SOURCE_UID and SQUIRE_SOURCE_GID to yours.

Next#

Read The release script for what runs inside the app container, or Citadel setup for the dashboard side of the same pipeline.