Disponible en Español · In this tutorial
Canvas by Instructure is the most popular LMS in U.S. Higher Education today. It has excelled at grabbing the upper income tranche of the market. But even if you do not belong at the American top, you can still find out what all the fuss is about.
The following guide will show you how you can set up the Canvas LMS for free on your server.
Canvas LMS: Free as in an AGPLv3 puppy
Technically speaking, the Canvas LMS software is Open Source. Parts of it anyway. The AGPLv3 license it is under allows users to collaborate in software hosted on a cloud. Users of AGPLv3 licensed software must make any work based on it public and free. You cannot sell it, but you can sell products or offer services supported by the software. So it’s perfectly fine to provide services from say, the cloud, using free software with or without modifications, and never letting users download it.
Instructure does not release 100% of Canvas code, so you might not get the exact same experience as in signing on as a customer or trying out their cloud demo.
The AGPLv3 seeks to close a loophole found in the otherwise identical GPL license. It enables companies to take advantage of free software hosted on a server, and use it for paid services. Many argue that without this loophole some (if not all) the tech giants would not be roaming today. You can “FOSS” anything, from Apache‘s server management suite, to OpenSSL security certificates. Think of it as a free headstart for startups everywhere. Free, of course, to those in the best position to exploit them as well, big tech included.
It is clear that the decision to offer free, open source software is strategic. Many argue Instructure’s decision to make Canvas open was made at a time the company needed to convince the public about the quality and transparency of their code. Larger companies, either at their onset (RedHat) or down the road (Microsoft) find value in symbiotic relationships with the open source community. Moodle, the largest open source LMS, started from an ideological basis in support for free education, but recent initiatives and responses seem to reflect doubt about the commercial acuity of limitless commitment to open source at the internal level.
In short, you can set up your own Canvas LMS on your own server. You can do it for non-commercial as well as commercial purposes. And you should always credit the original license owner. If you want to contribute to Canvas code, you must comply with a Contributor License Agreement first.
Before you start: Asset inventory checklist
Make sure you have all the ingredients before you get started on setting up your own Canvas LMS.
Let’s begin with some helpful tools and associated skills:
- Apache HTTP Server
- The Ruby programing language. (The current stable version is 3.0.0)
- And the Ruby on Rails framework
- Linux. Canvas official tutorial is built in Ubuntu, tested for the 14 and 16 LTS versions.
- Optional, but highly encouraged:
- Version Control Software: Git and GitHub
- Database: PostgreSQL (Recommended) or SQLite
- Web server application: Passenger and the library for Apache
- Server virtualization: Docker or a Virtual Machine, are standard practice for developer of server-side applications.
- Cache management: Redis (latest, recommended) or Memcache (some functionality not supported)
As for the app and physical resources:
- The latest version of Canvas LMS. You can get it using GitHub (instructions here) or downloading and extracting the files in a compressed package: TARBALL (for Linux or Unix systems) or ZIP (everyone)
- A server running Linux. The latest Debian or Ubuntu Server distributions are recommended. If you have a server running Windows or a different system, you will need to set up a Virtual Machine
- Ruby on Rails. In addition, other dependencies are listed throughout the guide, but they seem fairly easy to install. They include Ruby Gems and Bundler
- PostgreSQL database engine. In principle an instance of the vastly more popular, open source MySQL engine should work, but in 2014 Instructure dropped support arguing the move to Rails 3. Howeverm there is nothing preventing Rails 3 from working with a MySQL databate. In fact, here is a 2013 guide about how to do it.
- An outgoing SMTP email server service.
- An SSL certificate.
The ‘quick start’ and the ‘production’ Canvas LMS guides
If you want to just check Canvas out and play around, Instructure offers many ways to get it done. They are, in order of simplicity:
- Canvas Cloud for Teachers. A freemium, cloud-based site for teachers, where you don’t have to set up anything nor touch any code. It also lets you export your work into a production Canvas site.
- Use Docker to launch an “Automated Setup.” Place this SH file on your virtual environment and run it to do all the work for you. Learn more.
- Manual setup. A more hands-on approach, but where you are told how to customized everything, and includes some sample files to get started. It is significantly limited and will not work as a production LMS.
The production guide is a more exhaustive walk-through, but one that can be difficult navigate thanks to incomplete information, implicit assumptions and disorganization.
Setting up a production Canvas LMS
Server configuration selection
One of the first examples of conflicting information in the production guide is the server configuration step. At different parts of the guide it suggests either a one or two-server setup.
You can choose the number of servers that will run Canvas, and which applications will use which server. The best recommendation at this point seems to be three servers with 8GB RAM each. Keeping the database and Canvas LMS running in the same server seems to be okay, but the official recommendation is to keep “memory-hungry” components separate, as in the case of Redis, daemon (automated background tasks) and the Canvas Rails app itself.
A fourth server could be recommended for the Apache server app. Although it seems there it no need for a server just for Apache, it is not clear which of the other three could share resources with it.
Choosing different servers will have implications going forward:
- The database must accept “foreign” connections (incoming from another server). This requires editing the database configuration files.
- If you are using a Virtual Machine, you might need to disable concurrent instances running in the step of linking the Canvas app with the Apache server.
Installing and configuring supporting software
You will need to install the following software, and then integrate one another:
- Ruby, its libraries and packages, and Rails. They begin here with Ruby Gems, which manages Ruby libraries (“Gems”), followed by Bundler, and continuing throughout the guide.
- The database. Instructure recommends PostgreSQL 9.5 or newer, on which the production guide is based. Install the database and create a “Canvas” user (name and password). Later on you will give Canvas the user info to let them create and udpate the tables.
- Apache and Passenger, including the Passenger + Apache library. The documentation to link the two to Rails is on a link currently not opening. Lighter instructions are here.
- SSL for Apache. This process can vary widely with the choices of free and paid SSL certificates available.
- Canvas for Apache + Passenger. The process involes linking a single “virtual instance” (on Apache, VirtualHosts) to Canvas and editing a
canvas.conffile with your server and SSL information.
Locating and installing Canvas LMS
Find a reasonable directory address in your server to upload the unpacked files of Canvas. The guide suggests
The files included on the package come with lots of preconfigured settings. Depending on your needs and context, you will need to find each file and locate them. Most of the configuration files have a YML extension and are on the
Initializing Canvas LMS options
- The database: Find the
config/database.ymland add the Canvas user database credentials you created earlier.
- Outgoing mail. Fint
config/outgoing_mail.ymland update it with your SMTP server information. Learn more.
- The domain of the website, on
- Security: Random hashing at
- Automated jobs: Canvas uses a daemon process, a common name for applications that run in the background.
Generating assets and populating databases
Canvas will automatically build a number of “assets” before it works correctly on its first launch. You need to build the directories manually, however. The list of directories is here.
Following the asset creation, the database will initialize with baseline data provided by Canvas. By running the initial setup executable, the console will prompt you for a series of “environment variables” and permissions. You will also be asked whether you want Canvas to send your LMS data to Instructure for analysis and monitoring.
Security: Canvas LMS ownership and roles
Once the initial setup is complete, edit the roles to make sure that your Canvas LMS site cannot be configured from outside, nor that Canvas can edit things on the server beyond its purview.
- Like on the database step, Create a unique Canvas user for Rails and limit its ownership.
- For all the YML files on the
configfolder, make it so only the Rails Canvas user you create can view and modify them.
First Canvas LMS launch
The final step should be to restart the Apache app:
sudo /etc/init.d/apache2 restart
Then, open your browser on the Canvas installation (mind the domain). You will be prompted for the Database admin credentials. Log in and follow the screen. You should be able to run a blank Canvas.
Where to go from here
After this process, you are ready to open Canvas and log in. There are some components that need extra configuration in order to work, including file optimization, rich content editor, and the copy and importing quizzes feature, which is technically a plugin (QTIMigrationTool).
A particuarly important step is Redis for cache optimization. It involves copying a configuration file from the Redis installation into the Canvas folder, as explained here.
Troubleshooting options are available: Here is a list of common issues. Canvas LMS forum is available at community.canvaslms.com which offers guides and other useful materials. There is also a Canvas LMS mailing group.