Liber Tertius · The recipes
Recipes
Guides you enter from a goal. Each one combines several commands or systems, names its prerequisites and ends in a state you can verify. Examples of a single command live on that command's spell; fixes for a single symptom are curses.
Getting grim
Put the CLI on your machine and prove it works.
3 of 3 inked
Install on macOS
Run the installer, open a fresh terminal, prepare the machine with grim setup, check that .test names resolve, and finish on a clean grim doctor.
Install on Windows
Run one installer in PowerShell, let it seed the Windows certificate authority and hand the rest to the WSL2 distro, then keep the distro's hosts file from being rewritten and finish on a clean grim doctor.
Run grim projects beside Laravel Herd
Keep Herd's sites and grim's Docker stacks on one Mac at the same time, with Herd's nginx in front of Traefik and every project answering at its own .test name.
Starting a project
From nothing, or from an application that already runs.
2 of 2 inked
Create a project
Answer two questions, let the install run, bring the stack up, sign in as the generated admin, run the suite once and give the first commit a remote.
Bring an existing app onto grim
Convert the instance into a grim.json without installing, read the dry run, settle the modules nobody asked for, point the copied .env at this machine, install, move your own files in, then test and commit.
Keeping a project current
New trains, single fixes, and knowing what is installed and why.
4 of 4 inked
Move a project to a new train
Read the train plan, decide what core stopped shipping, update, renew the infrastructure files, and commit a lock you have tested.
Take one module fix mid-train
Read the one-row plan, move a single module to its newest release on the train the project is locked to, run its migrations, test, commit the module with the lock and land it on the other machines.
Add, trace and remove modules
Find a module in the catalogue, require it on the project's train, trace what came along with it, and later remove it, sweep the leftovers and write the lock again.
Analyse a project with PHPStan
Run PHPStan over a project the way the unit check runs it over one module, inside the app container, against grim-core's baseline, and tell a finding of your own from one the project inherits.
Shipping
From a built image to an application serving traffic, and back.
5 of 5 inked
First deploy to a fresh VPS
Take a bare Ubuntu or Debian server and a project that runs on your machine, and end with the project live on its own domain over HTTPS.
Staging to production, one image
Register a staging environment next to production, name both in grim.json, release to staging, look at it, then send the same tag to production without building again.
Roll back a deploy
Read the deploy history, put the server back on the previous tag, check the site, and deploy an older tag by name when one step back is not enough.
Change config on a live app
Set one value in a server's .env, confirm the app reads it, change many values through a pull and a push, rotate a secret the whole team shares, and apply an edit on a stack you run yourself.
Debug production
Look at the server, read what the app logged, search the log on the server, question the app through artisan, turn the log level up for a while, and go inside the container when nothing else answers.
Working on modules
Changing the pieces projects are built from, and getting the change released.
5 of 5 inked
Onboard as a collaborator
Get access to the packages, log grim in, clone the project, install what its lock records, bring the stack up and run the suite once.
Change a module and send it back
Check what kind of module you are in, make, test and commit the change, read the dry run, open the pull request, and take the release when it arrives.
Read the unit check on your pull request
What the single `unit` check on a grim-* pull request does, how to read its annotations, and how to reproduce every one of its steps on your own machine before you push again.
Create a module
Scaffold a module, give it a table, check that it is enabled, write its first test, validate the manifest and commit it in the project — or, for a module other projects will install, publish a first version and add it to grim.json.
Create a theme
Scaffold a theme with its own repository, switch the project to it, work on it with the Vite dev server running, validate the manifest, publish a version that holds your work and add the theme to grim.json.
Shared dev boxes
A client’s machine, set up once, that developers attach to.
3 of 3 inked
Work on a client's dev box
Send your public key to the operator, paste the SSH block they send back, attach your editor to the project on the box, reload the stack after a change to .env, and open the database from there.
Set up a dev box for a client
Raise a shared development server, give it a registry token, put the first project on it, let developers in by key, hand over the access card, and later take a developer or a project off again.
LAN dev box with a custom certificate
Check a certificate from your own authority by hand, raise a dev box that serves it, put a project on it under names one wildcard covers, make developer machines trust the authority, and renew the certificate without downtime.