Conjure a project

$ grim create-project shop

This is the first command most people run in earnest. Give it a name and you get a directory with a grim.json pinned to the current train, the modules and the theme you picked, and, once the install has run, core, the Docker setup and a database to go with them. It asks what goes in rather than handing you a fixed skeleton.

It runs the other way too. Pointed at an application that is already running, it reads what that application enables and writes the grim.json for it. See importing a running instance.

Usage

$ grim create-project shop                                   # asks for modules and a theme
$ grim create-project shop --modules=cart,payments           # modules named up front
$ grim create-project shop --preset=minimal --no-install     # grim.json only, install later
$ grim create-project --from-instance=~/Sites/shop

Run it from the directory that should hold the project. The name is lowercase kebab-case. It becomes the directory, the name in grim.json and the local domain, so shop answers at https://shop.test. An existing directory of that name stops it: Directory shop already exists.

Arguments and options

Create a new GRIM project interactively

Usage

grim create-project [--from-instance FROM-INSTANCE] [--host HOST] [--preset PRESET] [--modules MODULES] [--refresh-registry] [--new-theme NEW-THEME] [--theme-public] [--theme-org THEME-ORG] [--no-install] [--no-enable] [--] [<name>]

Arguments

Options

What it actually does

1. Checks Docker and the registry login before asking anything. The daemon has to run; in a terminal grim offers to start Docker Desktop and wait up to 60 seconds. Docker also has to be able to read the base image on ghcr.io; when it is not logged in, grim offers to run grim auth:login on the spot. --no-install skips this step.
2. Asks what goes in. First a module preset: minimal for no modules, which is the default, all for every module in the registry that has a release, or custom to pick from a list. Then the frontend theme: blank, an existing theme by name, or a new one. --preset and --modules answer the first question, --new-theme the second.
3. Writes grim.json and .gitignore. The name, core constrained to the current train, the modules under requires and both theme slots on the same constraint, Horizon and the scheduler switched on and Reverb off, and a deploy block with a health check. The .gitignore tracks itself, grim.json and grim.lock, and nothing else. It prints ✓ Created shop/grim.json.
4. Scaffolds the new theme, when you asked for one. This is grim make:theme run inside the project: a copy of blank, published as a repository of its own. --theme-public and --theme-org are handed to it.
5. Runs grim install in the new directory. Core, the modules and themes, the Docker files, grim.lock, the local database, migrations and an admin user all come from there. --no-install stops before this step and prints what to run next. --no-enable is handed on to the install.
6. Registers the domain. On Linux and WSL2 it adds shop.test and mail.shop.test to /etc/hosts through sudo. On WSL2 it then adds the same to the Windows hosts file, behind a UAC prompt. On macOS the resolver that grim setup wrote only points .test at your machine. Where Herd, Valet or dnsmasq answers there, nothing more happens. On a Mac where the name does not resolve, the same line goes into /etc/hosts through sudo.

Anything left out in step 2 can be added later with grim require.

Importing a running instance

Moving an application that already runs onto grim: point the command at the instance directory, read the dry run, point .env at a new database, then install. A conversion never installs on its own, with or without --no-install.

$ grim create-project --from-instance=~/Sites/shop
$ cd shop
$ grim install --dry-run
$ grim install

It reads three files of the instance and writes to none of them. The new project lands in a new directory under the one you are in.

The name is the deploy host, not the directory. ~/Sites/shop3 deployed as host('shop') becomes the project shop. When deploy.php lists several hosts and none carries the directory's name, the run stops, lists the hosts it found and asks for --host=<name>. A name argument changes only the directory that is created.

Two kinds of finding are reported. A module the instance enables that now ships with core is a warning, Cart is core, omitted from requires, and is left out. A module with no package is an error, and all of them are listed before anything is written: Module Foo (foo) has no package — it is not in the registry, or archived, or private without access. Without a stored token the modules are not checked at all, and a warning says so.

In the dry run, read the section headed Resolved but not in grim.json. It lists what the install would pull in that the instance never asked for. The conversion is meant to run once; from then on grim.json is the source of truth.

Pitfalls

The converted .env still names the old database

--from-instance copies .env unchanged, so DB_* points at the instance's database. grim install runs php artisan migrate --force and creates an admin in whatever DB_* names. That is why the conversion stops before the install and prints a warning. Load a dump into a new database and set DB_DATABASE before you run grim install. Import an existing app walks through it.

--modules does not make it silent

The theme question is still asked. In a script without a terminal, add --no-interaction and every question takes its default, which for the theme is blank.

A new theme that could not be published stays local

⚠ Theme "boulder" scaffolded locally only — install will resolve it from disk. Publish to GitHub later to share with the team. means the theme directory exists and the GitHub part failed. The project installs and runs. A colleague who clones it cannot install until the theme is published.

On Windows, where you start decides how fast the app is

Started from a directory on the Windows drive, the command first offers to create the project inside the WSL2 filesystem instead. Take the offer. A project on the Windows side is reached by Docker through a slow bridge, and every request pays for it.

The local database needs a passwordless root

The install creates the project's database with the mysql client, as root with no password. When that login does not work, the step is passed over without a word and no database is made. grim doctor, run outside a project, tells you whether the login works before you start.

After it finishes

The install ends with a summary: project, core version, module and theme counts, and the admin login it created, with a generated password. Note the password down. Then bring the environment up.

$ cd shop && grim up

Traefik takes ports 80 and 443. If something else on the machine already has them, this is where you find out.

Questions

Can I change the modules afterwards?

Yes. grim require adds a module and grim remove takes one out. Nothing chosen here is final.

Why does the .gitignore ignore almost everything?

The project repository is a prescription, not a checkout. git clone followed by grim install rebuilds the rest from grim.json and grim.lock. Add a line for each file the project itself owns.

Related spells

Recipes that use it