Lando → Docker Compose + Makefile (Drupal local dev)

This is the upstream prerequisite skill: it produces the Makefile (and the Dockerized environment behind it) that d11, gulp-to-vite, sass-migrator and php-docker-upgrade all depend on. The target architecture is the one used across the reference projects (Project B, Project D, Project E):

Traefik (shared, external)  ──►  apache (httpd:2.4-alpine, proxy_fcgi)
  *.dev.localhost, TLS            └─►  php (php:8.4-fpm)
                                        ├─ db      (mariadb:11.8)
                                        ├─ redis   (redis:8-alpine)
                                        ├─ node    (node:24-alpine, idle)
                                        ├─ adminer (adminer:6.1.2)
                                        └─ mailpit (axllent/mailpit)

The tags above are a baseline, not a target: Step 1 resolves the current ones (references/image-versions.md).

Golden rule

The Makefile is the single developer entrypoint — after this migration, every drush/composer/npm runs through a make target inside a container, never via lando and never on the host. Building that Makefile faithfully is the core deliverable.

Prerequisites (host, once per machine)

A shared external Traefik and a local wildcard cert — see references/compose-traefik.md:

docker network create traefik-public
mkcert -install && mkcert "*.dev.localhost"     # feed cert to the Traefik instance

*.dev.localhost resolves to 127.0.0.1 automatically — no /etc/hosts edits. If the user has no shared Traefik, say so and point them at the reference before generating the stack (the stack assumes it exists).

Step 0 — Inventory the .lando.yml and decide the variants

Read .lando.yml (and .lando.local.yml if present; recover from git history if already deleted). Extract: recipe, PHP version, web server, DB type+version, node version, extra services (redis, search, cache), the tooling: commands, and the proxy: hostnames. Then settle the three decisions that shape the output:

Capture the target COMPOSE_PROJECT_NAME (the base hostname) and the theme folder now — they thread through every file.

Step 1 — Resolve the image versions, then create the docker/ tree

Before writing any file, resolve every image's tag with references/image-versions.md:

• dev-only tools (Adminer, Mailpit, httpd, Redis) take their newest release;
• PHP, Node and the database take the newest LTS / supported version that production and the CI image also run.

Write the resolved tags into the files below, and keep the report table for the MR.

Create the image/config files verbatim from references/docker-images.md: docker/php/{Dockerfile,entrypoint.sh,php.ini,www.conf,xdebug.ini}, docker/apache/{Dockerfile,vhost.conf}, and .dockerignore. The node service uses the node:<LTS>-alpine image directly; write docker/node/Dockerfile only if imagemin/optipng is a dependency (toolchain form) — a FROM + WORKDIR-only Dockerfile is dead weight.

Do not skip www.conf (clear_env = no) — it is load-bearing: without it the env-driven DB/Redis/SMTP config in settings.php is silently empty. Which of $_ENV / getenv() actually holds the values also depends on the project's .env loader — see "Which source holds the .env values" in drupal-glue.md before writing any env-driven condition.

Step 2 — Write docker/compose/dev/docker-compose.yml

From references/compose-traefik.md: all services, the Traefik label pattern (web + websecure routers, tls=true), the app-internal bridge and the traefik-public external network, named volumes. For multisite, apply the apache OR-rule and the per-site db network aliases.

Step 3 — Write the Makefile

From references/makefile.md: the header wiring, the dual argument-passing convention (named c=/m=/uid= and positional with the catch-all %: rule), and every target. Verify coverage: each lando <cmd> from the old tooling: block must map to a target (drush→make drush, composer→ make composer, npm/node/yarn→make npm, gulp→make npm-dev/npm-build). Add the SITES loop + cr-all for multisite.

Step 4 — Drupal glue

From references/drupal-glue.md: point the DB host at the compose service (db) or network alias, read creds from $_ENV, set config_sync_directory, trusted_host_patterns, the reverse_proxy block (Traefik terminates TLS), and the empty-password Redis guard. Update drush aliases (/app → /var/www/html, *.lndo.site → https://*.dev.localhost). For multisite, add web/sites/sites.php, the per-site init SQL, and the per-site $_ENV prefix logic.

web/sites/*/settings.php is often git-ignored (a local file) — edit wherever the project actually reads DB config (a tracked base.settings.php, a settings.local.php, or the developer's local settings.php).

Step 5 — .env.example + bring it up

Write .env.example (see references/drupal-glue.md), then:

cp .env.example .env      # or: make init (generates HASH_SALT, builds, boots)
# set USER_ID / GROUP_ID from `id -u` / `id -g`
make init                 # first run: .env, HASH_SALT, build, up
make db-import _dumps/<dump>.sql.gz
make cim
make cr

Step 6 — Verify

make up                                    # prints the URLs
make drush c='status'                      # DB connected, bootstrap OK, shows PHP version
curl -ksI https://<project>.dev.localhost | head -1   # 200/301 via Traefik
make npm-build                             # frontend builds in the node container

# Failure paths — each one was a review finding once, test them, don't assume
make updv; echo $?                         # mistyped target → non-zero, not a silent 0
make db-import _dumps/nope.sql.gz          # → "file not found", DB still intact
grep HASH_SALT .env; make init; grep HASH_SALT .env   # identical: init is re-runnable
XDEBUG_MODE=debug docker compose … run --rm --no-deps --entrypoint "" php php -m | grep -i xdebug

Manual checks:

• https://<project>.dev.localhost loads (TLS via Traefik, no cert warning)
• Adminer at https://<project>-adminer.dev.localhost, Mailpit at -mailpit
• After importing a preprod dump, a real send (webform, password reset) lands in Mailpit — the transport override is in place (drupal-glue.md)
• No service publishes a host port that Traefik already routes
• make uli uid=1 logs in
• Edits to files on the host are picked up (bind mount + UID/GID remap OK)
• make npm-dev HMR works (Vite/Gulp) if applicable
• (multisite) each site resolves and reaches its own DB
• Every image is on the version the image-versions rule picks, and the report table lists each newer version held back, with the reason

Hand-off to the other skills

Once make drush c='status' is green, the Makefile contract the other skills rely on exists. Natural next steps: php-docker-upgrade (bump PHP), d11 (Drupal 10 → 11), gulp-to-vite, sass-migrator.

Git workflow

One focused branch + a single MR is enough (this is one coherent change). If the gm:merge-request skill is available, delegate the branch/commit/MR to it; otherwise do a plain branch → commit → push (open the MR with glab if authenticated), or commit on the current branch — ask the user which. Keep the old .lando.yml deletion in the same commit as the new docker/ + Makefile.

Common issues

Reference files

• references/image-versions.md — resolving each image's tag + the report table
• references/docker-images.md — verbatim docker/ Dockerfiles + config
• references/compose-traefik.md — docker-compose.yml, Traefik labels, mkcert
• references/makefile.md — full Makefile template + argument passing
• references/drupal-glue.md — settings/sites/drush/.env, single vs multisite
• references/frontend-build.md — node image toolchain + Gulp/Vite/Tailwind HMR