About OctoberCMS

OctoberCMS is a relatively new open-source CMS based on the Laravel PHP framework. It has a number of attractive features – especially for developers – that can be explored by visiting this page.

In this tutorial we are going to install OctoberCMS on a VPS running Ubuntu 14.04. There are two ways you can install OctoberCMS: via the wizard and via the command line. We'll look at installing it using the second method.

Requirements

To install OctoberCMS, you'll need to meet a few system requirements. You'll need to have the LAMP stack (Linux, Apache, MySQP, PHP) installed, but Nginx and Lighttpd are also acceptable web servers. The PHP version needs to be 5.4+ with safe_mode restrictions disabled. Ubuntu 14.04 comes with a version of PHP 5.5 so you shouldn't have any problems with that.

You can read this great tutorial on how to install LAMP on Ubuntu 14.04 if you don't already have it set up.

Since we are using Apache as a webserver and October can make use of URL rewriting, we'll need to also make sure that Apache will in fact let it do that. If you haven't already done the following steps, you'll need to do them now.

Edit the virtual host file that is responsible for the folder where October will be installed (in our case, the default Apache document root: /var/www/html):

sudo nano /etc/apache2/sites-available/000-default.conf

Within the block contained by the starting:

<VirtualHost *:80>

Add the following block:

<Directory "/var/www/html">
    AllowOverride All
</Directory>

Next thing we need to do is enable mod_rewrite (again, if you don't already have it enabled). To check if it's already enabled, use the following command:

apache2ctl -M

If you see "rewrite_module" in the list, you are fine. If not, use the following command to enable the module:

a2enmod rewrite 

OctoberCMS also needs the cURL extension installed, so run the following command to do that:

sudo apt-get install curl php5-curl

Then you should restart the Apache server in order for the changes to take effect:

sudo service apache2 restart

Installation

For installing via the command line, we will need Composer. If you don't know how to work with it, or have not yet set it up, consult this tutorial that will get you going. Additionally, you'll need Git installed on the system; if you don't already, go ahead and run this command:

sudo apt-get install git-core

Now we can proceed with the installation. I said above that we will install October in the Apache web root (/var/www/html). So first, remove all the files in that folder. This is of course only if OctoberCMS is the only application you want in the web server's root folder. After you made sure you have the Composer.phar file in the /var/www folder and you navigate to it, run the following command:

php composer.phar create-project october/october html dev-master

What this will do is clone October from the repository and create a new project in the html/ folder.

Setup

The next thing we need to do is modify a few files. Open the app/config/app.php file and where you find this line:

'url' => 'http://yourwebsite.com'

Change the path to your own site. Let's say http://example.com (for later referencing in this tutorial).

Additionally, you should also modify this line:

'key' => 'UNIQUE_ENCRYPTION_KEY'

In order to pick an encryption key October will use.

Optionally, editing the app/config/cms.php file will allow you to change what the theme of the site is, which modules are loaded, and even customize the URI of the backend.

Database

Next, let's set up a database for October to use. I will guide you through some quick steps to set up your MySQL database, but there is a great tutorial here for more information.

The first thing you need to do is log in to mysql from your terminal (you can use PHPMyAdmin as well, but I will show you how to do it from the command line):

mysql -u username -ppassword

From there, run the following command to create a database called october:

create database october;

You can of course change its name to something else if you want. And that's pretty much it. Next, edit the app/config/database.php file and under the MySQL connection block specify your database credentials where appropriate. Finally, it's time to run the console command that will set up the October database:

php artisan october:up

Make sure you run this command from within the October root folder and if you get the following notice:

Mcrypt PHP extension required

Run the following command to install it:

sudo apt-get install php5-mcrypt

Then you'll need to enable this extension manually. Edit the php.ini file:

vi /etc/php5/apache2/php.ini

And inside at the following line:

extension=mcrypt.so

Then navigate to /etc/php5/apache2 and if you do not have a conf.d folder in there, create one:

sudo mkdir conf.d

And inside that folder create a file called mcrypt.ini with the following content in it:

extension=mcrypt.so

Then create a link between that file and the available PHP modules by running this command:

sudo ln -s /etc/php5/apache2/conf.d/mcrypt.ini /etc/php5/mods-available

And enable the module:

sudo php5enmod mcrypt

Followed by restarting Apache:

sudo service apache2 restart

Creating the conf.d folder is necessary only if it's not there already with the mcrypt.ini file (that you have to link to the available modules folder). If it's already there, skip the step and perform the linking directly.

And now you can run the php artisan october:up command again to set up the database which should be successful.

Permissions

In order for OctoberCMS to run, some folders need to be writable by the web server. So let's change their ownership to the www-data group which includes the www-data user (Apache) and make it so that this group can write in these folders.

sudo chown -R root:www-data app/storage
sudo chown -R root:www-data themes
sudo chown -R root:www-data uploads

sudo chmod -R 775 app/storage/
sudo chmod -R 775 themes
sudo chmod -R 775 uploads

Make sure you run these commands from within the OctoberCMS root folder and keep in mind that with this command we are making the owner of the files the root user. If you are using another user, just replace that username.

And that should be it. You can now navigate to http://example.com where you should see your brand new installation of OctoberCMS. To log in the backed at http://example.com/backend (by default), you can use the username admin and password admin.