parity.json#
The one file Parity adds to your app. Its fields mirror Citadel's app settings page, so filling it in is copying the
dashboard. parity init writes it from what is in the folder; every field has a default except name.
It holds settings, never secrets. Commit it.
An example#
What parity init --print writes for testdata/hello, the smallest app in Parity's repository:
{
"version": 1,
"name": "hello",
"image": "citadel/php-apache:8.5r3",
"public_dir": "public",
"mode": "mount",
"build_script": "build.sh",
"deployments": "deployments/",
"health_check": "php health.php",
"environment": "local",
"server_name": "hello.apps.wayne.test",
"time_zone": "America/Detroit",
"http_port": 8080,
"database": {
"mysql": false
},
"sign_in": "none"
}
Fields#
| Field | Citadel's setting | Default |
|---|---|---|
version |
(Parity's) the file format | 1 |
name |
the app (names the containers: compose project parity-<name>) |
the folder's name |
image |
base image | citadel/php-apache:8.5r3 |
public_dir |
public directory, relative to the app | public when there is one, else . |
mode |
(Parity's) mount or bake |
mount |
build_script |
build script | build.sh when there is one |
deployments |
deployments folder | deployments/ when there is one |
health_check |
health check command, run from the app folder | php health.php or ./health-check when there is one |
cron |
cron entries: name (short name), schedule (five fields), command (see Cron entries) |
Laravel's scheduler when the app schedules anything, else none |
writable |
writable paths: Apache's group, group-writable, as Citadel's deploy leaves them (baked into the image in bake mode; set as the container starts in mount mode) | Laravel's storage and bootstrap/cache |
config_files |
configuration files: path and required_keys |
none |
environment |
environment | local |
server_name |
host name | <name>.apps.wayne.test |
time_zone |
time zone | America/Detroit |
http_port |
(Parity's) the proxy's port on 127.0.0.1 | 8080 |
https |
(Parity's) serve https for server_name (and localhost) on 127.0.0.1:8443, a fixed port, with a leaf from the app's local CA; http_port and database.port must not be 8443 while it is on |
false |
database |
MySQL: mysql (yes or no), name, local port |
no MySQL; when yes, database app on port 3307 |
sign_in |
(Parity's) none, fake (SESAME's fake driver) or cas (see Sign-in) |
none |
fake_user |
(Parity's) who the fake driver signs in | jdoe |
test.requests |
(Parity's) extra requests for parity test: path, status, contains |
none |
test.tools |
(Parity's) commands parity test runs in the app container as user citadel, in order, before its HTTP checks; the first failure stops the run |
none |
Rules#
- Unknown fields are an error, so a typo is caught rather than ignored.
- Paths may not hold
$, backquotes, double quotes or line breaks, andhealth_checkis one line, because they land in a Dockerfile and a shell. - Required keys in
config_filesare named the way the file names them:section.keyfor ini files,NAMEfor env files,a.bfor JSON.parity checksays whether each is filled in and never prints a value. A configuration file is never baked into an image.
Mount or bake#
- mount (for developers): your folder is mounted at
/citadel/src, as Citadel mounts it. Edit, reload. - bake (for testers): your code is copied into the image, so a tester tests one exact commit, and Parity says
which (with
-modifiedwhen the folder has changes).writablenames the folders Apache may write to.
Sign-in#
sign_in puts SESAME's own settings in the app container's environment (.parity/app.env). A real environment
variable beats .env in Laravel and in SESAME's raw PHP settings, so your .env keeps whatever it says and Parity
never writes to it.
sign_in |
The app gets | Needs |
|---|---|---|
none |
nothing; the app's own settings decide | nothing |
fake |
SESAME_DRIVER=fake, SESAME_FAKE_USERNAME (fake_user, default jdoe) |
a local environment (below) |
cas |
SESAME_DRIVER=cas, SESAME_CAS_SERVICE_URL=https://<server_name>/login (SESAME's Laravel /login route) |
server_name on wayne.edu, pointed at 127.0.0.1 in your hosts file, and "https": true, so Parity serves https for server_name on 127.0.0.1:8443 |
fake needs environment set to local, development, dev, testing or test, because SESAME's fake driver
refuses to boot anywhere else. CAS sends its ticket back only to an https address on a name it knows. SESAME_CAS_BASE_URL is left to the app's
settings or the playbook, which carry the university's CAS server. For cas, set "https": true: Parity serves https
for server_name on 127.0.0.1:8443, and one run of parity trust makes your browser trust the app's local CA. The
hosts-file step stays, because CAS must see a name it knows. fake is the everyday local choice.
{
"sign_in": "fake",
"fake_user": "jdoe"
}
Cron entries#
Citadel offers apps no queue worker and no long-running services. It offers cron entries, each a short name, a
schedule and a command. Citadel's host runs each one as docker exec -u prisoner <your app container> <command> and
keeps its output in logs/cron-jobs/<name>.stdout.log and <name>.stderr.log. Parity does the same, inside the app
container, as prisoner, with the container's environment, from /citadel/src:
"cron": [
{
"name": "schedule",
"schedule": "* * * * *",
"command": "php artisan schedule:run"
}
]
-
The schedule takes what Citadel's dashboard takes: minute and hour as
*,*/Nor a list (0,30); day of month, month and day of week as*or a list (Sunday is0or7). No ranges, noMON, no@hourly. If your crontab has a range, it now has a list. -
The command is one simple command. Citadel writes it into the host's crontab after
docker exec, so the host's shell reads the line: a;,&&,|,>or$there would act on the host, outside your app. Parity refuses those. Put the steps in a script in the app and name it (sh bin/nightly.sh). -
Output:
parity logs cron:<name>shows the two files, as Citadel's dashboard does, andparity logs appshows each run as it happens (parity logs). -
How Parity runs them: a small loop (
.parity/cron/cron.php, in PHP because every Citadel image has PHP) starts asprisonerbeside Apache once Citadel's entrypoint has run the deployments, and starts each due entry with/bin/shat the top of the minute, as cron does. Copying Citadel exactly, with a sidecar that runsdocker exec, would need the container engine's socket inside a container (root on your computer). The loop gives the command the same container, user, environment and folder without it. -
Queues: there is no worker service, on Citadel or here. A Laravel app drains its queue from the scheduler:
Schedule::command('queue:work --stop-when-empty --tries=5 --timeout=600') ->everyMinute() ->withoutOverlapping(15) ->runInBackground();parity init(and--from-squire) proposes thescheduleentry above whenroutes/console.php,bootstrap/app.phporapp/Console/Kernel.phpschedules anything, or the Squire kit has a scheduler service.--no-cronleaves it out.
Test requests#
{
"test": {
"requests": [
{ "path": "/rooms.php?building=STATE", "status": 200, "contains": "State Hall" },
{ "path": "/admin/", "status": 302 }
]
}
}
A request passes on any answer below 500 unless it names a status, and must contain contains when it names one.
Redirects are not followed, so a redirect is checked as the redirect.
Test tools#
{
"test": {
"tools": [["composer", "ci"], ["php", "artisan", "test"]]
}
}
Each entry is one command as an argument list. parity test runs the tools in the app container as user citadel,
in the order listed, before its HTTP checks, with their output going straight to your terminal. The first failing
tool stops the run: the later tools and the HTTP checks do not run, and parity test exits 1.