Installing Cachet on Ubuntu 14.04

I recently came across an amazing piece of open-source software called Cachet for dashboarding system statuses! James Brooks at Alt-Three has done a really great job with development but the documentation is still a bit lacking for those less familiar with Linux. Therefore I've put together a start-to-finish guide for getting Cachet up and running in 20 minutes! Or you can just skip to the end of the post to download a ready-to-go VMware VMDK :)

Installing Ubuntu

If you're reading this article, I'm going to assume you at least know how to download Ubuntu and get it installed on a machine/VM. I downloaded Ubuntu 14.04.2 LTS (64-bit) and got it installed in VMware Workstation 8.

Before we get to installing Cachet, let's make our Ubuntu install a bit more secure. This article does a really good job of summarizing some hardening techniques. We're not going to go too crazy but let's get the bare necessities.

First, elevate your privileges to root access:

sudo /bin/bash

Now we can continue running commands without having to use the sudo command.

apt-get update

apt-get install ssh ufw

This installs OpenSSH for SSH access and UFW for your firewall.

Configure SSH

By default, SSH runs on port 22. Let's change to this to an atypical port, like 5901, and disable root login.

nano /etc/ssh/sshd_config

Find and modify these two lines in the config file to match below and save:
Port 5901

PermitRootLogin no

Then restart the SSH service:

service ssh restart

Configure Firewall

UFW provides a very simple way of creating firewall rules. For Cachet, the only port we need open is port 80, along with port 5901 for our SSH traffic.

ufw allow http

ufw allow 5901
ufw enable

If you want to view your rule list, you can show the firewall status by running:

ufw status

Installing Cachet Dependencies

The first thing we need to do is get all the dependencies downloaded for Cachet. These can be found on the prerequisites page of the official documentation, but those don't necessarily correspond to the apt-get packages.

Because we're on Ubuntu 14.04 LTS, we need to add a repository to get PHP 5.6:

add-apt-repository ppa:ondrej/php5-5.6

apt-get update

Now to install the dependencies:

apt-get install git supervisor apache2 mysql-server mysql-client

You'll get prompted to set up a root password for the mysql database. Choose a password and let the install finish. Then install the next set of dependencies:

apt-get install php5 php-pear php5-mysql php5-mcrypt php5-apcu php5-cli php-db php5-intl php5-readline

These should have installed without any issues. There is one final package that is needed, however it isn't available in the apt-get repositories. We will need to download Composer off the official website. Luckily this is two simple commands:

curl -sS | php

mv composer.phar /usr/local/bin/composer

Whew...that was a lot of work! It takes a ton of packages to lay the groundwork - but now comes the fun part!

Installing Cachet

First, we need a directory to put our Cachet files in. I always use /var/www because it's easy to remember and typically where Apache looks for things. Let's navigate to the directory and download the latest version of Cachet using git:

cd /var/www

git clone
cd Cachet
git tag -l
git checkout v1.2.0

In these steps, we cloned the git repository and downloaded the latest version of Cachet (v1.2.0 at time of writing).

Configure the Database

We need to configure a username and password in the mysql database for Cachet to use to store data. You can access the mysql command line by:

mysql -u root -p

Then enter the following one line at a time:


GRANT ALL PRIVILEGES ON cachet.* TO 'cachet'@'localhost' IDENTIFIED BY 'your password';

Configure the .env File

Cachet comes with a sample .env.example file that we need to fill out with our information and save as .env

Let's open up nano and edit the example file. I'll fill in my values as we go, with comments after each line:

APP_DEBUG=false #set this at false if on a production server
APP_URL= #fill in your cachet site url
APP_KEY=SomeRandomString #this will get filled in later on

DB_PASSWORD=<your password> #password for mysql cachet user


MAIL_DRIVER=smtp #fill in your mailserver info here if you want email alerts


Hit Ctrl+O to save in nano and remember to save as ".env" - don't overwrite the .env.example

Now that we have our environment variable set, it's time to "compose" our site. Make sure we're in our Cachet directory (/var/www/Cachet) and run:

composer install --no-dev -o

It should download and install several files before completing successfully.

One big thing: if you run this once and it fails and you try to run again, you may hit the github API limit. If this happens, you'll need to register a free account on Github and create a personal access token. It's not a big deal but was something that tripped me up during my many installs.

Moving on, it's now time to set up the initial database:

php artisan migrate

If you get an error, this means your database configuration is incorrect. Double check the values in your .env file.

And finally, we will generate a key. This key will automatically be added to your .env file. Don't change the key after it's been created or your data will be lost.

php artisan key:generate

Setting Up Apache

Navigate to /etc/apache2/sites-enabled. Open 000-default.conf and delete all the contents (holding down Ctrl+K works well) and replace with the text below (minus the line numbers):

<VirtualHost *:80>
        ServerName <server dns name>
        ServerAlias <server dns name>
        ServerAdmin webmaster@localhost
        DocumentRoot /var/www/Cachet/public

        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
<Directory "/var/www/Cachet/public">
        Require all granted
        Options Indexes FollowSymLinks
        AllowOverride All
        Order allow,deny
        Allow from all

