Monday, 20 November 2017

Installing Bedrock & Wordpress For Theme Development Using An Apache VirtualHost Server On Centos 7 RHEL.



Bedrock from Roots is a great tool for developing Wordpress projects and comes with a huge range of functionality including explicit dependency tracking using  Composer 

This tutorial is to create an installation of Bedrock using an Apache VirtualHost Server setup on a local Linux machine. 

Its a self-contained WordPress stack that installs an explicit version of WordPress and required plug-ins (composer install) which can be easily configured. All configuration is kept in a .env text file).

It has a multi-stage environment and you can have a development configuration for working locally, a staging configuration for tests, and a production configuration for the live site. 

System Requirements 

Below are the requirements for working with Bedrock

You should be comfortable working on the command line.

PHP >= 5.5

You need Composer on the server (install instructions)

You need to have a working Ruby and gem environment on your machine to perform deploys.

You need to have WP-CLI installed locally and on the server if you plan to use it. It's not required, but it is a useful tool (install instructions)

This is in addition to all the normal WordPress server requirements, like MySQL etc.

Set Up An Apache VirtualHost Server For Local Development With own Domain Name etc.

First Set Up Your VirtualHost Server by following the tutorial at 


When you have done this (just create one VirtualHost Server for now, you can create more another time) then you will install bedrock in to the root of that server, which if you have done it correctly should be nicely on your desktop in a folder called vhost1.com or your chosen name. I will use vhost1.com for this tutorial.

Installing Bedrock


For a brand new WordPress project. First, you'll need a copy of Bedrock, which you can get from its repo at


Don't clone the repo because you are going to use for for your own changes, and create your own repo for your projects, just download the zip file and extract it in to your vhost1.com folder, then enter the bedrock directory and cut/paste the contents from bedrock master in to the root vhost1.com folder (delete the now unused bedrock master folder) 

So you have bedrock installed at the root of your vhost1.com server not in its own folder. You will just have 2 main levels to deal with for now, the root at vhost1.com and the sub folder /web/ with a wordpress installation in it.


Now that you have downloaded the repo and added it to your vhost1.com server, you can initialize your own repository for the project with git initialize in the vhost1.com root.

$ git init

Install Composer dependencies.

Install the Composer dependencies like Wordpress etc, (however I am going to change some of these), Composer puts Wordpress in the /web/ folder of bedrock under a folder called wp.

Change Wordpress version. (optional)

The default version of Wordpress that composer currently installs is the latest version, and I have a bug with it which prevents me changing themes properly which is not much good if you are building a new theme, so I use an older version of Wordpress, typically 4.8, so I change the Wordpress entry in composer.json to 4.8 (from 4.9).

Otherwise if you are happy with 4.9 just run

$ composer install (from root of vhost1.com/bedrock)

(Later on, you can also upgrade Wordpress at any time by running)

$ composer require johnpbloch/wordpress <version no>

(And update the database schema with)

$ wp core update-db

Now create a database for your bedrock/wordpress install.

Create an empty database called bedrock in mysql command or gui program (or your chosen name)

Hit Control + H in vhost1.com root (now bedrock root) to reveal the hidden files, you need to create a .env file to get set up.

Open up .env.example and save it as .env in order to set up the configuration of Bedrock and Wordpress.

Change the values as below

DB_NAME=bedrock (or the database name you created)
DB_USER= your mysql user
DB_PASSWORD=your mysql user password

# Optional variables
# DB_HOST=localhost
# DB_PREFIX=wp_

(You will leave the above 2 values until the Wordpress install, the host refers to the database host not your VirtualHost name, so it will probably be localhost. Enter that and the table prefix if required at the install stage when you browse to it.)

Your wp_home is the web folder inside vhost1.com root and the wp_siteurl is the wp folder inside of that. So as below.

WP_ENV=development
WP_HOME=http://vhost1.com/web/
WP_SITEURL=${WP_HOME}/wp

Generate your keys here: https://roots.io/salts.html and just copy/paste them into the last section.

Save the file and browse to http://vhost1.com/web/wp/ to start the wordpress installation.

Enter the usual details mainly referring to the database and install Wordpress in to your Bedrock project. 

You may have to manually create a wp-config.php file which you just copy/paste the given values in to the vhost1.com/web/ folder. If not then it will probably be in the wp folder. And you may want to move it, see below.

Now you have installed Wordpress in to your Bedrock Project, you can upload it to github for others to collaborate if necessary.

