Prepare the machine

$ grim setup

Every project on your machine answers at https://<project>.test, and none of them brings the plumbing for that itself. One Traefik routes all of them, one local certificate authority signs all their certificates, and one rule sends .test names to your own machine. Those belong to the machine, and grim setup puts them there.

Reach for it on a machine that was set up by hand, after the Traefik container has been thrown away, or when a browser has stopped trusting .test pages. It is safe to run again: each step checks what is already there.

Usage

$ grim setup        # network, certificate authority, Traefik, DNS
$ grim setup -v     # also show Homebrew's output while mkcert installs

It runs from anywhere and asks nothing. Docker has to be running. On macOS expect one sudo prompt the first time.

Arguments and options

Set up local dev environment (Traefik, mkcert, DNS)

Usage

grim setup

What it actually does

Each step prints its name and its result on one line.

1. Creates the traefik-public Docker network, unless it exists. Every project's stack joins it so Traefik can reach the containers.
2. Checks for mkcert. On macOS a missing mkcert is installed with Homebrew. On Linux setup prints sudo apt install mkcert and stops; this is the only step that ends the run.
3. Installs the mkcert authority into the system trust store with mkcert -install, and creates ~/.grim/traefik/certs. No certificate is made yet. Each project gets its own on its first grim up.
4. Sets up and starts Traefik. ~/.grim/traefik/ gets dynamic/, certs/ and a docker-compose.yml copied from grim's template, then the container is started on ports 80 and 443, with its dashboard on 8099. A compose file that is already there is left as it is.
5. Points .test at your machine. On macOS it writes /etc/resolver/test with nameserver 127.0.0.1, through sudo, unless the file exists. The file names a DNS server and grim runs none: Herd, Valet or dnsmasq answer there, and on a Mac without them grim up adds a hosts line per project. On Linux and Windows there is no such wildcard, so it prints the hosts-file line to add instead.

It ends with Local dev environment ready., the dashboard address http://localhost:8099 and the next command.

Pitfalls

A failed step does not fail the command

When the network or Traefik cannot be set up, that line says failed with Docker's reason under it, and the run still continues to Local dev environment ready. with exit code 0. Read the lines, not the last one. grim doctor afterwards tells you whether Traefik's ports are really bound.

Laravel Herd is stopped without being asked

Herd holds ports 80 and 443. On macOS, when Herd is running, setup runs herd stop before starting Traefik and does not mention it. If herd stop fails, the Traefik step fails and tells you to stop Herd yourself.

Something else holds port 80 or 443

Port(s) 80, 443 are held by a non-Docker process. Free them before running grim (e.g. stop the conflicting service). appears under the Traefik step when a local nginx or Apache is listening. Stop that service and run setup again.

On Linux the hosts file is yours to keep

Setup only prints the line. In practice you rarely add it by hand: grim create-project and grim up add the project's entry to /etc/hosts through sudo, and on WSL2 grim hosts:windows does the same for the Windows side.

After it finishes

The machine is ready and no project is running yet. Go to a project and start it, or make one with grim create-project.

$ cd shop && grim up

Related spells

Recipes that use it