Installing and Configuring Bedrock in the ServBay Environment

Overview

This document guides you through installing and configuring Bedrock within the ServBay local development environment. Bedrock offers a modern WordPress project structure leveraging Composer for dependency management, enhanced configuration handling, and adherence to best practices—all to improve the efficiency and security of your WordPress development, deployment, and maintenance. Combined with ServBay's robust and user-friendly local environment management, you can quickly set up your Bedrock development workflow.

What is Bedrock?

Bedrock, created by the Roots team, is a WordPress project structure designed to improve the developer experience. It stands apart from the traditional WordPress setup with features such as:

• Dependency management via Composer: Handle WordPress core, themes, and plugins via Composer, simplifying updates and resolving conflicts.
• Improved configuration management: Implements the Twelve-Factor App principles by using .env files for environment variables, keeping config separate from code for better security and flexibility.
• Enhanced project organization: WordPress core resides in a dedicated subdirectory (web/wp), while themes and plugins are located in web/app for a cleaner structure.
• Increased security: Includes security improvements by default, such as hiding core file paths.

Bedrock is an ideal foundation for building robust, maintainable, and modern WordPress applications.

Why Use ServBay for Bedrock Development?

ServBay is a local web development environment tool built exclusively for macOS. It integrates leading web servers (Caddy/Nginx/Apache), multiple PHP versions, databases (MySQL/PostgreSQL/MongoDB), and development languages like Node.js, Python, Go, and Java. Using ServBay with Bedrock allows you to:

• Set up instantly: ServBay includes all required PHP, Composer, and database components for Bedrock—no additional installation or setup.
• Switch versions effortlessly: Easily toggle between PHP versions to test Bedrock compatibility across environments.
• Integrated database management: Manage Bedrock's databases using ServBay's built-in phpMyAdmin or Adminer.
• Simplify site configuration: Use ServBay's GUI to quickly configure Bedrock project websites (virtual hosts) and direct them to the correct web root.
• Unified management: Handle all local development packages and websites inside a single app.

Prerequisites

Before you begin, ensure that you meet the following prerequisites:

• ServBay is installed and running on macOS.
• You have basic command-line knowledge.
• You have a basic understanding of Composer (this guide includes specific commands).

Steps to Install Bedrock

This section provides a detailed walkthrough for installing and configuring a Bedrock project in the ServBay environment.

Step 1: Create Your Project Directory

Navigate to ServBay's default web root /Applications/ServBay/www and create a new directory for your project. It's recommended to use a descriptive name, such as servbay-bedrock-app.

cd /Applications/ServBay/www
mkdir servbay-bedrock-app
cd servbay-bedrock-app

This directory will serve as the root of your Bedrock project.

Step 2: Create a Bedrock Project Using Composer

ServBay ships with Composer. You can directly use the composer command in your terminal. In your newly created project directory (/Applications/ServBay/www/servbay-bedrock-app), run the following Composer command to set up your Bedrock project:

composer create-project roots/bedrock .

This command downloads the latest version of Bedrock and all its dependencies into the current directory (.). The process may take several minutes depending on your internet speed.

Step 3: Create Database and User

Bedrock and WordPress require a database to store website content and settings. We'll use ServBay's built-in phpMyAdmin to create the database and user.

1. Access ServBay’s Built-In phpMyAdmin

   Open your browser and navigate to ServBay's default local address: https://servbay.host/. On the welcome page, find and click the "phpMyAdmin" link to open the database management interface.

2. Create a Database User

   For security and manageability, it’s recommended to create a dedicated database user and database for each project.

   1. Go to the User Accounts Page

      In phpMyAdmin's main dashboard, click the “User accounts” tab in the top navigation.

   2. Add New User

      Click "Add user account" and provide the following details:

      • Username: Enter a username for this project, e.g., bedrock_user.
      • Host: Select localhost. This restricts the user to local connections.
      • Password: Enter a secure password for this database user. Make a note of it. For local development, something like password123 is acceptable, but always use strong passwords for production.
      • Re-type: Re-enter the password.

      In the “Database for user” section, select “Create database with same name and grant all privileges.” This will create a database named bedrock_user and grant full privileges to the new user.

      Ensure “Grant all privileges” is checked so the user has necessary permissions.

      Click the “Go” button at the bottom to complete user and database creation.

