Skip to content

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.

See the packing list Meet the party

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.

  1. build.sh Citadel's build hook. System packages only, POSIX sh, no Composer or npm (S1).
  2. deployments/001-first-release.sh Runs once per app and calls the release with the smoke test off; Apache is not up yet.
  3. scripts/release.sh The 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.
  4. health.php Citadel's health check: one request to /up, never boots the framework.
  5. The parity kit 19 files docker-compose.squire.yml, .squire/, .env.squire.example, scripts/parity.sh and scripts/parity.ps1: Citadel on your machine, and the portable image for everywhere else. The local half is deprecated: Parity takes it over.
Squire's satchel
To the Citadel From my-app Holds 25 files

5 of 5 packed, buckled for deploy day

Try the other commands

~/my-app

$ 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

  • S1build.sh runs 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 gate or proctor check.
  • S15auth.json stays 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 /up at 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.env files 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.

~/my-app excerpt

$ 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.

  1. Your browser on localhost
  2. HA-Proxy adds X-Forwarded-For and -Proto
  3. Your app Citadel PHP image, run as citadel
  4. MySQL 5.6.51 mysql inside, 127.0.0.1:3307 outside

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

  • up
  • down
  • reset
  • logs
  • shell
  • status
  • pin

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.

  1. Point the dashboard at the kit

    Build script build.sh, health check ["php","health.php"], Quick Update post-script ./scripts/release.sh as user citadel.

  2. Commit the lock files

    composer.lock, and package-lock.json or pnpm-lock.yaml if you have a frontend. The release installs from them and never runs an update.

  3. Mark the scripts executable

    Git on Windows forgets: git update-index --chmod=+x build.sh scripts/*.sh deployments/*.sh

  4. Settings in the configuration file

    Set SQUIRE_* values in the app's ./.env configuration file, never in a file in the repository. The dashboard has no environment field; its configuration-files step, after the wizard, writes ./.env into the source tree. A Laravel app reads it already; a raw PHP app loads it with vlucas/phpdotenv. All of them are optional.

0
pass
1
findings: drift for init --check, a failed rule for doctor
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.

  1. HELMETsets security headers
  2. SESAMEsigns the user in
  3. WayneUIrenders the page
  4. PROCTORchecks the code
  5. Preflightruns CI
  6. 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.ini holds 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/. Use scripts/release.sh as the Quick Update post-script too.
  • The release asks proctor gate for a go or no-go. A no-go is a report by default; set SQUIRE_PROCTOR=enforce and it stops the release before the build and the migrations.