Onboard as a collaborator

Before you start

Ask whoever runs the project for two things. The first is membership in the GitHub organisation, or the team in it, that owns the grimoiry/grim-* packages the project uses. The second is read access to the project's own repository. Accept both invitations before you go on. A pending invitation looks exactly like a missing package.

grim is installed and Docker is running. The login in step one hands your token to Docker, and it cannot do that while the daemon is down.

$ grim --version
$ docker info --format '{{.ServerVersion}}'

If you use the GitHub CLI, log it in first with gh auth login. grim borrows that login and you never handle a token. Without gh, create a classic personal access token with repo, read:user and read:packages. A fine-grained token is accepted by GitHub and still cannot pull images.

The ritual, in order

Six steps. The first two are done once per machine, the third and fourth once per project, and the last two are how every working day begins.

1. I

   Log grim in

   Modules, themes and the base images are private. grim auth:login takes the token gh holds, adds the scopes grim needs, and hands the same token to Composer and to Docker.

   $ grim auth:login
   …
   OK Authenticated as anna.

   Read the steps above the last line, not only the last line. A step marked ! means Composer or Docker did not get the token, and the command still ends in success. Without gh, run grim auth:login --no-gh and paste the token at the hidden prompt. Add --packages-write only if you will release images yourself. A collaborator who changes modules does not need it.

2. II

   Check who grim acts as

   grim auth:whoami reads what was stored, and grim doctor checks the rest of the machine: tools, the Docker daemon, the database, free disk space.

   $ grim auth:whoami
   Authenticated as anna (token: ghp_****abcd)
   $ grim doctor

   The name has to be yours. On a machine someone else set up it may not be, and then every clone happens with their access. Fix every ✗ line of the doctor now. A - line is something absent that is not wrong.

3. III

   Clone the project and read the plan

   The repository carries grim.json, grim.lock and a .gitignore. That is the whole project as far as git is concerned. The dry run of grim install needs no Docker and writes nothing, and it is the cheapest proof that your account sees every package.

   $ git clone git@github.com:acme/shop.git
   $ cd shop
   $ grim install --dry-run

   A table of modules with their versions means access is in order. A list of packages that cannot be installed means it is not. See the first entry under When it does not work.

4. IV

   Install what the lock records

   The same command without the flag lands core, every module and every theme at the versions in grim.lock, not at the newest ones. You get what your colleagues run. It then writes .env and the Docker files, builds the image, starts the stack, migrates and creates an admin account.

   $ grim install

   The first run builds an image and installs Composer packages, so it takes several minutes. It ends with a table titled Project installed.

   The Admin and Password rows of that table are shown once, and the password is stored nowhere in plain text. Copy both before the terminal scrolls away.

5. V

   Bring the stack up

   Install leaves the containers running. grim up adds what is still missing on a working day: the local certificate, the Vite dev server on your machine, and a check that HTTPS answers.

   $ grim up

   The table titled Development ready holds the address, https://shop.test, and the Mailpit address. A table without a Vite HMR row means yarn is not installed on your machine. Nothing else reports it.

6. VI

   Run the suite once

   Run grim test before you change anything. A failure you see now is not yours, and you will want to know that tomorrow.

   $ grim test

   The first run creates the database shop_test next to your development one and migrates it. Your development data is never touched.

What you have now

A directory that git considers nearly empty, and a full application inside it.

shop/
  grim.json, grim.lock      tracked: what the project is made of
  src/<Module>/             one git checkout per module, each at a tag
  resources/themes/         one git checkout per theme
  .env, docker/, vendor/    generated, never committed

On the machine, ~/.grim/config.json holds your token, and Composer and Docker hold a copy each. Every module under src/ is a checkout you can edit. How an edit gets back to everybody else is the subject of Change a module and send it back.

Each morning is git pull, then grim install when the lock changed, then grim up.

When it does not work

“1 package cannot be installed:”

Under the headline comes one line per package. cart is private — request access at … and … does not exist, or your token cannot see it both mean your GitHub account lacks access to that repository. GitHub answers the same for a package that is missing and one that is hidden from you. Ask for the package to be added to your team, accept the invitation, and run the dry run again. Nothing was installed, so nothing needs cleaning up.

“Some auth-pipeline steps failed (see above).”

The token is valid and saved, and the Composer or the Docker step failed. The usual cause is a Docker daemon that was not running. Start Docker and run grim auth:login again. Left alone, it comes back later as a 403 from ghcr.io in the middle of an install.

whoami shows a token that is not the stored one

With GRIM_GITHUB_TOKEN exported in your shell, grim uses that token and shows it masked, next to the stored user name. The two may not belong together. Unset the variable unless you set it on purpose.

The first page answers with an SQL error

You ran grim install --no-composer, or install stopped before its last step. On your own machine grim up never migrates. Run the migrations yourself.

$ grim artisan migrate

“service "app" is not running”

grim test enters the running app container. Bring the stack up with grim up and run it again.