Disponible en Español · In this tutorial
As of 2020, 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, and striking district-level partnerships that secure them dozens of schools within one agreement.
But even if your organization is not a top LMS spender, you can still find out what all the fuss is about.
The following guide will show you how you can install Canvas LMS for free on your server or cloud.
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 licensing 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 to deliver paid for services. Many argue that without this loophole some (if not all) 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 head start for startups everywhere. Of course, not everyone is in the same position to take advantage of them.
It is clear that the decision to offer free, open source software is strategic. Instructure’s decision to make Canvas’ code 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 latest stable version is recommended
- And the Ruby on Rails framework
- Linux. Canvas official tutorial is built in Ubuntu, tested for the 14 and 16 LTS versions. It claims it can be run on the latest LTS version.
- 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, setting up a Virtual Machine should be a great idea. If you’re looking to play around and not go into production right away, check out the Docker file for Canvas or fork it directly on a GitHub Codespaces repo.
- Ruby on Rails. In addition, other dependencies are listed throughout the guide, the installation being very straightforward. 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. To note, there is nothing preventing Rails 3 from working with a MySQL databate: 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 Docker and GitHub Codespaces routes mentioned earlier.
The production guide is a more exhaustive walk-through, but one that can be difficult to navigate directly from its own GitHub instructions.
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 as close to the latest stable version as possible. Install the database and create a “Canvas” user (name and password). Later on you will give Canvas a user access to let it create and update the tables.
- Apache and Passenger, including the Passenger + Apache library. Light instructions are here.
- SSL for Apache. This process can vary widely with the choices of free and paid SSL certificates available. (Left as an exercise for the reader)
- Canvas for Apache + Passenger. The process involves 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 these settings across several files and adjust 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: Adding randomized strings 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 and give Canvas ownership. 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 created 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.
To sum up, and where to go from here
Installing Canvas LMS for free is possible, with utmost care for the environment in which it is deployed, requirements and dependencies set up and up-to-date; establishing connections between the different systems, managing permissions and adjusting settings. Canvas LMS is a Ruby on Rails App that connects to a database (most likely PostgreSQL) and is delivered online using Apache HTTP with Passenger.
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 particularly 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.