Skip to content
Parity 0.1.0
Menu

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, and health_check is one line, because they land in a Dockerfile and a shell.
  • Required keys in config_files are named the way the file names them: section.key for ini files, NAME for env files, a.b for JSON. parity check says 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 -modified when the folder has changes). writable names 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 *, */N or a list (0,30); day of month, month and day of week as * or a list (Sunday is 0 or 7). No ranges, no MON, 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, and parity logs app shows 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 as prisoner beside Apache once Citadel's entrypoint has run the deployments, and starts each due entry with /bin/sh at the top of the minute, as cron does. Copying Citadel exactly, with a sidecar that runs docker 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 the schedule entry above when routes/console.php, bootstrap/app.php or app/Console/Kernel.php schedules anything, or the Squire kit has a scheduler service. --no-cron leaves 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.