There’s no place like 127.0.0.1/32

As the old saying goes there’s no place like home and that’s especially true for software development. It seems that everyone and their brother has a local development environment. The problem is that I work in WordPress MultiSite and not many of them work well for this special kind of environment.

I have friends that swear by VVV or straight up vagrant and then there are those that are all docker this and docker that. Look I don’t want to rain on your parade if you’ve found a solution that works for you then by all means use it. If you are looking for a solution then continue reading.

When I wrote The TAO of Releasing I touched upon the local environment but I did not go into any details. So let’s remedy that. However let me preface all that follows with it’s a lot of information to take in and I shall have to break it up into parts.

Let us begin for those who are unfamiliar with WordPress MultiSite at a short description of what it is. In essence WPMS is a cluster of WordPress sites that share a unified codebase, and may share plugins, themes and even users. While sub-directory MultiSites are the default, in this example we will be building a subdomain based MultiSite. There are a bunch of article about which is better and I really do not care to debate it so if you are curious Google it and move on.

The local environment we will be working with is based on Trellis. And the installation is relatively straight forward. In addition we will be utilizing Bedrock to setup the frame work for our WordPress MultiSite environment but not really using much of that system. Before we begin make sure that you have already installed the required dependencies: Vagrant and Virtualbox. In addition I highly recommend installing Composer before you begin.

Once we’ve setup Trellis and Bedrock and then cloned the site repo in we will end up with something similar to the following diagram.

For the sake of this discussion I created a ccl directory in my Projects folder and I have pushd into that new directory to checkout the trellis engine.

git clone --depth=1 git@github.com:roots/trellis.git && rm -rf trellis/.git

After this we will run the following Composer command. Remember that I mentioned earlier you should have composer installed on you local machine.

composer create-project roots/bedrock site

Once this has completed you can pushd into the app directory under site/web. If you have an existing WordPress repo you can replace the contents of what is in app with that. For the time being we will ignore this directory and focus on launching the local site. Depending on your personal development ethos open your favorite editor and let’s get to work. Switch to the trellis directory and let’s open the trellis/group_vars/development/vault.yml. We are going to change the example.com domain in the file to SOMETHING-cluster.lcl. In my case I have chosen cheddar-cluster.lcl as my system domain.

vault_wordpress_sites:
  cheddar-cluster.lcl:
    admin_password: admin
    env:
      db_password: example_dbpassword

Next we will move onto the WordPress configuration by editing trellis/group_vars/development/wordpress_sites.yml which will require a fair amount of modification. Below you will see the default file.

# Documentation: https://roots.io/trellis/docs/local-development-setup/
# `wordpress_sites` options: https://roots.io/trellis/docs/wordpress-sites
# Define accompanying passwords/secrets in group_vars/development/vault.yml

wordpress_sites:
  example.com:
    site_hosts:
      - canonical: example.test
        redirects:
          - www.example.test
    local_path: ../site # path targeting local Bedrock site directory (relative to Ansible root)
    admin_email: admin@example.test
    multisite:
      enabled: false
    ssl:
      enabled: false
      provider: self-signed
    cache:
      enabled: false

The following are the changes I am introducing:

wordpress_sites:
  cheddar-cluster.lcl:
    site_hosts:
      - canonical: cheddar-cluster.lcl
      - canonical: mikel.cheddar-cluster.lcl # additional subdomain sites
    local_path: ../site # path targeting local Bedrock site directory (relative to Ansible root)
    admin_email: admin@cheddar-cluster.lcl
    multisite:
      enabled: true
      subdomains: true
    ssl:
      enabled: false
      provider: self-signed
    cache:
      enabled: false
    env:
      domain_current_site: cheddar-cluster.lcl

The final file that we will me modifying is in the bedrock portion of the system. Open site/config/application.php in your editor and add the following immediately after the first comment block.

    define( 'WP_ALLOW_MULTISITE', true );
    define( 'MULTISITE', true );
    define( 'SUBDOMAIN_INSTALL', false );
    $base = '/';
    define( 'DOMAIN_CURRENT_SITE', 'cheddar-cluster.lcl' );
    define( 'PATH_CURRENT_SITE', '/' );
    define( 'SITE_ID_CURRENT_SITE', 1 );
    define( 'BLOG_ID_CURRENT_SITE', 1 );

This is a slightly hidden step necessary to get WordPress MultiSite up and running. Meanwhile back in the trellis directory execute vagrant up and let the Ansible magick happen. During the process depending on the version of operating system you are hosting on you may see a popup like the following.

Click OK to proceed. It is important for properly setting up the NFS shared resources because administrative privileges are required to modify the /etc/exports file. Unfortunately I have not found a way to make OK the default so every time you launch the vagrant you will see this dialog box.

If the build process does not complete say perhaps you neglected to save the vault file in step one. Correct the file, and save it this time, then type vagrant provision to restart the process. If resuming still does not work the simply run vagrant destroy and start build process over. Obviously if you are destroying a working local environment you should have a database backup set aside to help when you provision the new vagrant.

Once the process has completed you can test your handy work by typing http:// plus the SOMETHING-cluster.lcl domain you entered in the files above. You should see something like the following in your browser.

Simply add /wp-admin/ to the URL and let’s log in with the default local admin credentials.

You should observe that unlike your average WordPress installation you have the My Sites menu options.

In addition you can add network/ to the main wp-admin URL to access the Network CMS. You’ll notice that the network admin differs from the standard WordPress admin. You have control over which themes are available and can activate plugins across the entire cluster. You can even deny local site admins access to the plugins page in their respective CMS. Finally you can create and modify sites.

I hope you have enjoyed this the first article in setting up a local development environment. The next article will focus on properly setting up the app directory and provisioning your MultiSite repository.

Finally I have created a Cheddar Cluster Local repository hosted on GitLab that you may clone or fork for your own needs based upon this article. I intend to use this as the base for all of my MultiSite projects. That will be a future article in itself.