Step 4: Configure Bedrock

Bedrock uses environment variables, typically stored in a project root .env file, for configuration.

1. Edit the Environment Config File

   In your Bedrock project root (/Applications/ServBay/www/servbay-bedrock-app), you’ll find a sample file named .env.example. Copy and rename it as .env:

   cp .env.example .env

   The .env file is used for actual project configuration; .env.example is a template without sensitive data.

2. Edit the .env File

   Open the .env file with your preferred text editor (e.g., VS Code, Sublime Text, Nano, etc.). Locate the database connection settings and update them according to the database/user you created in Step 3:

   # Database
   DB_NAME='bedrock_user' # Database name, same as username
   DB_USER='bedrock_user' # Database username
   DB_PASSWORD='password123' # Database password
   DB_HOST='localhost' # Database host, usually localhost for local ServBay
   DB_PREFIX='wp_' # Table prefix—leave as default or change as needed
   
   # WordPress Environment
   WP_ENV='development' # Environment, options: development, staging, production
   
   # Site URLs
   WP_HOME='http://servbay-bedrock.local' # Full site URL
   WP_SITEURL='${WP_HOME}/wp' # URL to WordPress core directory

   Update the values according to your configuration (especially the database password, DB_PASSWORD).

   WP_HOME and WP_SITEURL define the URLs for accessing your site in the browser. servbay-bedrock.local is a common convention for local development; you may change this if you wish. WP_SITEURL points to the WordPress core in the web/wp subdirectory.

   You can also configure additional Bedrock/WordPress options in the .env file, such as setting constants or email settings.

Step 5: Configure the Web Server (ServBay Website)

To enable ServBay's web server to serve your Bedrock project, you'll need to add a new site (virtual host) in ServBay.

1. Add a New Website

   Open the ServBay app and click the "Websites" section in the navigation sidebar. Click the "+" or "Add Website" button to create a new configuration. Enter the following details:

   • Name: A descriptive name for the site, e.g., My Bedrock Site. This is for internal management in ServBay.
   • Domain: Enter the domain set in WP_HOME in your .env file, e.g., servbay-bedrock.local. ServBay will map this domain to your local machine (127.0.0.1).
   • Site Type: Choose PHP.
   • PHP Version: Select any PHP version compatible with Bedrock. Bedrock generally works with recent PHP versions—it’s recommended to choose ServBay's latest stable PHP version.
   • Site Root Directory: Important—the web root is not your project root, but the web subdirectory inside your project. Set this as /Applications/ServBay/www/servbay-bedrock-app/web.

2. Save Configuration

   Once all details are filled out, click the save button. ServBay will automatically update its web server configuration. If prompted, restart the related service as directed.

Step 6: Complete WordPress Installation

With your Bedrock project and ServBay website set up, you can now complete the classic WordPress installation process via your browser.

1. Open the Installation Page

   Open your browser and navigate to the WP_SITEURL you set in .env and ServBay, e.g., http://servbay-bedrock.local/wp. If everything is set up correctly, you'll see the WordPress installation wizard.

2. Enter Database Information

   The installation wizard will prompt for database connection details. Enter the values matching those created in Step 3:

   • Database Name: bedrock_user (matches the username)
   • Username: bedrock_user
   • Password: The password you set (e.g., password123)
   • Database Host: localhost
   • Table Prefix: wp_ (typically left as default unless otherwise required)

   Click the "Submit" button. WordPress will attempt to connect to the database.

3. Set Up Site Information

   If the database connection is successful, you’ll proceed to the site settings page. Enter the following:

   • Site Title: The name of your website.
   • Username: Create an admin username.
   • Password: Set a strong password for the admin user.
   • Your Email: Enter the admin email address.
   • Search Engine Visibility: For local development, it's usually best to check "Discourage search engines from indexing this site."

