Deploying Web Simula in Production
Web Simula is a Ruby on Rails application that uses:
- PostgreSQL as its database;
- Redis for managing websocket communication; and
- Node.js for precompiling the client-side JavaScript code through webpacker.
I've started off deploying Web Simila on Heroku while I was developing it as my undergraduate thesis because it allowed me to quickly deploy a live version to test with real users and validate my work. After finishing my thesis I've switched it to Digital Ocean using Dokku to reduce server costs.
In this guide I'll describe how to deploy it in both platforms.
If you do not have an account on Heroku, sign up in their website: Cloud Application Platform | Heroku.
Also, if you don't have the Heroku CLI, you'll need to install it in your computer. Follow their guide: Heroku CLI - Download and Install. Once you install the Heroku CLI, run heroku login and enter the credentials (e-mail and password) of the account you've created on the Heroku website.
Now, make sure you have a clone of this repository in your computer. To do that, you'll need to have Git installed, then run the following command in your terminal:
git clone https://github.com/guisehn/websimula.git && cd websimula
It will download the project in a folder called websimula and then open it in your terminal.
Create your Heroku application by running heroku create inside the repository folder (websimula). This will make Heroku create an empty web application for you with a random name and add a remote to your local Git repository. It will print something like this to your terminal:
$ heroku create
Creating app... done, ⬢ dry-sands-74611
https://dry-sands-74611.herokuapp.com/ | https://git.heroku.com/dry-sands-74611.git
We'll now install the Postgres add-on and associate it with your application. Heroku offers different Postgres plans based on your usage. In this case I'll use the Hobby tier which is free and has a 10,000 row limit. You can learn about the other plans here: Choosing the Right Heroku Postgres Plan
To create the database using the hobby plan, run:
heroku addons:create heroku-postgresql:hobby-dev
It should output something like:
$ heroku addons:create heroku-postgresql:hobby-dev
Creating heroku-postgresql:hobby-dev on ⬢ dry-sands-74611... free
Database has been created and is available
! This database is empty. If upgrading, you can transfer
! data from another database with pg:copy
Created postgresql-asymmetrical-44106 as DATABASE_URL
Use heroku addons:docs heroku-postgresql to view documentation
Now let's install the Redis add-on. It also has a list of plans. In this case I'm also going with the free Hobby Dev plan by running:
heroku addons:create heroku-redis:hobby-dev
It should output something like:
$ heroku addons:create heroku-redis:hobby-dev
Creating heroku-redis:hobby-dev on ⬢ dry-sands-74611... free
Your add-on should be available in a few minutes.
! WARNING: Data stored in hobby plans on Heroku Redis are not persisted.
redis-adjacent-24027 is being created in the background. The app will restart when complete...
Use heroku addons:info redis-adjacent-24027 to check creation progress
Use heroku addons:docs heroku-redis to view documentation
The next step is to set the buildpacks that will be used by Heroku to build the web application everytime we push a commit to it. Run the following commands:
heroku buildpacks:clear
heroku buildpacks:set heroku/nodejs
heroku buildpacks:add heroku/ruby
Heroku will output something like:
$ heroku buildpacks:clear
Buildpacks cleared. Next release on dry-sands-74611 will detect buildpack normally.
$ heroku buildpacks:set heroku/nodejs
Buildpack set. Next release on dry-sands-74611 will use heroku/nodejs.
Run git push heroku master to create a new release using this buildpack.
$ heroku buildpacks:add heroku/ruby
Buildpack added. Next release on dry-sands-74611 will use:
1. heroku/nodejs
2. heroku/ruby
Run git push heroku master to create a new release using these buildpacks.
Now, let's push our code to Heroku. To do that, run:
git push heroku master
You'll run this same command everytime you want to deploy a new version of the application.
It should take a few minutes to finish. If everything goes well you should see something like this in the end:
remote: Verifying deploy.... done.
To https://git.heroku.com/dry-sands-74611.git
* [new branch] master -> master
The last step is to initialize the database. Run:
heroku run rails db:schema:load
After the command is done Web Simula should be live! Run heroku open to launch it in your browser.
To set up e-mail and error tracking, jump to the sections 2. Setting up e-mail sending and 3. Setting up error tracking
In this guide I'll be showing how to install Web Simula in a VPS with Ubuntu Server on Digital Ocean. It should work on any similar hosting provider though.
The Droplet (VPS) used for this guide is:
- OS: Ubuntu Server 16.04.3 x64
- Specs: 512 MB RAM / 1 CPU / 20 GB SSD Disk ($5/mo plan)
Start off by logging in your VPS using the command ssh root@[ip address] in your terminal.
Since I'm using a machine with only 512 MB of RAM, the first thing I'm going to do is create a swap file so that we don't run out of memory while installing all the stuff. This is not required if your VPS has over 1 GB of RAM.
Follow this tutorial to create a swap file: How To Add Swap on Ubuntu 14.04
Dokku is described as "Docker powered mini-Heroku. The smallest PaaS implementation you've ever seen.". It basically provides an interface very similar to Heroku to install and manage a web application (in this case, Web Simula) in your server.
To install it, follow the instructions of their repository: Dokku - Installation.
In my case, I ran:
cd ~ && mkdir dokku_setup && cd dokku_setup
wget https://raw.githubusercontent.com/dokku/dokku/v0.11.2/bootstrap.sh
sudo DOKKU_TAG=v0.11.2 bash bootstrap.sh
Check if you have a SSH public key in your local computer. You'll know you have one if the file ~/.ssh/id_rsa.pub exists in your computer.
If you don't have one, you'll have to generate it. Follow this guide from Git to learn how to do that: Git on the Server - Generating Your SSH Public Key
Once you have your public key, run cat ~/.ssh/id_rsa.pub in your terminal and copy the value, which should be something like ssh-rsa [a very long string] [email protected]
Now, open the IP address of your server in your browser (http://[ip address]/). Paste your public key (including the ssh-rsa prefix and the name of your machine) into the Public Key field.
If everything is ok it will redirect you to the Dokku documentation after you submit.
On your VPS, run:
dokku apps:create websimula
sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git
dokku postgres:create websimula-database
dokku postgres:link websimula-database websimula
sudo dokku plugin:install https://github.com/dokku/dokku-redis.git redis
dokku redis:create websimula-redis
dokku redis:link websimula-redis websimula
From now on, when you see [app_name] in the next commands that use Dokku, replace it with websimula (or with the name that you have used on the dokku apps:create command).
This will create an app called websimula, a Postgres database service called websimula-database and a Redis service called websimula-redis. It'll then link both services to your app.
First, make sure you have a clone of this repository in your local computer. To do that, you'll need to have Git installed, then run the following command in your terminal:
git clone https://github.com/guisehn/websimula.git && cd websimula
It will download the project in a folder called websimula and then open it in your terminal.
Once you're inside the project folder, run:
git remote add dokku dokku@[ip_address]:[app_name]
...where [ip_address] is the IP address of your server and [app_name] is the name of your Dokku application (websimula in our example). This will create a Git remote to our VPS server where you'll push the code everytime you want to deploy a new version of the application.
Then, run git push dokku master to push the web application code to the server.
When the command finishes successfully, run the following command, now inside your VPS:
dokku run [app_name] rails db:schema:load
This will generate the database structure for the application.
Run the following commands, replacing [app_name] with your app name (websimula in this example):
dokku config:set [app_name] RAILS_ENV=production
dokku config:set [app_name] RAILS_LOG_TO_STDOUT=enabled
dokku config:set [app_name] RAILS_SERVE_STATIC_FILES=enabled
dokku config:set [app_name] APP_HOST_URL=`dokku url [app_name]`
dokku config:set [app_name] WEBSIMULA_AUTO_MIGRATIONS=true
Now, let's generate a secret token for the Rails application. This is used by the framework to verify the integrity of signed cookies sent by the users. First, generate a secret token by running:
dokku run [app_name] rake secret
It should output something like:
$ dokku run websimula rake secret
ec5ecf1eaaf385d23eb67c2097e3086daa8901e1d12dcb7db6e977badcbc6509335182d6740b45328f3746321f403676bc1ab8e4a53951d54204202a81934d76
Execute the following command, replacing [generated_secret] with the value generated above (e.g. ec5ecf...d76).
dokku config:set [app_name] SECRET_KEY_BASE=[generated_secret]
Important: do NOT use the same value of this example or people will be able to hack your application!
After the environment variables are set Web Simula should be ready to use!
Run dokku url [app_name] to get the URL that you should enter in your browser to access the app.
To set up e-mail and error tracking, jump to the sections 2. Setting up e-mail sending and 3. Setting up error tracking
Web Simula uses Postmark for sending transactional e-mails such as project invites, password resets, etc.
Create an account and set it up with your domain, then go to Account → API Tokens and generate a new token, or copy the existing token (for example 8aa1b682-f606-49a8-87ca-6087126654e1).
Now, create an environment variable called POSTMARK_KEY with this value.
- If you're using Heroku, run:
heroku config:set POSTMARK_KEY=[postmark_key](replace the values) - If you're using Dokku on your own server, run:
dokku config:set [app_name] POSTMARK_KEY=[postmark_key](replace the values)
Also, create an environment variable called EMAIL_FROM_ADDRESS with the e-mail address that will appear as the sender of the emails.
- If you're using Heroku, run:
heroku config:set EMAIL_FROM_ADDRESS=[email_address](replace the values) - If you're using Dokku on your own server, run:
dokku config:set [app_name] EMAIL_FROM_ADDRESS=[email_address](replace the values)
Web Simula uses Sentry for error tracking on the back-end and front-end. It will log and report to you when runtime errors occur in the server and also when JavaScript errors happen on the browser of someone accessing the website.
To set it up, first sign up on Sentry through their website with your email and password. When setting up the project, select Ruby on Rails as the language/framework.
When asked to configure your application, ignore the instructions and click on "All done!"
Now click on the Project settings button.
Click on Client Keys (DSN).
Copy the values of the DSN and DSN (Public) keys on the page that will open, then set the SENTRY_SERVER_URL env var to the DSN value, and SENTRY_CLIENT_URL to the DSN (Public) value.
- If you're using Heroku, run the following commands replacing the values:
heroku config:set SENTRY_SERVER_URL=[dsn]
heroku config:set SENTRY_CLIENT_URL=[dsn_public]
- If you're using Dokku on your own server, run the following commands replacing the values:
dokku config:set [app_name] SENTRY_SERVER_URL=[dsn]
dokku config:set [app_name] SENTRY_CLIENT_URL=[dsn_public]