Why Multi-site?

LocomotiveCMS has one killer feature for me which makes it beat out RefineryCMS in my books. That feature is the ability to do multi-site. I host websites for many people and have felt the pain of configuring sites by hand for each one of them, plus the extra sever load of running a separate process / instance for each website.

A good multi-site CMS will take care of that pain pretty handily – it means that I can run one instance of the CMS with mulitiple processes. So, my server costs go down and I can ensure that all the sites respond quickly – I don’t have to worry about their instances spinning down and having to spin up again if they are not visited regularly.

Setting it up

LocomotiveCMS doesn’t have great documentation, but their code seems to be really solid. It required me to do a bit of reading between the lines to sort it out. Actually, it was more reading the lines of code but that’s a separate point.

Step 1 – config/initializers

Once you have locomotive running locally (see the installation guide) then you need to modify the initializer to tell it to operate in multi-site mode. The comments will tell you what to do, but this is what I did.

  config.multi_sites do |multi_sites|
    multi_sites.domain = 'local.i'
    multi_sites.reserved_subdomains = %w(www email blog webmail mail support help site sites)
  end

This is for a local environment. The reason that I used local.i was because I want to be able to test this on my development machine. I also removed admin from the list of reserved subdomains.

Step 2 – set up your /etc/hosts (Mac)

Now that the initializer is set, you need to configure your hosts file so that you can access your local server via subdomains using the built-in webserver (e.g. WEBrick)

This is what I added to my hosts file.

 127.0.0.1 local.i
 127.0.0.1 admin.local.i
 127.0.0.1 sub1.local.i

Step 3 – fire up the server and configure

This next step took me a bit to sort out because I had already set up my locomotive config weeks ago. I was trying to switch things into multi-site mode but it wasn’t working. The easiest way for me to do it was to wipe out the db that I had created and visit the site again. If there is no db, it will prompt you to set up a new one from scratch. So, if you already have a locomotive db and you don’t care about the contents, wipe it out and start fresh. if you do care about the contents: back it up, rename it, whatever. I’m not responsible for you wiping out your valued data

Here are the two steps it takes you through:
  1. create an admin user
  2. set up a default site

For the default site, I used name = Awesome Hosting and subdomain = admin. The subdomain needs to match what you put into your /etc/hosts file. Make sure you upload the default template

Step 4 – enjoy!

Now if you visit admin.local.i:3000 you will see your admin site. To administer it, go to admin.local.i:3000/admin and login with your credentials. From there you can visit settings -> my account and add new sites with the little (+ new site) button.

Remarks..

There are some oddities here that I’m not 100% comfortable with.

  1. Why can’t I create the default site with no subdomain? e.g. just local.i for the admin site rather than admin.local.i ?
  2. Why is adding sites under the obscure location of settings -> my account? It should be somewhere like settings -> sites

One thing I just noticed as I finish this write-up is that you can click on the little link it the top menu switch to another site and you can switch between sites and add new sites from there. That’s cool.