WordPress Starter

A starter repository for WordPress websites for organisers, campaigns and anyone else who finds it useful.

This folder structure uses the Bedrock pattern, a modern WordPress stack.

• Docker installed
• PHP and Composer installed locally. If not, you can use them in containers provided, prefixing all Composer commands below with docker compose run composer <command>

1. Clone This Repository
2. Search and replace all instances of wordpress-starter-template and WordpressStarterTemplate with the name of the new project, in kebab and camel case respectfully. Also rename the theme folder web/app/themes/wordpress-starter-template to the name of the new project.
3. If you have PHP and Composer installed locally you can run from this directory composer install. Otherwise run composer install via Docker with docker compose run composer install.
4. Copy .env.example to .env, running cp .env.example .env. The example file contains variables required for this Docker Compose setup but modify details appropriately as per the Bedrock documentation as required.
5. Start up all containers with:

docker compose up

5. Build the theme (see Theme), then install WordPress, activate the theme and load the page fixtures in scripts/fixtures:

scripts/setup.sh http://localhost:8082 "WordPress Starter Template"

6. You can access the site at http://localhost:8082, and log in with admin / admin.

If ports 8082 or 3308 are already in use by another project, set WEB_HOST_PORT and DB_HOST_PORT in .env, and update the port in WP_HOME to match.

Run the smoke test with the site title and URL. Extra path=text arguments check a page contains some text:

scripts/smoke-test.sh "WordPress Starter Template" http://localhost:8082 "/blocks/=wp-block-wordpress-starter-template-example"

CI builds the theme, runs setup.sh and runs the smoke test against a fresh install, then:

• scripts/test-plugins.sh activates every plugin and checks the site still works
• the browser tests (npm run test:e2e from the theme folder, see Theme) load the front end, the block editor and the Site Editor with every plugin active, and fail on JavaScript errors, failed requests, PHP error output and blocks the editor can't load
• scripts/check-php-log.sh fails if PHP logged any errors or warnings along the way

A second job, .github/workflows/production.yml, installs the site the way deploy.yml deploys it: Composer without dev packages, the production theme build, WP_ENV=production and every plugin active, including Wordfence. It then runs the plugin, smoke, browser and PHP log checks against that.

These cover what a dependency bump can break, so a Renovate pull request that passes CI can be merged with confidence. See What CI checks for dependency updates.

The theme in web/app/themes/wordpress-starter-template is built with webpack, TypeScript, Sass and PostCSS, and needs Node 24 (see .nvmrc). From the theme folder:

