StarterKit logo
Get Started

Installation

⏱️ Start Coding in 5 Minutes

1. Requirements

  1. Docker Engine v24+ (includes Compose v2)
  2. GNU Make – required to run project commands
  3. Git – for version control and cloning the repository

🖥️ Supported Platforms: macOS, Linux, and Windows (with WSL2). See Platform Notes for details.

2. Getting Started

⚡️ Looking to scaffold a new WordPress project, not just clone this StarterKit? See: Advanced Installation Options. You’ll generate your own repository with independent Git history and configuration — a clean foundation ready to customize and deploy.

🤖 Using Claude Code? You can skip most of the manual steps below — see AI-Assisted Development for the automated bootstrap sequence.

Clone the repository:

git clone https://github.com/solidbunch/starter-kit-foundation.git my-project

Customize environment variables by editing the .env files in the config/environment/ folder:

  • .env.main – shared base config, edit APP_NAME and APP_TITLE
  • .env.type.local, .env.type.dev, .env.type.stage, .env.type.prod – environment-specific overrides, edit APP_DOMAIN variable.
  • You can create as many .env.type.* files as needed (.env.type.qa, .env.type.stage2, etc.)

📁 Tip: We recommend using the /srv folder instead of /var/www for your web content. This follows the Filesystem Hierarchy Standard (FHS), which suggests /srv for site-specific data served by the system.

3. Install the Stack

make install [environment_type]

environment_type if omitted, defaults to local, it must match a file in config/environment/.env.type.*

What happens during installation

  1. If .env.secret is missing, it is generated from a template
  2. .env.main, .env.type.[environment_type], and .env.secret are merged into root folder .env file
  3. Composer dependencies are installed (PHP), for both the root project and the theme, using the toolkit compose file’s composer container — this step prompts Are you sure? (y/n): before it runs; answer y to continue
  4. npm dependencies are installed and frontend assets are built in a single call (npm run install-<APP_BUILD_MODE>), using the toolkit compose file’s node container
  5. Docker containers for the main project stack are pulled and started
  6. The database availability is checked
  7. WordPress is installed via WP-CLI: an admin user is created, all installed plugins are activated (wp plugin activate --all), and permalinks are set to /%postname%/

♻️ Note You can safely re-run make install at any time – it is idempotent.

Examples

✅ Install locally (most common scenario):

make install

This will use config/environment/.env.type.local.

Install using the production environment:

make install prod

This will use config/environment/.env.type.prod, applying values like APP_DOMAIN, APP_PROTOCOL, etc.

4. Post-Installation

✅ Once the installation is complete, your WordPress site is running inside Docker containers and ready to use.

The site domain is defined in the APP_DOMAIN variable inside your active .env.type.local file. To make it work locally, you must add it to your /etc/hosts file:

127.0.0.1 myproject.local

💡 Tip: Domains ending with .localhost do not require manual host mapping.

To open the site in your browser:

http://myproject.local

Or access the admin panel directly:

http://myproject.local/wp-admin

Login credentials are printed in the terminal during make install, and also stored in config/environment/.env.secret:

WP_ADMIN_USER=admin
WP_ADMIN_PASSWORD=...

Now you can start developing your theme and plugins, or customize the WordPress installation as needed.

🔐 Security Note: The .env.secret file contains sensitive credentials and should not be committed to version control. It is generated automatically during installation and should be kept secure.

🛠️ Tip: If you have any problems during installation, check the The Troubleshooting section for common issues and solutions.