91 lines
4.3 KiB
Markdown
91 lines
4.3 KiB
Markdown
# 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`](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](https://herd.laravel.com/) 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):
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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):
|
||
|
||
```bash
|
||
./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.
|