• npm ci installs dependencies
• npm run dev starts the webpack dev server on port 9000, which the theme loads assets from when WP_ENV is development. It also writes to build/, where blocks load their scripts and styles from.
• npm run build builds assets to build/ for other environments
• npm run typecheck type-checks with TypeScript 7
• npm test builds the theme into temporary folders and checks the output: every file each block.json loads, WordPress packages left to WordPress, and TypeScript, Sass and PostCSS compiled as configured
• npm run test:e2e runs the browser tests against the site at SITE_URL (default http://localhost:8082), starting the dev server if it isn't running. Set E2E_DEV_SERVER=false for a site that isn't in development, which loads the production build instead. Run npx playwright install chromium once first. They log in as admin / admin, so run them against the local site after scripts/setup.sh.
• npm run lint checks lint and formatting with ESLint and Prettier, as CI does, and npm run lint:fix fixes what it can

TypeScript 7 does not yet have a compiler API, which ts-loader and typescript-eslint need. As recommended in the TypeScript 7 release notes, the typescript package is aliased to @typescript/typescript6 for those tools, and TypeScript 7 is installed as @typescript/native, which provides tsc. Once TypeScript 7.1 ships an API and those tools support it, the alias can be removed.

Each custom block is a folder in blocks/. Copy blocks/example to start one:

• block.json defines the block and points at its built files in build/blocks/<name>/
• index.tsx is the editor script, written in TypeScript and JSX
• render.php renders the block on the server
• style.scss styles the block on the front end and in the editor
• view.ts (optional) is front-end JavaScript, loaded through viewScript in block.json

webpack builds and functions.php registers every block folder automatically. @wordpress/* and React imports use WordPress's own copies at runtime. Add new blocks to scripts/fixtures/blocks.html so they show at /blocks/ and are covered by CI. See CLAUDE.md for theme conventions.

This template comes with some useful development tools for use within WordPress itself.

Crucial. Save off block themes that you are making in the full site editor to the theme on disk. Add fonts direct from the WordPress backend, including Google Fonts.

Create WordPress patterns from within the WordPress backend. They are automatically saved to the theme on disk, with appropriate metadata and can also be modified in this way.

Generate a lot of dummy content to see how the website looks and feels with full content in it.

Again for creating dummy data, this allows quick duplication of posts to fill things out.

Renovate opens pull requests for Composer, npm, Docker and GitHub Actions updates. Each kind is covered by these checks:

1. Run composer outdated to verify any dependencies that require updating.
2. Run composer bump to bump minor versions and save results to composer.json.
3. Update within composer.json. For example the wordpress package.
4. Run composer update.
5. Commit the result.

WP-CLI is installed in the wordpress container.

docker compose run wordpress wp <command>

Note WP-CLI will not work on the host machine, as WordPress configuration refers to databases within the Docker network, not the host machine.

Run docker compose run composer require wp-plugin/plugin-name.

Documentation for Bedrock is available at https://roots.io/bedrock/docs/.

The following are instructions on how to setup a new site on Kinsta.

You will need to have "Company developer" or above permissions in order to create a site.

These are exhaustive manual instructions, but should not be required after initial setup.

1. Log in to your Kinsta account and create a new site.
2. Select “Don’t install WordPress” and choose the London data center.
3. The provisioning process will take about 10 minutes.

Once the site is created, you will have both Live and Staging environments. Start with the Live environment, and you can later create a Staging environment as needed.

You will use the same SSH key to connect to Kinsta and pull from GitHub.

1. Generate an SSH Key Pair (if you don’t already have one)

2. On your local machine, generate a new SSH key pair:

   
   ssh-keygen -t rsa -b 4096 -C "your-email@example.com"
   
   

   This will create two files: id_rsa (private key) and id_rsa.pub (public key).

1. In Kinsta, navigate to Sites > Live Environment > Info.
2. Under SSH Access, click “Add SSH Key” and paste the contents of the id_rsa.pub file.

1. Go to your GitHub profile > Settings > SSH and GPG keys.
2. Click New SSH key, paste the contents of the id_rsa.pub file, and save it.

You need to set up SSH forwarding so that you can connect to Kinsta and GitHub using the same key.

1. Open or create the ~/.ssh/config file and add the following block:

      Host <your_site>_live
      User <Kinsta SSH username from Live Environment>
      Hostname <Kinsta SSH hostname>
      Port <Kinsta SSH port>
      IdentityFile <path_to_your_private_key>
      ForwardAgent yes
   
   

2. Replace the placeholders (<your_site>, , , , <path_to_your_private_key>) with the actual details from the SFTP/SSH section of your Live Environment in Kinsta’s dashboard.

3. Start the SSH agent and add your GitHub SSH key:

   eval "$(ssh-agent -s)"
   ssh-add ~/.ssh/id_rsa
   

1. SSH into the Live environment with the following command: ssh <your_site>_live

2. Test the GitHub SSH connection by running: ssh -T git@github.com

After accepting the host authenticity, you should see a confirmation message from GitHub.

1. Remove the Existing public Directory Once logged into the Live environment, remove the default public directory: rm -r public

2. Clone Your WordPress Theme from GitHub git clone git@github.com:<your_repo>.git public

3. Install Dependencies with Composer Navigate to the public directory and install the dependencies: cd public composer install --no-dev

4. Set Up the .env File Copy the .env.example file to .env: cp .env.example .env

   Modify the .env file as per the Bedrock documentation. Update the database and other environment details You can find database credentials in the Kinsta dashboard under Database Access. Set the WP_HOME to http://localhost.

5. Install WordPress

   Run the following command to install WordPress and create the necessary database tables:

   wp core install --url=<Kinsta Primary Domain URL> --title=<Site Title> --admin_user=<Admin Username> --admin_email=<Admin Email>
   

   This command will output the password for the new admin user. Save this password for later.

6. Ask Kinsta support (via Intercom chat) to update the NGINX configuration to point to public/web.

7. Follow Kinsta’s guide to point your domain to the Kinsta environment.

8. Set Up SSL and Force HTTPS

   • Go to the Tools section in the Kinsta dashboard for the live environment.

   • Generate a new Let’s Encrypt SSL certificate.

   • Enable Force HTTPS by selecting “Force all traffic to the primary domain”.

9. In the Kinsta Domains section, make sure your primary domain is selected and marked as primary.

1. You can use the same SSH key you generated for both Kinsta and this repository's GitHub Actions deploy workflow.

2. Ensure the public key (id_rsa.pub) has been added to the SSH Access section for the Live environment in the Kinsta dashboard (as shown in the previous steps).

3. Add the SSH Key as a Secret in GitHub

   • In your repository, go to Settings > Secrets and variables > Actions.

   • Click New repository secret and create the following secrets:

   • SSH_PRIVATE_KEY: Paste the contents of your id_rsa (private key).

   • SSH_USER_HOST: Enter the username and hostname from Kinsta’s SFTP/SSH details

   • SSH_PORT: Enter the SSH port number from Kinsta’s SFTP/SSH details