SilverStripe, Homestead & Forge 1/3

Recently I’ve had to develop a site or two using the CMS framework SilverStripe. It’s a relatively straightforward php CMS/Framework but more than that it has a Common Web Platform that incorporates a ton of other packages and services such as custom virtual machines and git deployment. However, these services are quite pricy and not always appropriate for the size of a project.

Forge created by Taylor Otwell is a php deployment service aimed at taking the hassle out of DevOps for php developers. It launches instant php platforms on the likes of Linode and DigitalOcean and includes a Nginx, PHP5.6, Postgres, Redis, MySQL, Node, Memcached, Beanstalkd and more. It’s specifically tuned for the Laravel framework but works with pretty much any php project. One nice feature is it’s ability to allow a ‘push to deploy’ service using the likes of Github, Bitbucket and other common git service providers.

Homestead is a pre-packaged Vagrant box that allows you to setup a local development environment near identical to that which Forge will launch by default. There are many advantages to using a tool like Vagrant to provision Virtual Machines but perhaps the most obvious here is the knowledge that your local development environment will match that of your production environment.

So to state the obvious, we can create a nice SilverStripe application using Homestead, Forge and Github for an elegant and relatively easy deployment pipeline.

Since there is a fair bit involved in getting this all initially set-up and working I’m going to break this down into three articles that cover each component on it’s own. To follow along I’m assuming you are already familiar with tools like Vagrant, Git, Github, the Terminal/iTerm2, Vim, Composer, php and SilverStripe. You don’t need to be an expert in any of these but knowing what they are will be of some help. With regards to using the Vim editor I’ll add some helpful commands to ensure you can follow along.

SilverStripe

To get started we will begin by installing SilverStripe using the package manager Composer. I wont be installing the full Common Web Platform that SilverStripe offers but the same principles crossover.

You can visit the SivlerStripe downloads page for specific information on framework installation. Since we’re using Composer we can open the Terminal and run the following command:

$ composer create-project silverstripe/installer /forge-silverstripe 3.1.8

This will create a new SilverStripe project in a folder called ‘forge-silverstripe’. Once this has finished downloading and installing open the project in your preferred editor, mines PhpStrom/IntelliJ for php projects.

Configuring SilverStripe

SilverStripe lets you set your database config in a few different ways. We will put the configuration in _ss_environment.php so open that up and add the following snippet.

// Set database variables
define('SS_DATABASE_NAME', 'forgesilverstripe');

define('SS_DATABASE_SERVER', getenv('DB_SERVER'));

define('SS_DATABASE_USERNAME', getenv('DB_USERNAME'));
define('SS_DATABASE_PASSWORD', getenv('DB_PASSWORD'));

// Set development environment
$env = getenv('APP_ENV') == 'local' ? 'dev' : 'live';
define('SS_ENVIRONMENT_TYPE', $env);

// Set file mapping for Sake CLI
global $_FILE_TO_URL_MAPPING;
$_FILE_TO_URL_MAPPING['/home/forge/default'] = 'http://forge-silverstripe.nz';
$_FILE_TO_URL_MAPPING['/home/vagrant/Sites/forge-silverstripe'] = 'http://forge-silverstripe.local';

// Set default admin account
if (getenv('ADMIN_USERNAME')
    && getenv('ADMIN_PASSWORD')) {

    define('SS_DEFAULT_ADMIN_USERNAME', getenv('ADMIN_USERNAME'));
    define('SS_DEFAULT_ADMIN_PASSWORD', getenv('ADMIN_PASSWORD'));
}

We’re adding a lot of important configuration in the above snippet and made extensive use of php’s environment variables to set several key options. Using environment variables this way means we can check this code into our git repo without worrying about potentially exposing sensitive configuration information such as passwords. Lets break down what we’ve configured.

In the first group we set the database. In this case it’s a MySQL database and we pull in the appropriate details that we will set up later in our Nginx server config. I’ve hardcoded the database name in this instance because often you will use Homestead to host multiple applications you’ve got on the go. In this case a single environment variable name DB_NAME would potentially conflict with another application database. While we could create a more specific variable name I think in this case it’s ok to directly drop the in db name.

In our second config block we are letting SilverStripe know about the environment that it’s running on. SilverStripe allows you to perform specific tasks while in development mode that are not accessible when in production for security purposes. So we are checking the local APP_ENV variable made available by Homestead and then setting it appropriately for SilverStripe.

Next, we perform a bit of file mapping required for using the sake cli tool for when you’ve ssh’d into the virtual machine. The file path here should be similar to that of your local development environment. For me I have a Sites directory in my main user folder where I store all my development websites. Yours may differ so update /home/vagrant/<your-website-path> as appropriate. I've also added in a mapping specifically for Forge, but I'll cover this in a later article.

Finally and really only for the sake of demonstration I’ve added a default administrative user. It firstly checks to see if we’ve set these environment variables and then sets these parameters accordingly. I wouldn’t recommend doing this when deploying to production.

We aren’t making anything special we just want to get all this working together so that will pretty much be it for setting up SilverStripe.

CWP Specifics

If you are using the CWP from SilverStripe there are a few additional things you’ll want to configure. When you install a CWP bundle it adds an SSL redirect for the administration section which is not very helpful when developing without one. To turn the SSL redirect off you will need to add the following config to your mysite/_config/config.yml file.

CwpControllerExtension:
  ssl_redirection_force_domain: false
  ssl_redirection_enabled: false

Please note that this needs to be placed correctly inside any containing elements or you may get errors.

End

With that we now have an installed version of SilverStripe framework ready to be run via Homestead. In the next article we’ll get Homestead installed and configured to run our SilverStripe website.