Skip to content
42wpPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

31 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

42wp — 42WP dev environments

O Guia do Mochileiro do WordPress — a tiny CLI that spins up disposable WordPress dev environments with Docker, the 42WP way.

42wp runs a shared global layer (Traefik reverse proxy + MySQL + phpMyAdmin + Mailpit) and, on top of it, per-project WordPress containers reachable at http://<project>.localhost. Your current working directory is mounted as wp-content, so you develop your theme/plugin locally and WordPress runs in a container with Xdebug, Memcached and WP-CLI preinstalled.

Requirements

  • Docker with the Compose v2 plugin (docker compose)
  • Node.js >= 18.17

Install

npm install -g @42wp/dev-env

This installs the 42wp command globally.

Usage

42wp init [project]        # scaffold a .42wp-dev-env with this project's options
42wp global start          # start Traefik + MySQL + phpMyAdmin + Mailpit
42wp start <project>       # build & start a project (run from your theme/plugin repo)
42wp update <project>      # update an existing project to a newer WordPress image
42wp wp <project> <args>   # run a WP-CLI command inside the project container
42wp stop <project>        # stop a project's containers
42wp rm <project>          # remove a site (container, image, database) — keeps your repo
42wp seed <project> [n]    # generate demo content in a running project (default 200)
42wp global stop           # tear the global layer down

Run 42wp with no arguments for the full command list.

Project config (.42wp-dev-env)

Drop a .42wp-dev-env file in your project repo to save its 42wp start options, so you (and your team) can just run 42wp start with no flags. Scaffold one with 42wp init:

42wp init mysite --subdomains --vip --locale pt_BR --theme my-theme --demo-content

That writes:

project_slug=mysite
multisite=subdomain      # false | subdir | subdomain
username=admin
password=password
locale=pt_BR
default_theme=my-theme
wpvip=true
initial_content=200

42wp start, run in that directory, reads the file and applies it — and CLI flags override any value for a one-off run. With project_slug set you can run 42wp start with no name. 42wp init won't overwrite an existing file unless you pass --force.

Key Effect
project_slug project name (so 42wp start needs no argument)
multisite false, subdir or subdomain
username / password admin credentials (plaintext — local dev only)
locale WordPress site language, e.g. pt_BR (pt-br is normalized)
default_theme theme to wp theme activate after install
wpvip clone + mount the VIP mu-plugins
initial_content true (200 posts) or a number

Project dependencies

Before installing WordPress, 42wp start installs the project's dependencies in your repo so WordPress and its mu-plugins load cleanly:

  • composer install — when composer.json is present
  • <pm> install — when package.json is present, where <pm> is inferred from the lockfile: pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm (defaults to npm)

These run on your machine, in the mounted repo, before the containers start. Composer is required: if a project has a composer.json and its PHP dependencies can't be installed (composer missing, or the install fails), start stops — a project with unmet PHP deps would break during the WordPress install anyway. The JS install is best-effort (a missing tool or failure just warns). Skip the whole step with --skip-deps:

42wp start my-site --skip-deps

WordPress version

By default projects are built on wordpress:php8.4-apache (newest WordPress, PHP 8.4, Apache). Pick a different image tag per project with --wp <tag>:

42wp start my-theme --wp latest             # newest WP, image's default PHP
42wp start legacy   --wp 6.9-php8.5-apache  # pin a specific WP + PHP
42wp update my-theme                        # rebuild on the default tag, run wp core update-db
42wp update my-theme --wp php8.5-apache     # update to a specific image

update rewrites the project's Dockerfile, re-pulls the base image, recreates the container and runs wp core update-db to migrate the schema. Set a different default for every project with the FORTYTWO_WP_TAG env var.

update moves the image (PHP, Apache), not WordPress core. Core lives in the container's /var/www/html volume, which the official image fills only when it is empty, and the volume survives the rebuild. To move core, use WP-CLI with an explicit version, discarding the language packs:

42wp wp my-site core update --version=<x.y.z> --locale=en_US \
  --exec="define('WP_LANG_DIR', '/tmp/discard-lang'); define('CORE_UPGRADE_SKIP_NEW_BUNDLED', true);"