So from root folder run

$ git add . && git commit -m 'First commit'

Your folder structure inside the vhost1.com directory should now look as below.

config
│ ├── application.php
│ └── environments
│ ├── development.php
│ ├── production.php
│ └── staging.php
├── vendor
├── web
│ ├── app
│ │ ├── mu-plugins
│ │ ├── plugins
│ │ ├── themes
│ │ └── uploads
│ ├── wp
│ └── wp-config.php

Or the wp-config.php may be inside the wp folder, you might want to move it to the web folder if this is the case, see below for reason.

config: this is where you configure WordPress. These files can't be accessed from the Internet.

config/application.php: this file contains the usual WordPress configuration and is intended to include base settings that are common to all environments.

config/environments/*: these contain environment-specific settings. For example in production it disables errors output.

vendor: dependencies managed by Composer will be installed there, except WordPress plugins and themes; if you inspect the composer.json file you'll see that these kind of packages will be moved in web/app/{mu-plugins,plugins,themes}/.

web: files included in this directory are publicly available
— only the files that are required are in the 
web folder (see config above).

web/app: this is the old wp-content folder. It's been renamed to reflect its content. This is where your plugins and themes will end up.

web/wp: the WordPress package. This should be put in vendor but can't be because of WordPress limitations.
web/wp-config.php: this file is well-known, in Bedrock it acts as a loader to load settings from the config directory. It needs to stay here because WordPress core hard codes paths.

Environment Settings.

the “.env” file is ignored by git which is a benefit. It also allows you to define a different password/key for each machine. If every developer has to generate a new one for testing purposes and the key is stored in a file that's tracked by git you have to remember not to add that file to the staging area.

So add it to the .env file
DB_PASSWORD=<password>
And define it in the config file
define ('DB_PASSWORD', env('DB_PASSWORD'));

Environment-specific files (`config/environment/  are required before the main file ('config/application.php') So you cant override settings.
If you have the same configuration for development and staging but a different one for production, then do the following.
define it in every environment file (`development.php`, `staging.php`, `production.php`, etc).

put it in the `.env` file and define it in the main application (`application.php`) file.

Plugins

If your plugin is available in the official plugin registry, you can install using Composer and WordPress Packagist, which is a Composer repository that mirrors WordPress' official plugin and theme registry.

Bedrock has added wpackagist's repository, so installing a plugin is just a matter of running the following command to install the latest version

$ composer require wpackagist-plugin/<name>
$ git add composer.json composer.lock
$ git commit -m 'Install <name> plugin'

Plugins are prefixed with wpackagist-plugin/ so the plugin Memberful WP becomes wpackagist-plugin/memberful-wp.

You can also provide a constraint for the plugin version  no.

$ composer require wpackagist-plugin/memberful-wp ~1.0
$ git add composer.json composer.lock
$ git commit -m 'Install Memberful plugin'
   
You can also do the same if you manually edit the composer.json file and run composer install.

If your plugin isn’t available on the official registry, you will need to put it in `web/app/plugins` and remove it from the ignore list:

$ echo '!/web/app/plugins/my-plugin' >> .gitignore
$ git add .gitignore web/app/plugins/my-plugin
$ git commit -m 'Add Plugin'

If you have a git repository for the plugin, you can use Composer directly. Add the following to the repositories array of the composer.jsonfile

composer.json

{

"type": "git", "url": "<repository url>"

}

The repository needs to contain a `composer.json` manifest file in the root.



composer.json

{

"name": "Plugin name", "description": "Plugin description", "type": "wordpress-plugin", "license": "proprietary",

"require": { "php": ">=5.5", "composer/installers": "~1.0.12" }

}
You can run


$ composer require plugin-name

to install it.

And activate it from wp-cli

$ wp-plugin activate plugin-name

If plugins ask you to modify the wp-config.php file, move those new settings to `application.php`, or the environment specific one.
 
Themes

Themes work the same way as plugins, with two differences:
  1. Their directory is web/app/themes

  1. Composer's vendor name is wpackagist-theme

If you use a theme that's available on the official WordPress registry you can install it with Composer:

$ composer require wpackagist-theme/hueman

If you're going to develop your own theme, create its folder under web/app/themes and you're good to go. 

There is much more that you can do with Bedrock including deploying with Capistrano 

However here we are just looking at setting it up in a VirtualHost Server for initial local testing. If you followed the above successfully then you are up and running.