Installing and Setting up Canvas Server
High Level Installation Steps
The following are general application installation steps for Linux. For other environments, the general requirements will be the same - let us know if you need help by emailing support@gridfabric.zendesk.com.
Install Prerequisites
During the bundle install step, native binaries are built for several packages which requires build tools. Ensure the following are installed in your environment:
- GCC
- G++
- Make
- CMake
- nodejs (to build web assets)
Note: Starting with version 3.x, we are introducing binary releases. These will include jruby and pre-built gems which reduce the installation dependencies, making installs and upgrades much easier. Releases are OS specific, so let us know if you need a release for an OS that isn't currently covered.
If installing a binary release, you do not need these pre-requisites and may also skip the jruby installation listed below.
Create an application user
sudo adduser appuser --disabled-login
Let all of the options be default. The application will run as this user and the application will be installed under this user's home directory.
Install RVM
RVM is used to install different versions of ruby and create gemsets. RVM is most useful on a development machine where multiple rails projects with different versions of ruby and gemsets are in play. Servers installations can use RVM to make installing ruby easier, but may also download and install ruby directly from jruby.org https://www.jruby.org/.
Skip this step if manual ruby installation will be used.
Follow the instructions here to install RVM: https://github.com/rvm/ubuntu_rvm
Add the apuser to the rvm group:
sudo usermod -a -G rvm appuser
Note: the instructions to install RVM on Ubuntu 16.04 don’t seem to work quite right. You may notice errors or warnings when running certain commands. If this happens, use google to troubleshoot the issue and let us know if you are unable to resolve them.
Install Java version 8 to 11 + dependencies
OpenJDK from the Ubuntu repositories works fine. Java from Oracle requires a license now but works as well. Here are two options for installing java:
- https://adoptopenjdk.net/installation.html
- https://www.digitalocean.com/community/tutorials/how-to-install-java-with-apt-on-ubuntu-18-04
Make sure to install a version of java between 8 and 11. It may work up to version 14, but jruby seems to be mostly focused on java through 11 so we recommend staying with that. Since OpenJDK 8 is now supported through 2026 (https://adoptopenjdk.net/support.html) and Java has jaxb support built in, Java8 is recommended.
Once installed, run java -version in the terminal to ensure the correct version of java is installed. If multiple versions of java are installed, set the JAVA_HOME environment variable to use a particular version by adding the following line to the end of the appuser .bashrc file:
export JAVA_HOME=<version>
Install jaxb deps (only if java > 8 is installed)
Java versions > 8 no longer include jaxb for processing XML and require external jars. Those dependencies are available in the canvas-jar download from the same location canvas was downloaded from. Unzip the canvas-jar file to a directory called target in the root install directory.
Another option is to install the dependencies with maven. From the root install directory, run the following:
mvn install dependency:copy-dependencies
(Maven must be installed before running this command)
Install haveged (randomization)
On Ubuntu 16, 18 and 20, running 9.2.x versions of jruby, if the server is mostly idle, the random device runs out of entropy which can cause long delays. One place this issue manifests is during startup. On a new Ubuntu server, we found that restarting the app 2 or 3 times resulted in start up times over 2 minutes. Redhat 8 did not have this issue.
If the service has startup times greater than 30s or so, install the haveged daemon: https://linux.die.net/man/8/haveged.
Install and configure postgres
Configure postgres with a default timezone of UTC by modifying the postgresql.conf file.
Create a user for the application with rights to create a database. By default, the user will have a username and password of canvas - you can change this in the database config file covered in setup config files.
Install the program code
Copy the source code to the app user’s home directory. Make sure the appuser is the owner of the directory and everything underneath.
Install Jruby
You may skip this step if installing a binary release
Once jruby installed, the executables jruby, ruby, and gem should be on appuser’s path. Follow one of the two suggestions below.
Reference the .ruby-version file in the source code to determine the version of jruby you should use for your version of Canvas.
Option A: Install jruby w/ RVM
rvm install jruby-<version>
Errors regarding openssl such as what’s shown below can be ignored:
Error running 'gemset_import_list jruby-openssl jruby-launcher gem-wrappers rubygems-bundler rake rvm', please read /usr/share/rvm/log/1520352392_jruby-1.7.10/gemsets.import.global.log
After installing jruby, cd out of the application directory and cd back in.
cd ../
cd canvas-oadr-vtn
A generating wrappers message should appear - the command will take a few moments to complete.
Option B: Install jruby manually
Download the correct jruby version from here: https://repo1.maven.org/maven2/org/jruby/jruby-dist/
Unzip this file in the bin directory under the appusers home directory. Add jruby bin directory to the user's path (append to .bashrc)
Set the path in the .bashrc file.
export PATH="$PATH:$HOME/bin/jruby/bin/"
Run commands as appuser
Switch to the user appuser and change to the application root directory - the remaining commands are run as the appuser.
sudo su - appuser
cd canvas-oadr-vtn
Update default rails environment to be production
Add the following line to the end of the appuser .bashrc file
export RAILS_ENV=production
Exit and log back in as appuser after making this change.
Install the application gems
gem install bundler -v 2.1.4
bundle install
Setup config files
The following config files have sample config files with the same name except .sample is appended. Make a copy of the sample config file without the .sample extension.
config/database.yml
Configure the database and database user in this file.
config/secrets.yml
Run: rake secret to generate a random key. Copy the output into secrets.yml. The sample config file uses an environment variable, but feel free to overwrite the variable with the key text since the file isn’t in source control.
Note: you may need to prepend your rails commands with bundle exec for it to run without errors. For example, bundle exec rake secret.
Setup the database tables
rake db:setup
There are a number of different rake db:* commands to help with setting up the database. An initial database setup should not use the rake db:migrate - that command for upgrades only.
The rake db:* commands, can be used to drop the database, create the database, load the schema, and load the seed data. The rake db:setup command creates the database, loads the schema, and then loads the seed data. The rake db:reset command will first drop the database and then run setup.
If the rails environment is set to production (which it should be when following these commands), running commands that destroy data such as rake db:drop or reset will result in an error. If you want to continue with the destructive command, follow the instructions from the error message.
Add downloads directory
Create a directory called downloads in the application root. Exported interval data files are created in this directory.
Setup the event service
Copy config/initializers/service_starter.rb.example to config/initializers/service_starter.rb.
This service handles moving events through the different states (far, near, active, complete).
Setup assets
This command can take 15 minutes or more to complete and consumes a fair amount of memory!
JAVA_OPTS="-Xmx2048M" rake assets:precompile
Launch and test puma to run the app
This command will launch puma.
Adjust the amount of memory available to puma by preceding the command with:
JAVA_OPTS=-Xmx1024m puma -C config/puma.rb
You can make puma listen on all interfaces by changing the IP in puma.rb from 127.0.0.1 to 0.0.0.0 (line 16 of puma.rb in the config directory) or run use the -b switch when starting puma:
puma -C config/puma.rb -b tcp://0.0.0.0:8080
Puma will take 30 seconds or so to startup and will run in the foreground. Once puma is running, connect to port 8080 with a web browser and log in with the default username admin and password testing.
Hit ctrl-c to stop the app. The recommended method for running the app is through a service file which is covered next.
Install the service file
The canvas.service file (in the source code under the documentation directory) can be used to start and stop the app, and auto start the app on server reboot. Follow the instructions at the top of the file. Paths in the file need to be adjusted based on the install location of the app. The PATH environment variable may need to be set in the service file.
Installation Notes
Ubuntu
Install postgres: sudo apt install postgresql postgresql-contrib
Switch to the posgres user and create the postgres application user:
sudo su postgres
psql # starts the psql command prompt
create user <username> with createdb password ‘<password>’;
\q # to quit the shell
Install java: https://www.digitalocean.com/community/tutorials/how-to-install-java-with-apt-on-ubuntu-18-04
Alternative java (OpenJDK) download: https://adoptopenjdk.net/
Install RVM: https://github.com/rvm/ubuntu_rvm
Redhat
Install postgres: https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-centos-8