Installing a development environment

How to get a development version of Rooftop up and running

❗️

Some technical knowledge required

You'll need some experience running virtual machines and PHP applications to get Rooftop CMS running locally. If you just want to try out Rooftop, get in touch with Ed and the team and we'll set up a demo account for you. No installation required!

1. Install Vagrant and Virtualbox (or another virtualisation tool)

We use Vagrant as a development virtual machine, running on Virtualbox. Download and install the latest versions of both of these for your operating system:

https://www.vagrantup.com/downloads.html
https://www.virtualbox.org/wiki/Downloads

2. Install VVV from the Rooftop CMS fork

VVV is a ready-built set of scripts for running PHP in a vagrant machine, from the folks at 10up and makes it dead easy to get set up. We have forked from VVV master to add some plugins: primarily Elasticsearch (not used yet) and Redis (used for queues, caching and etags). Periodically we merge the upstream master branch of VVV.

In the location you want to install the VVV virtual machine (inside which you'll add Rooftop CMS), run the following:

git clone https://github.com/rooftopcms/VVV.git
git submodule update --init --recursive

3. Clone Rooftop CMS into your VVV installation and edit the composer.json

Clone the Rooftop git repo inside the VVV one:

cd VVV/www
git clone https://github.com/rooftopcms/rooftop-cms.git
git submodule update --init --recursive

There are a couple of entries in the Composer file you'll need to remove because they're not open-sourced (yet). They don't affect the running of Rooftop for your site; they're just stuff we have in the project for our hosted version. There's work in progress to remove these and put them elsewhere.

Remove the line from VVV/www/rooftop-cms/public/composer.json which contains this:

"errorstudio/rooftop-hosted-hooks": "dev-qa"

4. Install the PHP packages locally

🚧

You'll need Composer installed locally

Composer is a package manager for PHP. You'll need to have it installed to run this command. Installation instructions are at https://getcomposer.org/download/ - for OSX it's easiest to use Homebrew: brew install composer should do it.

We've hit one or two issues getting VVV to install the composer packages on first run. To get around that, install them locally in the place VVV will access them:

composer install -d public/

4. Install vagrant hostsupdater and add subdomains

Rooftop is a Wordpress Multisite installation with subdomains. To develop locally, you need to configure Vagrant to update your hosts file with entries you need

vagrant plugin install vagrant-hostsupdater

Edit VVV/www/vvv-hosts to include the subdomain(s) to the sites you're developing locally.

5. Start the Vagrant machine and wait a while

You should be good to start the Vagrant machine. On first run it'll take ages to install everything - on a 10Mb connection with a fast machine it takes us about half an hour.

Run this from the rooftop-cms folder:

vagrant up

…and go and do something else for a while.

When it's done, it'll drop back to a command prompt and you should be able to access http://vvv.dev on your local machine.

Other things you might want to do

Install redis

Redis is used for etag caching and queues.

vagrant ssh
apt-get install redis-server

 Allow access to the MySQL database from your host machine

Sometimes it's useful to access your VM MySQL database from your local machine. To do this you need to grant the root user access from other machines:

From a console on your machine, inside the rooftop-cms project:

# ssh into the vagrant machine
vagrant ssh

#log into mysql - password is root
mysql -u root -p

# grant access
grant all on *.* to [email protected]'%' identified by 'root';
exit