42wp wp my-site core update-db               # --network on a multisite

On a non-English site core update downloads the localized package and copies its wp-content/languages into WP_LANG_DIR — your repository's languages/, since wp-content is your working directory. --locale=en_US is ignored without --version. Create /tmp/discard-lang in the container first, and compare git status before and after. The container must be running (docker compose up -d in the project dir, then docker compose stop to leave a stopped site as you found it).

Removing a site

42wp rm <project> tears a site down completely — its containers, the locally built image, and its database — and deletes the generated project dir (~/.42wp/projects/<name>/, including any cloned VIP mu-plugins). Your repository is never touched: wp-content is a bind mount of your working directory, which Docker leaves alone. It asks for confirmation; skip the prompt with --yes (or --force):

42wp rm my-theme          # prompts before removing
42wp rm my-theme --yes    # no prompt (for scripts/CI)

Demo content

Seed a project with a full demo dataset using --demo-content (defaults to 200 posts), or set a count with --demo-content=<n>:

42wp start my-site --demo-content       # ~200 posts
42wp start my-site --demo-content=50    # 50 posts

It runs a PHP seeder (wp eval-file) — no plugin required (FakerPress has no CLI) — that creates:

  • ~10 42wp_author terms (Portuguese names), ~10 tags, ~10 categories
  • a small pool of real images downloaded from picsum.photos, reused as featured + inline images
  • posts with rich HTML content (h1/h2/h3, lists, blockquote, images, links), a plain-text excerpt, varied past dates, and each linked to 1 category, 2–5 tags and 1–3 authors

Works on any project (not just --vip). It tops the site up to the requested number of posts rather than appending — if the site already has that many published posts it creates none, so re-running 42wp start never doubles the dataset. A failure never aborts start. The author terms use the 42wp_author taxonomy, which the project registers itself (e.g. the 42-framework mu-plugin) — the seeder does not register any taxonomy. If 42wp_author isn't available, the author links are simply skipped.

