The release script#
This page walks through scripts/release.sh, the one common script every app gets, in the order its steps run. It is the artifact that lands on Citadel; read Citadel setup first if you have not wired the dashboard yet.
What it is#
scripts/release.sh is the idempotent release: preconditions, composer install --no-dev from the lock file, audit, PROCTOR's deploy gate (a report by default, a stop with SQUIRE_PROCTOR=enforce), frontend build, Laravel migrate --force, optimize and the restart of the long-lived processes, an Oracle connection check (a report, never a gate), and a /up smoke test. It runs from the first-release hook and from the Quick Update post-script (user citadel, script ./scripts/release.sh).
Its neighbors in the kit:
| File | What it is |
|---|---|
build.sh |
Citadel's build hook: system packages only, POSIX sh, runs as root with no app source. No Composer, no npm. |
deployments/ |
Runs once per app: calls the release script with the smoke test off (Apache is not up yet). |
health.php |
Citadel's health check (["php",): one HTTP request to /up, never boots the framework. |
oracle-check. |
The plain-language Oracle connection check the release runs: settings, host, port, driver, login. A report, never a gate; silent when the app has no ORACLE_* settings. |
Every shell script uses set -euo pipefail (build.sh uses set -eu, because Citadel runs it with /bin/sh), prints a [squire] ==> step N: ... marker for each step, and can be run twice with the same result.
Idempotence and step markers#
Safe to run twice: every step repeats with the same result (S10). Each step prints a marker such as [squire] ==> step 4: composer install from the lock file, without dev packages, and a failure names the step: [squire] FAILED at step N (name): reason with the exit code and line number. A release script that is not idempotent is just a rehearsal that happens to ship.
Step by step#
- check preconditions: refuses to run as root unless
SQUIRE_ALLOW_ROOT=1(files it creates could not be written by the web process); requirescomposer.jsonandcomposer.lockin the app root (the lock file is the release, S13); requiresphpandcomposeron PATH; resolves the framework (autodetects Laravel fromartisan, otherwiseraw); requires.envwhenSQUIRE_REQUIRE_ENVresolves to1(Laravel always does); picks the smoke URL (http://127.0.0.1:80/upfor Laravel,http://127.0.0.1:80/up.phpfor raw PHP). - create writable directories: creates the
SQUIRE_WRITABLE_DIRSentries, orstorage bootstrap/cachefor Laravel by default. - package download caches: skipped when
SQUIRE_CACHE_DIR=off, which leaves Composer's and npm's own defaults alone. Otherwise it creates$SQUIRE_CACHE_DIR/composerand$SQUIRE_CACHE_DIR/npm(the default.cache/squireis relative to the app root, an absolute path is used as is), writes a.gitignoreof*and an.htaccessofRequire all deniedinto the folder when they are missing (so git ignores the cache without touching the app's own.gitignore, and Apache never serves it), and pointsCOMPOSER_CACHE_DIRandnpm_config_cacheat the two folders unless the environment already sets them (a value the host set wins). The app folder survives a Citadel Update, the container home does not, so the next release installs from what this one downloaded. It notes both cache paths in the log. - composer install from the lock file, without dev packages: logs the Composer version (it moves at every container start, S58), then
composer install --no-dev --optimize-autoloader --no-interaction --no-progress --prefer-dist. - composer audit:
composer audit --locked --no-interaction. By default (SQUIRE_COMPOSER_AUDIT=report) a non-zero exit prints a warning and the release goes on;failstops it,skipskips it. - PROCTOR gate: see below. It runs before the frontend build and the migrations, so an enforced no-go stops the release before it touches the database.
- frontend install and build: skipped without a
package.jsonor withSQUIRE_NPM=skip. Withpackage-lock.jsonit runsnpm ci --prefer-offline(with--ignore-scriptswhenSQUIRE_NPM_IGNORE_SCRIPTS=1); withpnpm-lock.yamlit runscorepack pnpm install --frozen-lockfile; withyarn.lockit runs Yarn through corepack, Yarn 1 ascorepack yarn install --frozen-lockfile --non-interactive(with--ignore-scripts), and Yarn 2 or later (a lock with a__metadata:block) ascorepack yarn install --immutable(with--mode=skip-build), which needs"packageManager": "yarn@..."inpackage.jsonand stops without it, because corepack would hand the lock to Yarn 1; with none of the three it fails, telling you to commit one or setSQUIRE_NPM=skipif the built assets are committed. The packages named inSQUIRE_NPM_REBUILDthen run their own install scripts, and nothing else does (npm rebuild,pnpm rebuildoryarn rebuild; Yarn 1 has no rebuild of named packages, so npm rebuilds them in itsnode_modules). With npm older than 11.10 and amin-release-ageline in.npmrc, it notes that this npm ignores the line (the lock file still decides what installs). It then runs thebuildscript (orSQUIRE_NPM_BUILD_SCRIPT) whenpackage.jsondefines it. - laravel migrate (Laravel only):
php artisan migrate --forcewhenSQUIRE_MIGRATE=1. - laravel optimize (Laravel only):
php artisan optimizewhenSQUIRE_ARTISAN_OPTIMIZE=1. After this the config is cached and.envis no longer read, soenv()works only insideconfig/(S16). - laravel restart long-lived processes (Laravel only): skipped when
SQUIRE_ARTISAN_RESTART=0. Whenphp artisan reload --helpsucceeds it runsphp artisan reload; otherwise it runsphp artisan queue:restartandphp artisan schedule:interrupt, each only when its own--helpsucceeds, and notes the skip when neither exists. A failing command is a warning naming the command and its exit code, and the release goes on. A worker that keeps running holds the old code in memory until it restarts, so the step sits after the caches are built and before the smoke test. - check Oracle (never fails the release): runs
php oracle-check.phpwhen the file exists, and notes a skip when it does not (the app does not use Oracle). - check opcache (never fails the release): reports whether the web server sees changed files by itself. With the kit's default (
SQUIRE_OPCACHE_VALIDATE=1, files checked every 2 seconds) it is a note. With0, meant for an image that bakes its code in, Apache keeps serving the PHP it compiled before this release until it restarts, so after a release with Apache running this is a warning namingSQUIRE_OPCACHE_VALIDATE=1; in the first-release hook, before Apache starts, it is a note. See Image hardening. - smoke test the health endpoint: skipped when
SQUIRE_SMOKE=0(Apache is not running inside the first-release hook). Otherwise it requestsSQUIRE_SMOKE_URLup toSQUIRE_SMOKE_RETRIESattempts (default 5), sleepingSQUIRE_SMOKE_DELAYseconds (default 2) between them, and fails unless the answer is HTTP 200.
PROCTOR: the deploy gate#
The release asks PROCTOR's deploy gate, proctor gate, for a go or no-go on this commit. The gate runs the deploy-time checks (the PHP floor and runtime, the Laravel line and its PHP range, the lock file, known advisories and the overrides) and ratchets them against a baseline: a failure the running release already had is held, and only a new failure, a first release that fails, or an expired override blocks. The squire holds the gate; the proctor says who may pass.
-
Report or stop. By default (
SQUIRE_PROCTOR=auto) a no-go is a warning and the release goes on: a failing post-script cannot undo a Quick Update, because the new commit is already live (S20). WithSQUIRE_PROCTOR=enforcea no-go stops the release before the frontend build and the migrations: the first release never comes up healthy, and a Quick Update keeps the new commit checked out, so fix the BLOCK lines (or record a dated override inpolicy-overrides.json) and re-run. A gate that could not decide (exit 2) is a warning underautoand a stop underenforce.SQUIRE_PROCTOR=skipskips the step. -
The record. Every gated release writes its verdict to
storage/squire/proctor-gate.json(SQUIRE_PROCTOR_RECORD_DIR). When the release goes on (a go, or a reported no-go, which goes live anyway) that verdict is copied toproctor-gate-baseline.json, and the next release passes it to the gate as--baseline. A stopped release leaves the baseline alone, so re-running after a stop is judged against the release that is really live. The folder gets a.gitignoreof*. The first gated release has no baseline, so every failure blocks it. -
The runtime. The gate also grades the PHP that will serve the app for PROCTOR's unpatched check, passed as
--php-runtime(SQUIRE_PHP_RUNTIME, defaultauto).autoasks the php that runsrelease.sh, because that is the one serving the app, and cuts any suffix (8.4.27-devis graded as8.4.27); the log saysgate: grading PHP 8.4.27. AnX.Y.Zvalue is graded as given, for a host where the release runs under another php than the web server.skipgrades no runtime. A value that is notX.Y.Z(say8.4) or a php that does not answer is a note, and the gate runs without the flag. The olderproctor checkfallback never gets it. -
An older PROCTOR. When the installed PROCTOR has no
gatecommand, the step prints a warning naming its version, runsproctor checkas before (a failed check is a report, or a stop underenforce), and writes no record. Updatewaynestate/proctorto a release that has the gate. -
Which PROCTOR.
SQUIRE_PROCTOR_BINwhen set; otherwisevendor/bin/proctor, thenproctoron PATH. PROCTOR is a dev dependency, so on Citadel--no-devhas removed it by now, and the release fetches it: it reads the version yourcomposer.lockpins underpackages-dev(a plain release such as0.15.1), installs that version withcomposer create-project waynestate/proctor ... --no-devinto.cache/squire/proctor/<version>and runs it, so the gate grades the release with the same PROCTOR your CI ran. The log saysfetched into the release cachethe first time andfrom the release cacheafter that; a new version in the lock is fetched once. A failed fetch leaves nothing behind (the next release tries again) and is a warning, or a stop underenforce.SQUIRE_PROCTOR_FETCH=0turns it off, andSQUIRE_CACHE_DIR=offleaves it nowhere to go. With no dev PROCTOR in the lock there is nothing to fetch, and the step says PROCTOR was not found. -
The policy is
SQUIRE_PROCTOR_POLICYwhen set; otherwise the policy the CREED package ships (vendor/waynestate/creed/policy/policy.json, when installed); otherwise PROCTOR runs on its own default policy with a notice. An explicit value always wins.
The Oracle check#
The release also runs an Oracle connection check (oracle-check.php) after the migrations and before the smoke test. It is a report, never a gate: a finding prints in the deployment log and the release goes on. When the app does not use Oracle (no ORACLE_* settings) it prints nothing. It checks, in order, that the settings are present, that the host resolves, that the port answers within 3 seconds, that the oci8 driver is loaded, and that the login works, stopping at the first failure so a bad port never costs a login attempt. Settings: ORACLE_USERNAME, ORACLE_PASSWORD, and either ORACLE_TNS (Easy Connect host:port/service, or a full (DESCRIPTION=...) descriptor) or ORACLE_HOST, ORACLE_PORT and ORACLE_SERVICE_NAME. Only setting names are ever printed, never values.
Configuration#
Before the first step the script reads two sources: ./.env.squire (the release options) and the secrets folder, SQUIRE_SECRETS_DIR (default /run/secrets), where each file named like a variable becomes that variable unless the environment already sets it. Only names are printed. See Image hardening.
Configuration is environment variables, all optional, or the same names in ./.env.squire in the app root. On Citadel add that file as a configuration file (the configuration-files step after the wizard; the wizard has no environment field) and keep it out of git. A variable already in the environment wins over the file. See .env.squire.example.
Next#
Read Citadel setup for the dashboard steps that make this script run, or Local parity to watch the same pipeline on your machine.