Skip to content
GRIMOIRY

Renew the infrastructure files

$ grim upgrade --dry-run

The Dockerfiles and nginx configs in a project are not part of core and do not travel with a train. They are rendered from templates that ship inside grim itself. So a fix to one of them reaches you in two moves: grim self-update brings the new templates, and grim upgrade writes them into the project. Until the second move, a new grim changes nothing in docker/.

Reach for it after every self-update, and when grim build warns that a file is outdated.

Usage

$ grim upgrade --dry-run     # list the files, write nothing
$ grim upgrade               # rewrite the managed files
$ grim upgrade --force       # also regenerate the files you own, with backups

Run it from the project directory. Anywhere else it finds no grim.json and says so.

Arguments and options

Update generated infrastructure files to latest grim-cli templates

Usage

grim upgrade [--force] [--dry-run]

Options

Option Description
--force Also regenerate user-owned files (docker-compose.yml, Dockerfile.dev)
--dry-run Show what would be updated without making changes

What it actually does

  1. Rewrites the managed files. Four are copied as they are, two are rendered from grim.json. There is no prompt and no comparison: each one is written whether or not it would change.
  2. Skips the owned files. They were generated once and are yours to edit, so without --force they are only listed as skipped.
  3. With --force, backs up and regenerates the owned files. Each existing file is copied to <file>.bak next to it first.
  4. Prints a summary. Project, the grim version, and one row per file: Updated, Skipped, or Would update in a dry run.

Managed and owned

Files grim upgrade grim upgrade --force
Managed docker/nginx-production.conf, docker/nginx-dev.conf, docker/Dockerfile.production, docker/entrypoint-dev.sh, docker/php-dev.ini, docker/xdebug.ini Overwritten Overwritten
Owned docker-compose.yml, docker/Dockerfile.dev, docker/.env.docker.example, .dockerignore Left alone Backed up to .bak, then regenerated

A managed file is overwritten without a backup. An edit you made to docker/nginx-dev.conf by hand is gone after the next upgrade. The project's .gitignore tracks only grim.json and grim.lock unless you added more, so git does not remember the edit either. A file you change by hand belongs on that allowlist, committed, before the next upgrade.

Pitfalls

The dry run does not compare anything

--dry-run lists every managed file as Would update, changed or not. It tells you which files are in play, not what will differ. There is no way to preview the change. git diff docker/ shows it afterwards only for files you put on the allowlist in .gitignore. A project as grim create-project made it does not track docker/ at all.

--force resets your compose file

If you added a service or changed a port in docker-compose.yml, that lives nowhere else. --force replaces the file with a fresh render from grim.json and leaves your version in docker-compose.yml.bak. Move your additions back by hand, then delete the backup.

The running stack keeps the old files

Containers read these files when they start. After an upgrade that touched the dev files, restart the stack with grim down and grim up.

After it finishes

Restart the local stack so the containers read the new dev files. There is nothing to commit unless your .gitignore tracks files under docker/. The new docker/Dockerfile.production takes effect with the next grim build. The copies that already sit on a server are a separate matter, handled by grim server:upgrade.

$ grim down
$ grim up

grim update

Board the newest train

Move core, every module and every theme onto the newest release train grim.json allows, or a single module within the train it is on.

grim self-update

Update grim itself

Replace the grim phar with the newest release. Projects are not touched.

grim build

Forge the production image

Build the project's production Docker image, tag it with the next version, and push it to GHCR when asked.

grim server:upgrade

Refresh a project's server files

Send the current docker-compose.yml and in-container nginx config to a project's server, without deploying a new image.

Curses it can raise

upstream sent too big header while reading response header from upstream

The response headers of the app are larger than the buffer nginx reads them into, because an nginx config in the chain predates the larger buffers.

The idea underneath

What grim owns in your project

Which files in a project are yours, which grim rewrites, which command rewrites them, and why the repository of a project holds almost nothing.