Skip to content
GRIMOIRY

Liber Tertius · Chapter 1 · Getting grim

Install on Windows with WSL2

You work inside the distro and look at the result in a Windows browser. Two installers are needed because those are two machines with two trust stores. The Windows one goes first so that the second can borrow its certificate authority and its token.

≈20 min 6 steps Windows 10 or 11 with a WSL2 distro Docker Desktop with WSL integration on A GitHub account with access to grimoiry
Source

Before you start

Know which side does what. Windows holds the browser, the certificate authority the browser trusts, and its own hosts file. The distro holds grim, your projects and every command you type after today. Docker Desktop serves both.

On the Windows side, Git for Windows has to be installed. The Windows installer stops without it. PHP, Composer, mkcert, MariaDB and Node it installs itself.

Inside the distro, Docker has to answer, which means WSL integration is switched on for this distro in Docker Desktop. PHP 8.1 or newer and Composer have to be installed in the distro too. The Linux installer checks both first and stops when either is missing.

$ docker info --format '{{.ServerVersion}}'
$ php --version
$ composer --version

The ritual, in order

Six steps. The first runs in PowerShell, the other five inside the distro. The order of the first two matters, and nothing else here is ever repeated.

  1. Install on the Windows side

    In PowerShell, not in the distro. This creates the mkcert authority in the Windows trust store, which is the one Chrome, Edge and Firefox on Windows believe. It also asks for a classic GitHub token and stores it under your Windows profile, in .grim\config.json.

    $ irm https://grim.grimoiry.com/install.ps1 | iex

    The pasted token is shown on screen. GRIM CLI installed successfully ends the run. You will not use this Windows copy of grim for daily work. It is here for what it leaves behind.

  2. Install inside the distro

    Open the distro. The same installer as on macOS and Linux notices WSL2 and looks at the Windows side before it asks for anything.

    $ curl -sS https://grim.grimoiry.com/install.sh | bash
…
Sharing mkcert CA with Windows host: /mnt/c/Users/anna/AppData/Local/mkcert
…
Found GitHub token from a Windows-side grim install at:
  /mnt/c/Users/anna/.grim/config.json

Reuse it? [Y/n]

    Sharing mkcert CA with Windows host is the line this recipe exists for. Certificates made inside the distro are now signed by the authority Windows trusts. No Windows mkcert CA found means step one did not finish. Go back to it, then run this installer again.

    Answer the token question with Enter. The installer ends by running grim auth:login, which also removes the credsStore entry that breaks image pulls from inside WSL2. Yellow lines are things the installer left to you. On Linux that includes the database: it prints the packages for your distribution and one GRANT statement. Run both now.

  3. Open a fresh shell

    The installer wrote CAROOT and, when it had to, a PATH hint into your shell profile. Neither reaches the shell you ran it from.

    $ echo $CAROOT
/mnt/c/Users/anna/AppData/Local/mkcert
$ grim auth:whoami

    An empty CAROOT in a new shell means your shell reads none of ~/.profile, ~/.bashrc and ~/.zshrc. Copy the three marked lines from one of them into the profile it does read.

  4. Stop WSL2 from rewriting the hosts file

    grim adds each project's names to the distro's /etc/hosts. WSL2 generates that file again at every restart and the entries are gone. Switch the generation off once per distro, then restart WSL.

    $ printf '[network]\ngenerateHosts = false\n' | sudo tee -a /etc/wsl.conf
$ wsl.exe --shutdown

    The shutdown closes every distro and this terminal with them. When /etc/wsl.conf already has a [network] section, put the line there by hand instead. Open the distro again before the next step, and wait until Docker Desktop reports the engine running.

  5. Prepare the distro

    grim setup creates the Docker network all projects share, installs the authority into the distro's own trust store and starts the one Traefik that routes every project.

    $ grim setup
Setting up local dev environment...

  Creating traefik-public network... OK
  Checking mkcert... installed
  Installing mkcert CA... OK
  SSL certs will be generated per-project on grim up
  Setting up Traefik... running
  Setting up *.test DNS... manual setup needed
  Add to /etc/hosts: 127.0.0.1 yourproject.test
  Or install dnsmasq: address=/.test/127.0.0.1

Local dev environment ready.

    Read the indented lines, not the last one. Local dev environment ready. is printed, with exit code 0, even when a line above it says failed. manual setup needed is not a task for you. Creating a project adds its names to both hosts files by itself.

  6. Ask the doctor

    On WSL2 grim doctor has a section of its own for the road from the distro to a Windows browser.

    $ grim doctor
…
  Docker daemon    ✓ running
  Traefik ports    ✓ 80, 443 bound
  MySQL/MariaDB    ✓ 10.11.6 (root@127.0.0.1, no password)
…
WSL2 browser path
  mkcert CAROOT     ✓ /mnt/c/Users/anna/AppData/Local/mkcert
  Windows CA        ✓ /mnt/c/Users/anna/AppData/Local/mkcert/rootCA.pem
  certutil          ✓ /usr/bin/certutil
  Browser           ✓ Snap Firefox not on PATH (use Windows browser for *.test)

All checks passed!

    A - on the MySQL/MariaDB line does not fail the run, and it still matters. grim creates a project's database from inside the distro, as root without a password. With a - there, the first project gets no database.

What you have now

Where What
Windows The mkcert authority in the trust store, a token in .grim\config.json, and a copy of grim you can ignore
Distro ~/.local/bin/grim, ~/.grim/config.json, ~/.grim/traefik/, CAROOT in your shell profile
Docker Desktop The traefik-public network and one Traefik on ports 80, 443 and 8099

Keep projects in the distro's own filesystem, under ~/, never under /mnt/c. Docker reaches Windows files through a slow bridge and every request pays for it.

No project yet. That is the next recipe, Create a project. Its one Windows-specific moment is a UAC prompt on the desktop, when the project's names go into the Windows hosts file. If you miss it, grim hosts:windows asks again.

When it does not work

“PHP is not installed. Install PHP 8.1+ first.”

The Linux installer brings Node and mkcert but not PHP or Composer. Install both with the distro's package manager and run the installer again. Composer is not installed. is the same stop one check later.

“No Windows mkcert CA found at /mnt/c/Users/*/AppData/Local/mkcert/.”

The distro made an authority of its own, and Windows browsers will reject every certificate signed by it. Finish step one on Windows, or run mkcert -install in PowerShell, then run the Linux installer again. Doctor shows the same state as Windows CA ✗.

“Git is not installed or not in PATH.”

The Windows installer stops here. Install Git for Windows, open a new PowerShell and run step one again.

“error getting credentials” when an image is pulled

The distro's ~/.docker/config.json names "credsStore": "desktop" again, and that helper fails inside WSL2. Run grim auth:login again. It removes the entry and logs in without it.

Firefox in the distro still warns about the certificate

Snap Firefox detected on PATH in doctor explains it. A Snap browser keeps a sandboxed trust store the authority cannot be installed into. Use the Windows browser for .test pages.

Next recipe

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 commit the three files that are the project.

Read it