Easy WordPress Bootstrap

Spin up a complete WordPress development site on macOS with Laravel Herd and DBngin (or any MySQL/MariaDB server) in one pass. For the Windows/PowerShell workflow, see windows/README-Windows.md.

What You Get

• Project directory under your Herd workspace with sanitized slug and host mapping.
• MySQL database + user created after verifying the supplied root credentials.
• Latest WordPress core, wp-config.php with fresh salts, permalinks set to /%postname%/, and Home/News pages.
• Plugin install/activation from plugins.json, resolved from the project folder first then the repository default.
• Starter theme cloned with shallow history, .git stripped, repo reinitialized, remote optionally set, and Composer/NPM build steps run when available.
• .htaccess seeded when Apache rewrites are missing, bootstrap-summary.txt written, and plugin install logs stored at wp-content/plugin-bootstrap.log.
• Automatic WP-CLI detection with a bundled wp-cli.phar fallback (WP_CLI_PHAR env/config override).

Prerequisites

• macOS with Laravel Herd configured (default workspace ~/Herd).
• MySQL or MariaDB available locally (DBngin recommended) and the mysql client in PATH.
• CLI tools: php, git, curl, openssl, composer, npm, mysql, and optionally jq for pretty plugin output.
• Either wp in PATH or a downloadable wp-cli.phar placed beside the script (or in windows/wp-cli.phar).

Quick Start (Interactive)

1. Copy the sample configuration (one time):

   cp wp-bootstraprc.example ~/.wp-bootstraprc
   

2. Review plugins.json (optional override per project; place your own copy in the project root if needed).

3. Make the script executable, then run it and answer prompts:

   chmod +x wp-bootstrap.sh
   ./wp-bootstrap.sh
   

When the bootstrap completes, open the URL printed in the summary and check bootstrap-summary.txt under the project root.

Non-Interactive Usage

Pass values via flags (help output lists every option):

./wp-bootstrap.sh \
  --project-name "Client Site" \
  --admin-user admin \
  --admin-email dev@example.com \
  --theme-starter-repo git@github.com:vendor/theme.git \
  --herd-workspace "$HOME/Herd" \
  --local-tld test \
  --mysql-host 127.0.0.1 \
  --mysql-port 3306 \
  --mysql-root-user root \
  --mysql-root-pass secret

Any value omitted from the CLI falls back to ~/.wp-bootstraprc or the script defaults. Supply --help to print the full usage guide.

Configuration with .wp-bootstraprc

The script sources ~/.wp-bootstraprc on start. Key entries include:

• HERD_WORKSPACE, LOCAL_TLD
• MYSQL_HOST, MYSQL_PORT, MYSQL_ROOT_USER, MYSQL_ROOT_PASS
• DEFAULT_ADMIN_USER, DEFAULT_ADMIN_EMAIL
• THEME_STARTER_REPO, DEFAULT_THEME_REMOTE_ORIGIN
• WP_CLI_PHAR to point at a custom wp-cli.phar

Environment variables exported before running the script take precedence over both CLI flags and rc defaults when they share the same name.

Plugin Manifest

plugins.json accepts WordPress.org slugs or zip URLs. The script first looks for ./plugins.json inside the target project (useful for site-specific manifests) and falls back to the repository version when absent. Premium/private zips can point to signed URLs or local files; make sure the executing user has access.

Logs & Files Created

• bootstrap-summary.txt – high-level run output, stored in the project root.
• wp-content/plugin-bootstrap.log – detailed plugin installation results.
• .htaccess – created only when missing, populated with standard WordPress rewrite rules.

Troubleshooting

• WP-CLI missing – install wp globally, or download wp-cli.phar into the script directory and set WP_CLI_PHAR=/path/to/wp-cli.phar.
• MySQL connection failures – confirm DBngin (or your server) is running, credentials match your .wp-bootstraprc, and the root user can create databases/users.
• Composer/NPM not installed – the script skips dependency installation but leaves a warning in the output; install the tooling and rerun if theme assets are required.
• Permissions – ensure the Herd workspace and MySQL socket/port are accessible to your user account.

---

DIY-first policy: keep plugins.json minimal; add heavier stacks only when a project truly needs them.