The Citadel kit
Squire
Suits you up for the Citadel.
A squire carries the knight's kit. This one carries your app's. squire init writes the scripts Citadel runs when you deploy and squire doctor checks them. To run your app on your laptop on the same PHP image and MySQL 5.6 as Citadel, behind the same kind of proxy, Squire rides with Parity.
$ composer require waynestate/squire --dev
Already packed into every Sourdough app, and WELD deploys to Citadel through it. Use Squire on its own to bring an app you already have onto Citadel.
Before you ride · Any PHP app
Get started with Squire
Pack your app for the Citadel and try it at home first.
You are a coding agent. Read https://squire.apps.wayne.edu/llms.txt and ask ADVISOR.
Install it with `composer require waynestate/squire --dev`, then run `vendor/bin/squire init` at the root of your app.
Ask me before you guess.
vendor/bin/squire init
The packing list for deploy day
squire init writes the files Citadel needs from templates, for raw PHP, Laravel or a static site, and adds a Vue layer when package.json has Vue. It records a SHA-256 of each file in .squire.json. A file you edited is never written over unless you pass --force.
-
build.shCitadel's build hook. System packages only, POSIX sh, no Composer or npm (S1). -
deployments/001-first-release.shRuns once per app and calls the release with the smoke test off; Apache is not up yet. -
scripts/release.shThe idempotent release: install from the lock file, audit, ask PROCTOR's gate for a go or no-go, build, migrate, smoke-test/up. Also your Quick Update post-script. -
health.phpCitadel's health check: one request to/up, never boots the framework. -
The parity kit 19 filesdocker-compose.squire.yml,.squire/,.env.squire.example,scripts/parity.shandscripts/parity.ps1: Citadel on your machine, and the portable image for everywhere else. The local half is deprecated: Parity takes it over.
5 of 5 packed, buckled for deploy day
Try the other commands
$ vendor/bin/squire init
created build.sh (written from the template)
created deployments/001-first-release.sh (written from the template)
created scripts/release.sh (written from the template)
created health.php (written from the template)
created oracle-check.php (written from the template)
created .gitattributes (written from the template)
created docker-compose.squire.yml (written from the template)
created .squire/Dockerfile (written from the template)
created .squire/Dockerfile.dockerignore (written from the template)
created .squire/base-fallback.Dockerfile (written from the template)
created .squire/apache-hardening.conf (written from the template)
created .squire/fallback/citadel-apache-entrypoint (written from the template)
created .squire/fallback/citadel-deploy (written from the template)
created .squire/haproxy.cfg (written from the template)
created .squire/php.ini (written from the template)
created .squire/php-web.ini (written from the template)
created .squire/vhost.conf (written from the template)
created .squire/portable.Dockerfile (written from the template)
created .squire/portable.Dockerfile.dockerignore (written from the template)
created .squire/portable/squire-entrypoint.sh (written from the template)
created .squire/portable/ports.conf (written from the template)
created .squire/portable/vhost.conf (written from the template)
created scripts/parity.sh (written from the template)
created scripts/parity.ps1 (written from the template)
created .env.squire.example (written from the template)
Target: laravel. Wrote .squire.json.
Next: git update-index --chmod=+x build.sh deployments/001-first-release.sh scripts/release.sh .squire/fallback/citadel-apache-entrypoint .squire/fallback/citadel-deploy .squire/portable/squire-entrypoint.sh scripts/parity.sh
Parity: the parity group is deprecated (removed no sooner than 0.12.0). Parity runs Citadel on your computer now; `parity init --from-squire` carries this kit over: https://git.wayne.edu/enterprise-apps/parity
Every shell script runs with set -euo pipefail, prints a [squire] ==> step N marker, and gives the same result when you run it twice. Pack half the bag with --only=release or --only=parity.
vendor/bin/squire doctor
The squire inspects the armor
Doctor reads your repository and checks the rules a machine can decide. It doesn't run your app or touch a server. A fail exits 1 and a warning or info note doesn't, so if you want doctor to block a merge, run it in CI.
fail exits 1 warn reported info noted
- S1
build.shruns no Composer or npm. - S3Every script has
set -e. - S4No download piped into a shell.
- S8No CRLF in shell scripts.
- S9Build, first release and release are three jobs.
- S12Install from the lock file; never update.
- S14The release runs
proctor gateorproctor check. - S15
auth.jsonstays out of git. - S16Laravel runs
optimize. - S17Migrations run and stay old-code friendly.
- S19Refuses to run as root.
- S20PROCTOR is a report, never a bare command.
- S21The release requests
/upat the end. - S22One marker per step.
- S35Locally, the Citadel PHP image.
- S36A forwarding proxy in front.
- S37Locally, MySQL 5.6.
- S41The Docker socket is not mounted.
- S42
.envfiles stay out of git. - S50Lock file, audit and MySQL 5.6 are PROCTOR's: run
proctor check. - S55The health check never boots the framework.
- S57npm installs with
--ignore-scripts. - S67Images pinned by digest.
- S70Containers drop capabilities.
- S71Citadel's health-check timing.
- S78A Vue app keeps
node_modules/out of git.
Every rule, its level and why it matters: BEST_PRACTICES.md. Drift from the templates is a warning under S9, never a failure; your copies are yours to edit.
$ vendor/bin/squire doctor
PASS S1 build.sh runs no composer or npm commands. [build.sh]
PASS S12 `composer install --no-dev` from the lock file.
PASS S14 The release script runs PROCTOR (proctor gate or proctor check).
PASS S20 PROCTOR runs as a report and cannot stop the release.
PASS S55 health.php is an artisan-free health check. [health.php]
WARN S8 .gitattributes does not force LF for shell scripts. Add `*.sh text eol=lf`, and `*.conf text eol=lf`, `Dockerfile text eol=lf` and `*.Dockerfile text eol=lf`, which PROCTOR checks too.
WARN S67 Not pinned by digest: citadel/php-apache:8.4r5. Run `scripts/parity.sh pin` and put the digests in .env.squire.
RESULT: pass (0 fail, 2 warn, 0 info, 5 pass)
Local parity
Practice on the real field
The parity kit runs your app on the Citadel PHP image, behind an HA-Proxy that adds the same forwarding headers, with MySQL 5.6.51 beside it. If something would only break on Citadel, you should see it on your laptop first.
- Your browser on localhost
- HA-Proxy adds X-Forwarded-For and -Proto
-
Your app
Citadel PHP image, run as citadel -
MySQL 5.6.51
mysqlinside,127.0.0.1:3307outside
Docker with Compose v2.
cp .env.squire.example .env.squire # then set the passwords
scripts/parity.sh up # or: scripts/parity.sh up --fallback
Docker Desktop with the WSL 2 backend. PowerShell 5.1 or 7; no other shell needed.
Copy-Item .env.squire.example .env.squire
scripts\parity.ps1 up # or: scripts\parity.ps1 up -Fallback
Commands
updownresetlogsshellstatuspin
pin prints the digests of the images you pulled, so you can pin them. reset also removes the volumes.
Containers drop capabilities, set no-new-privileges and carry memory and process limits; the database listens on loopback only. The compose file refuses to start without real passwords.
No access to the real image? --fallback builds an approximation from the official PHP image plus Citadel's extensions. It's fine for a practice bout. It doesn't prove parity.
Citadel setup
Onto the field
Squire itself runs on your machine and in CI. Only the scripts it wrote go to Citadel.
-
Point the dashboard at the kit
Build script
build.sh, health check["php","health.php"], Quick Update post-script./scripts/release.shas usercitadel. -
Commit the lock files
composer.lock, andpackage-lock.jsonorpnpm-lock.yamlif you have a frontend. The release installs from them and never runs an update. -
Mark the scripts executable
Git on Windows forgets:
git update-index --chmod=+x build.sh scripts/*.sh deployments/*.sh -
Settings in the configuration file
Set
SQUIRE_*values in the app's./.envconfiguration file, never in a file in the repository. The dashboard has no environment field; its configuration-files step, after the wizard, writes./.envinto the source tree. A Laravel app reads it already; a raw PHP app loads it withvlucas/phpdotenv. All of them are optional.
0- pass
1- findings: drift for
init --check, a failed rule fordoctor 2- the tool itself could not run
Squire's own repository rides along: php bin/docs-site.php turns docs/ into the committed pages under site/docs/, renders GitHub alert callouts ([!NOTE], [!TIP], [!WARNING] and [!DANGER]) as labeled asides, groups consecutive tab="..." code fences into labeled code tabs that read without JavaScript, generates a changelog page from CHANGELOG.md when the nav lists one, and lets a site theme its docs with a header partial and a stylesheet through a theme key in docs/docs.json. The kit's docs.css styles the pages in light and dark themes (an explicit reader choice first, then the system setting), with every text pair at WCAG AA contrast in both.
The platform
Letters for the castle
A good squire carries messages too. When we find something Citadel could do better, we write it up and send it to the platform team privately. Squire never touches a server, and none of its scripts wait on a proposal.
Its place in WELD
Every knight rides with a party
Squire is one part of WELD, the Wayne State application stack. It rides last. The parts ahead of it handle the headers, sign-in, the interface, the checks and CI, and Squire takes the finished app to Citadel.
HELMETsets security headers
SESAMEsigns the user inWayneUIrenders the page
PROCTORchecks the code
Preflightruns CI
Squiredeploys you are here
Also in the stack
Around your app
Booster gets you onto a supported PHP
Rollcall every app answers “present”
ADVISOR what applies, and what next
Drawbridge the Citadel sign-in gateway
Squire the Citadel kit
Parity Citadel on your computer
Known limits
Scuffs on the leather
Squire 0.11.1 is tagged and on Packagist. Where we had to guess how Citadel behaves, OPEN_QUESTIONS.md lists each guess and the default it chose.
- The local
php.iniholds the safe defaults HELMET also enforces at runtime, not the platform's file. - The Citadel image has no registry digest to pin yet; doctor warns under S67 until you run
pin. - A full Update may not refresh
vendor/. Usescripts/release.shas the Quick Update post-script too. - The release asks
proctor gatefor a go or no-go. A no-go is a report by default; setSQUIRE_PROCTOR=enforceand it stops the release before the build and the migrations.