Citadel setup#
This page lists the numbered steps that connect a new app to the scripts Squire wrote: what to set in the dashboard, what to commit, and where the configuration lives. Finish the steps below, then read The release script to see what runs on every deploy, or try Local parity first.
The steps#
- In the dashboard set the build script to
build.sh, the health check to["php","health.php"], and the Quick Update post-script to./scripts/release.sh(usercitadel). - Commit
composer.lock, andpackage-lock.json,pnpm-lock.yamloryarn.lockif you have a frontend. - Mark the scripts executable in git. On Windows:
git update-index --chmod=+x build.sh scripts/*.sh deployments/*.sh. - Set
SQUIRE_*values in the app's./.envconfiguration file (below), not 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./.envalready; a raw PHP app loads it withvlucas/phpdotenv(Dotenv\Dotenv::createUnsafeImmutable($root)->safeLoad()), sogetenv()sees the values and a real environment variable wins.
Executable bits#
Citadel runs the scripts as files, so git must record them as executable. Step 3 above does that with git update-index --chmod=+x; the release script itself starts with set -euo pipefail and expects to run as the citadel user from the Quick Update post-script.
./.env#
./.env is the app's own configuration, written into the source tree by the dashboard's configuration-files step (after the wizard; the wizard has no environment field). A Laravel app reads it already; a raw PHP app loads it with vlucas/phpdotenv (Dotenv\Dotenv::createUnsafeImmutable($root)->safeLoad()), so getenv() sees the values and a real environment variable wins.
./.env.squire#
./.env.squire is Squire's file: the release options for scripts/release.sh, and locally the parity settings. All of its values are optional. On Citadel, add ./.env.squire as a configuration file (the configuration-files step after the wizard; the wizard has no environment field) and keep it out of git. release.sh reads the release options from it, and a variable already in the environment wins. Locally, the same file holds the parity settings. See .env.squire.example in the app; it holds placeholders only.
Two files, two owners.
./.envis yours and the app reads it;./.env.squireis Squire's and the release script and the parity kit read it. Neither belongs in git.
Next#
Read The release script for what scripts/release.sh does step by step, or Local parity to run the same setup on your machine.