4. Finish Installation

   Click "Install WordPress" to complete the process. WordPress will finalize the setup and create necessary tables. Upon success, you'll see a confirmation page with a link to log in to the WordPress admin dashboard.

Step 7: Install Themes and Plugins (via Composer)

Bedrock encourages using Composer for managing themes and plugins, instead of via the WordPress admin UI.

1. Find the Composer Package Name for Theme/Plugin

   Many popular themes and plugins have Composer packages, typically available on Packagist (packagist.org) or WordPress Packagist (wpackagist.org). Package names usually follow the format vendor/package-name, e.g., wpackagist-theme/twentytwentyone or wpackagist-plugin/wordpress-seo.

2. Install Using Composer

   From your Bedrock project directory (/Applications/ServBay/www/servbay-bedrock-app), run the Composer command:

   Install a theme:

   composer require wpackagist-theme/your-theme-name

   Install a plugin:

   composer require wpackagist-plugin/your-plugin-name

   Replace your-theme-name and your-plugin-name with actual package names. Composer installs themes to web/app/themes and plugins to web/app/plugins.

3. Enable in the WordPress Admin

   Log in to your WordPress admin dashboard (http://servbay-bedrock.local/wp/wp-admin/):

   • Themes: Go to "Appearance" -> "Themes," find your installed theme, and activate it.
   • Plugins: Go to "Plugins" -> "Installed Plugins," find your installed plugin, and activate it.

   While Bedrock supports installing themes/plugins via Composer, you can still use the WordPress admin to upload .zip files; however, Composer provides a more modern, maintainable way—recommended by Bedrock.

Building Your Website with Bedrock

You now have Bedrock installed and configured in ServBay. You can use it just like standard WordPress, while also enjoying the development benefits Bedrock brings.

• Create Pages and Posts: Log in to the WordPress admin, and create content via the "Pages" and "Posts" menus, as usual.
• Configure Navigation: Set up menus in "Appearance" -> "Menus."
• Customize Widgets: Manage sidebar and area content in "Appearance" -> "Widgets."
• Theme and Plugin Development: If you're a developer, work directly in the web/app/themes and web/app/plugins directories.
• Configuration management: Use the .env file to handle different configuration settings for development, staging, and production.

Frequently Asked Questions (FAQ)

• Q: What if I see a 404 error when visiting http://servbay-bedrock.local?

  • A: Make sure the website domain in ServBay matches the one you're visiting.
  • A: Verify that the site root in ServBay points to /Applications/ServBay/www/servbay-bedrock-app/web.
  • A: Ensure ServBay’s web server is running.
  • A: Double-check your .env file’s WP_HOME setting.

• Q: What if I encounter a database connection error at http://servbay-bedrock.local/wp?

  • A: Check that the DB_NAME, DB_USER, DB_PASSWORD, and DB_HOST in the .env file are exactly the same as the database/user you created in phpMyAdmin.
  • A: Ensure the MySQL (or database of choice) service is running in ServBay.
  • A: Confirm the user you created in phpMyAdmin has full privileges on the relevant database.

• Q: Why don’t my themes or plugins show up after installation?

  • A: If you installed them with Composer, make sure you ran composer install or composer require successfully from the project root (/Applications/ServBay/www/servbay-bedrock-app).
  • A: Composer installs themes to web/app/themes and plugins to web/app/plugins. Check if the relevant files are present there.
  • A: Look for and activate them from the WordPress admin: under "Appearance" -> "Themes" or "Plugins" -> "Installed Plugins."

• Q: How do I update Bedrock, WordPress core, themes, or plugins?

  • A: With Composer management, simply run composer update in your project root to update all, or composer update vendor/package-name for a specific theme/plugin. After updating, you might need to run database updates in the WordPress admin if prompted.

Conclusion

By following these steps, you have successfully set up a Bedrock-powered WordPress project in your ServBay local development environment. With ServBay simplifying environment management and Bedrock supporting modern workflows, your WordPress projects will be easier, more secure, and more efficient to develop and maintain. Now, you’re ready to harness the power of Bedrock for your next WordPress site!