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 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.json
file
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:
-
Their
directory is web/app/themes
-
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.
Labels: Apache, Bedrock, Centos 7, Composer, Linux, RHEL, VirtualHost, Wordpress