Be sure to replace the ServerName and ServerAlias with your server's DNS name! Once you've gotten this in the .conf file, save and exit. Finally, we need to enable mod_rewrite in Apache by:

a2enmod rewrite

service apache2 restart

Fixing Things Before They Break

At this point, you might be tempted to open up a browser and navigate to your new Cachet site - but don't do it yet!

During my initial few installs, I ran into a couple issues that caused me major grief. Luckily the great folks in the Cachet github community were able to guide me to success...and now to pass that knowledge on to you!

The first issue I ran into was the initial setup page was blank. I couldn't go anywhere or get any part of the site to load. It turns out my file ownership and permissions were all messed up. Because we ran all these steps as the "root" user, all the files technically belong to the protected root account. We need to set the file ownership to www-data, which is the user that Apache automatically sets up and runs as. You can set the permissions by running:

chown -R www-data:www-data /var/www/Cachet

I also had to set the storage folder in the Cachet folder to be world-writable (source):

chmod -R guo+w /var/www/Cachet/storage/

The final issue I had was once I got to the end of the initial setup page, the dashboard wouldn't load! It turned out to be an issue with github rate limiting and some emoji module within Cachet. The fix was to run the following:

mkdir /home/www-data

mkdir /home/www-data/.composer
nano /home/www-data/.composer/auth.json

In the auth.json file, put in the following:

    "http-basic": {},
    "github-oauth": {
        "": "__TOKEN__"}

Replace __TOKEN__ with your github personal access token. If you got a personal access token back up above when running composer, you'll put that same token here. Otherwise you'll need to go generate one.

Once again, let's make sure the www-data user has ownership of its home folder:

chown -R www-data:www-data /home/www-data

Since we've made so many changes, let's go ahead and clear our artisan cache. We shouldn't have to do this often but it's a good first step to troubleshoot if you run into any issues.

cd /var/www/Cachet

php artisan config:clear

Navigate to your site

Here comes the time you've been waiting for. Cross your fingers and navigate to your Cachet site in a web browser! If everything works correctly, you should see the initial setup screen!

Configuring Cachet

Are we done yet? Well no, not quite yet. Just a few finishing touches - we're so close!

Click Next and work your way though the Cachet setup pages. Unless you know you need to change something, keep the Cache and Session drivers the same on the environment setup page, fill in your site info on the status page setup, and set up an initial admin account. Once you complete the initial setup, you'll be taken to the login page where you will login with your initial admin account email address and password.

At this point, you have a working Cachet environment to play around in. The only thing left to optionally configure is emailing.

Configure Email Notifications

Remember back in our .env file we had some mail server parameters? I'm going to assume you filled those in. If not, go back and do so.

Now in our Cachet admin panel, go to Settings and check the "Allow people to signup to email notifications" checkbox. This will add a subscribe button to the top of the Cachet home page (don't forget to clear the artisan cache!). Users can subscribe and receive email alerts when something goes down.

Cachet already has pretty good documentation on setting up subscribers but I'll go over it here as well.

There are two methods for Cachet to process email notifications. There's sync mode, where the emails are sent immediately but at a high cost to website performance during processing, or in the database queue, which is much less demanding on resources but a little trickier to configure. For this article, I'm going with the database queue. If you have a large enough network to need a system dashboard, you probably have a lot of users :)

This method is already used by default. However while these events are being added to the database queue, nothing is processing them. We need to setup a process that will run in the background at all times and listen for events to come up (more info about queues). Luckily we installed the package needed earlier: supervisor.

Thanks to a great tutorial over at DigitalOcean, we can have this up and running in no time.

First, we need to create a file in the supervisor conf.d directory to run the artisan queue listen command:

cd /etc/supervisor/conf.d

nano phpartisan.conf

Place the following in the phpartisan.conf file:

command=php /var/www/Cachet/artisan queue:listen

On startup, supervisor will start the artisan queue listener and will restart it if it stops working at any point. Now to get supervisor to read our new conf file:

supervisorctl reread

supervisorctl update

The output of that last command should show the phpartisan job running.

All Done!

You did it! Hopefully you are successfully up and running with a nearly production-ready environment.

In the unfortunate case things did not work out or you simply want to try Cachet without an upfront time cost, I have put together a virtual machine made in VMware Workstation 8 for you to try out.

VM Quick Setup

Step 1: Download VM from Dropbox 336MB (7z archive)

Step 2: Extract, import into VMware, and start VM

Step 3: Modify /var/www/Cachet/.env by setting your APP_URL and mail server settings

Step 4: Modify /home/www-data/.composer/auth.json and insert your github personal access token

Step 5: Flush the artisan cache by running php artisan config:clear from the /var/www/Cachet directory

Step 6: You should be good to go! Login credentials are below:

SSH port: 5901
Ubuntu login: cachet / c@ch3t
MySQL root: root / toor
MySQL user: cachet / c@ch3t
Cachet: / demo

Run into any issues? Feel free to leave me a message in the comments below!

Posted on
Tagged in Cachet , Ubuntu
chris reinking

comments powered by Disqus