When the project ships the 42-framework (detected by client-mu-plugins/42-framework or a composer.json that requires 42wp/wp-mu-plugins), the seeder additionally configures — once, idempotently — a fuller site:

  • the /%category%/%postname%/ permalink structure
  • a 42wp_homepage post set as the static front page (falls back to a regular page if the type isn't registered)
  • 4 category-driven menus — Header Primário / Secundário and Footer Primário / Social (with a nested footer and YouTube/X/Instagram links) — assigned to the theme's registered menu locations

Re-running (or 42wp seed) reuses the existing homepage and menus instead of duplicating them; only posts keep appending. On a plain WordPress site these extra steps are skipped and only the content above is seeded.

To add demo content to an already-running project without recreating it, use seed. Like start, it tops the site up to the given count (so seed 500 on a 200-post site adds 300, and running it again adds nothing):

42wp seed my-site         # up to 200 posts
42wp seed my-site 500     # up to 500 posts
42wp seed my-site --demo-content=50

Admin credentials

The silent install creates an admin / password user by default. Override per project on start:

42wp start my-theme --user joao --pass s3cr3t

Site language

New sites install in English (en_US) by default. Pick a WordPress locale with --locale; the language pack is downloaded and activated automatically:

42wp start my-site --locale pt_BR      # Brazilian Portuguese
42wp start my-site --locale es_ES      # Spanish (Spain)

Set a default for every project with the FORTYTWO_WP_LOCALE env var. This is the site language — distinct from --lang, which controls the 42wp CLI's own messages (en/pt). The pack is downloaded into wp-content/languages; if the download fails (e.g. offline), the site stays in English and start continues.

Multisite

Start a site as a WordPress network with --multisite (subdirectory) or add --subdomains for a subdomain network:

42wp start my-network --multisite               # sites at my-network.localhost/site2
42wp start my-network --multisite --subdomains  # sites at site2.my-network.localhost

This installs WordPress, converts it to a network, writes the MULTISITE constants into wp-config.php, and mounts a .htaccess with the matching network rewrite rules (WP-CLI refuses to generate those for a multisite, which otherwise causes a redirect loop on sub-sites). For subdomain networks the Traefik router is widened to a wildcard (*.my-network.localhost) so sub-sites route to the container; *.localhost already resolves to 127.0.0.1, so no /etc/hosts edits are needed. Network admin lives at …/wp-admin/network/.

WordPress VIP (mu-plugins)

WPVIP sites expect the VIP Go mu-plugins under wp-content/mu-plugins. Pass --vip to start and the tool clones vip-go-mu-plugins-built (shallow) and mounts it into the container at wp-content/mu-plugins:

42wp start my-vip-site --vip

The clone lives in the project's data dir (~/.42wp/projects/<name>/mu-plugins), so it never touches your repo, and re-running start fast-forwards it. Regular (non-VIP) projects are unaffected.

--vip also mounts a small dev-helper mu-plugin (00-42wp-dev.php) that loads the WordPress admin media includes in admin/REST/CLI contexts. This fixes "Call to undefined function media_handle_sideload()"-style errors from plugins like FakerPress, which the VIP environment triggers by loading file.php early. It's mounted from the data dir, so your repo and the cloned VIP suite stay clean.

Example

cd ~/code/my-theme
42wp global start
42wp start my-theme
# → http://my-theme.localhost  (admin / password at /wp-admin)
42wp wp my-theme plugin list
42wp stop my-theme

Shared services once the global layer is up:

Service URL
Traefik http://localhost:8080
phpMyAdmin http://db.42wp.localhost
Mailpit http://mail.42wp.localhost

How it works

State lives under ~/.42wp (override with FORTYTWO_HOME):

~/.42wp/
  docker-compose.global.yml   # the global layer (created on first run)
  mysql-data/                 # persisted MySQL data
  projects/<project>/         # generated wp-config.php, Dockerfile, docker-compose.yml, meta.json

42wp start generates an ephemeral wp-config.php (fetching real salts from api.wordpress.org, with a local fallback when offline), a Dockerfile, and a docker-compose.yml, then builds the container and runs a silent wp core install. The DB name is the project name with hyphens turned into underscores; a trailing .suffix (e.g. .localhost) is stripped.

Where a project is bound. 42wp start mounts the directory you run it from as wp-content, so it first checks that directory looks like one — it must contain plugins/ and themes/, otherwise start refuses (rather than building a broken site). Pass --force to override (e.g. bootstrapping a brand-new, empty project). The chosen directory is recorded in the project's meta.json, and later starts reuse it — so re-running from a different folder can't silently re-point the container. Run 42wp start <name> --rebind from a new directory to move the binding there on purpose.

The generated wp-config.php always defines WP_ENVIRONMENT_TYPE as local, so wp_get_environment_type() reports local (not the WordPress default of production) — code and plugins that branch on the environment behave as they should in dev. The constant is set before mu-plugins load, so it holds even under --vip. The config is regenerated every start, so to apply this to an existing project, just re-run 42wp start <project>.

Troubleshooting

  • An edited PHP file doesn't change the page. Through a macOS file-sharing mount (seen with OrbStack) the container can keep the old mtime, so OPcache serves the old code. After an edit batch, touch the files inside the container (it is wp_ + the database name): docker exec wp_my_site find /var/www/html/wp-content/themes/my-theme -name '*.php' -exec touch {} +. After composer dump-autoload, also touch the project's vendor/composer/*.php, or the site fails with "Class … not found" while the host files are already right.
  • A parse error right after saving a file is the mount serving a half-written file: request again before changing the code, and don't run WP-CLI or curl while files are still being written.

Configuration

Env var Default Description
FORTYTWO_HOME ~/.42wp Where the global compose, DB data and projects live
FORTYTWO_WP_TAG php8.4-apache Default WordPress image tag for new projects (overridden by --wp)
FORTYTWO_WP_LOCALE unset (en_US) Default WordPress site language for new projects (overridden by --locale)
FORTYTWO_LANG auto (LANG) CLI UI language: en or pt
NO_COLOR unset Disable colored output

You can also pass --lang en / --lang pt before the command.

License

MIT

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages