To begin, you'll need a server running Ubuntu 16.04.
For this tutorial, we're going to assume that you're logged into your server as an unprivileged user with access to run commands as root using sudo.
Installing pre-requisites
The main things you need are Ruby (for actually running the app), Node.js (to help with javascript compilation) and MySQL (as the backend database). Let's start by getting them installed.
$ sudo apt update
$ sudo apt install mysql-server ruby ruby-dev nodejs git build-essential libmysqlclient-dev
$ sudo gem install bundler procodile
You'll be prompted to choose a password for your root MySQL user. Choose something secure and make a note of it, you'll be needing it shortly.
Creating your database
All the data that Staytus generates will be stored in your database. We'll go ahead and create a database and a user in your MySQL database. Get yourself a MySQL console and run the queries below. You'll be prompted to enter your root password that you entered in the previous password.
$ mysql -u root -p
CREATE DATABASE `staytus` CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER `staytus`@`127.0.0.1` IDENTIFIED BY 'choose-a-password';
GRANT ALL ON `staytus`.* TO `staytus`@`127.0.0.1`;
You can now exit the MySQL console. You shouldn't need that again for this tutorial.
Getting ready for Staytus
For security reasons, it isn't recommended to run your Staytus application as the root user. We'll now create a system user for Staytus to run as.
$ sudo useradd -r -d /opt/staytus -m -s /bin/bash staytus
This will create a user called staytus with a home directory in /opt/staytus. This is the directory that we will use for actually storing the application.
Downloading the application
Staytus is just distributed from its GitHub repository so it's trivial to download it straight onto your server.
$ sudo -u staytus git clone https://github.com/adamcooke/staytus /opt/staytus/staytus
Getting started
So we've got our system pre-reqs installed and we're ready to start getting Staytus running. There are a few steps we need to do first:
- We need to install all the RubyGems that Staytus depends upon
- We need to configure our database
- We need to compile all the CSS & Javascript that it is needed for the application
- We need to load the initial database schema in to the database
For the rest of this guide, we'll be working from the root of the application.
$ cd /opt/staytus/staytus
We'll start by installing all the Ruby dependencies the application requires. Run the command below to install everything that's required. This may take a few moments.
$ sudo -u staytus bundle install --deployment --without development:test
Next, we need to update the database configuration to point to the database we created earlier.
$ sudo -u staytus cp config/database.example.yml config/database.yml
$ sudo -u staytus nano -w config/database.yml
You need to add the following information to your new database.yml in the appropriate place under default.
- Hostname: localhost
- Username: staytus
- Password: the password you chose earlier
We're now going to compile the assets required for the application's stylesheets & javascript files. This keeps the application snappy.
$ sudo -u staytus bundle exec rake staytus:build
Finally, we just need to run the setup tool which will populate our database with our initial schema.
$ sudo -u staytus bundle exec rake staytus:install
Give it a test
Right... we're getting there now. It's time to run up the Staytus application and check everything is working as we'd expect.
$ sudo -u staytus procodile start --dev
This will run Staytus in the foreground so we can see everything that's happening. We'll be moving it to run in the background shortly.
Open up a web browser and point it to http://[yourIP]:8787. You'll be greeted by the installation wizard. Complete all of this and then come back here to finish off the rest of the installation.
When you've completed the wizard, press CTRL+C on your keyboard to stop it running.
Running in the background
Now you're satisfied everything is running as you'd hope. You can switch this over to run in the background.
$ sudo -u staytus procodile start
This will keep the processes running at all times. You can view the staytus by running procodile status.
Moving to port 80 using nginx
At the moment you need to access Staytus on port 8787 which isn't ideal. Next we'll install nginx and get everything running on port 80. You can start by installing nginx.
sudo service apache2 stop$ sudo apt install nginx
Once installed, we'll need to add some configuration. To save some time you can download an example nginxvhost file using the URL below.
sudo apt-get install curl
$ sudo curl -o /etc/nginx/sites-available/staytus https://share.adam.ac/files/2017/nginx.staytus.conf
$ sudo ln -fs /etc/nginx/sites-available/staytus /etc/nginx/sites-enabled/default
$ sudo systemctl restart nginx
You'll now be able to access your installation without adding the :8787 port suffix.
Note: if you have other sites installed on this server, you may not wish to change the defaultvhost above. In these cases, you will need to adjust your nginx configuration as appropriate.
Configuring outgoing e-mail
Staytus is able to send e-mails automatically. Configuring your own outgoing mail server can be a little tricky and is outside of the scope of this guide. Therefore, I recommend using AppMail to deliver e-mails from your status site. Here's how to configure that...
- Signup for an AppMail account
- Create a new mail server from your AppMail dashboard
- Add a domain for the domain that you wish to send messages from
- Create an SMTP credential. This will give you a key that can be used by Staytus to authenticate to the AppMail service.
Once you've configured AppMail, you can go ahead and add the appropriate configuration to your application. Open up your environment.yml and add the appropriate SMTP credentials.
$ sudo -u staytus nano -w /opt/staytus/staytus/config/environment.yml
STAYTUS_SMTP_HOSTNAME: smtp.appmail.io
STAYTUS_SMTP_USERNAME: [the username provided by appmail]
STAYTUS_SMTP_PASSWORD: [the key provided by appmail]
Of course, you don't have to use AppMail, you can use any SMTP compatible mail service.
If you make changes to your database & environment configuration files you will need to restart Staytus. You can do this using sudo -u staytus procodile restart from the /opt/staytus/staytus directory.
Upgrading
Upgrading your installation is quite a simple task. To upgrade, just follow these steps.
$ cd /opt/staytus/staytus
$ sudo -u staytus procodile stop -s --wait
$ sudo -u staytus git pull origin master
$ sudo -u staytus bundle
$ sudo -u staytus bundle exec rake staytus:build staytus:upgrade
$ sudo -u staytus procodile start
Next steps
You're all done now. There are a few things you can look at next though which are outside the scope of this tutorial:
- Add some DNS
- Adding SSL to your nginx configuration
After server reboot you need to run following command to start this application again:
root@noc-status:~# cd /opt/staytus/staytus
root@noc-status:/opt/staytus/staytus# sudo -u root procodile start
