Skip to content

Quick Start

Jump to bottom Edit New page
Mysti Lilla edited this page Oct 11, 2024 · 202 revisions

This guide is intended for those who want to get a version of Canvas LMS running as quickly as possible (e.g. for a development environment). The environment produced by this guide is lacking in several features (e.g. emails are not sent out, delayed jobs are not daemonized, there is no proper application server provided, no message bus integration is installed) and is not suitable for production use.

See the Production Start guide for instructions on standing up a production-ready system.

If you need help installing Canvas or troubleshooting your installation, your best bet is to join the community mailing list or the IRC channel (see the Home page) and ask specific questions there. It's likely that somebody else has already tackled the same problem. Note that a common category of questions are those that stem from following this guide instead of the Production Start guide. If you are sure that you want to continue with the Quick Start guide, read on.

Setup

Automated Setup

If you are running macOS or Ubuntu, you can clone the repository and run the docker_dev_setup.sh script to automatically setup a development environment with Docker. It is recommended that you have at least 150GB of available hard drive space, 8GB of RAM, and a quad-core CPU to use this script.

./script/docker_dev_setup.sh

for some systems you may need to run the following first: export DOCKER_BUILDKIT=0 export COMPOSE_DOCKER_CLI_BUILD=0 .. but do not run this unless the setup script fails with a docker file permission issue.

The doc/docker directory has more detailed information about using Docker for Canvas Development.

Manual Setup

This tutorial is targeting POSIX-based systems like macOS and Linux. This tutorial was written and tested using Ubuntu LTS 20.04 Focal and macOS 13 Ventura. If you have a different system, consider setting up a server or virtual machine running Ubuntu 20.04 LTS. We'll assume you've either done so or are familiar with these working parts enough to do translations yourself.

Getting the code

There are two primary ways to get a copy of Canvas: git or zip/tar download.

Using Git

If you don't already have Git, you can install it on Debian/Ubuntu by running

sudo apt-get install git

Once you have a copy of Git installed on your system, getting the latest source for Canvas is as simple as checking out code from the repo, like so:

mkdir ~/exempt; cd ~/exempt # because the virus scanner is configured to ignore this dir and it makes everything faster
git clone https://github.com/instructure/canvas-lms.git canvas
cd canvas
git checkout prod

Using a Tarball or a Zip Download

You can also download a tarball or zip file.

Application root

Wherever you check out the code to, we're going to call that your application root. The application root is the folder that has folders such as app, config, and script. For the purposes of this tutorial, we'll assume your application root is /home/user/canvas.

GitHub Codespaces Setup

If you're in the GitHub Codespaces beta, you can create a codespace that runs Canvas for you without having to install anything on your computer, which is useful if you do not have the ability to set it up manually. To start, you will need to fork this repository so you can create a codespace. Once complete, press the "code" button on the repo, select "Open with Codespaces" and then create a new codespace. GitHub will then start building your codespace for you, which might take a minute the first time.

Once the codespace has been created, you will need to install the dependencies to start installing Canvas. This can be done by running the following commands:

sudo apt-get update
sudo apt-get -y install postgresql-14 zlib1g-dev libldap2-dev libidn11-dev libxml2-dev libsqlite3-dev libpq-dev libyaml-dev libxmlsec1-dev curl build-essential

Note: Codespaces may default to using Node 17+. You can run nvm install to use the required version of node and npm for the compile_assets script to complete without errors.

Once that has completed, then run the following commands (you can paste them directly into the integrated terminal if you want to):

rvm install "ruby-3.1.0"
rvm use 3.1.0
gem install bundler:2.4.19
gem install nokogumbo scrypt sanitize ruby-debug-ide
sudo chown -R codespace:codespace /workspaces/canvas-lms/
sudo chown -R codespace:codespace /usr/local/rvm/rubies/ruby-3.1.0/lib/ruby/gems/3.1.0
bundle _2.4.19_ install
yarn install --pure-lockfile
for config in amazon_s3 delayed_jobs domain file_store outgoing_mail security external_migration dynamic_settings database; \
          do cp -v config/$config.yml.example config/$config.yml; done
sudo chown -R codespace:codespace /usr/local/rvm/rubies/ruby-3.1.0/lib/ruby/gems/3.1.0
bundle _2.4.19_ update
sudo chown -R codespace:codespace /var/run/postgresql/
export PGHOST=localhost
/usr/lib/postgresql/14/bin/initdb ~/postgresql-data/ -E utf8
/usr/lib/postgresql/14/bin/pg_ctl -D ~/postgresql-data/ -l ~/postgresql-data/server.log start
/usr/lib/postgresql/14/bin/createdb canvas_development
bundle exec rails canvas:compile_assets
bundle exec rails db:initial_setup

Notes:

  • If asset compilation fails, you may be running into memory limits, in which case you may need to change to a larger machine type.
  • Once these commands are finished, the final command (bundle exec rails db:initial_setup) requires user input to setup login credentials for the admin user. If no prompt appears, make sure that errors didn't occur during the setup process that caused dependencies or gems to not install.

Once you are finished with that, you will need to make some minor configuration changes if you are using Codespaces in a browser, and not via VS Code. Go to the "Ports" tab next to the Terminal tab in GitHub Codespaces and copy the host from the automatically forwarded port (should look like https://7af34f90-...). Then, go to config/domain.yml in the Codespaces editor. Modify the development part to look like this:

development:
  # Replace this with the domain your GitHub Codespace is accessible at.
  domain: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa-3000.apps.codespaces.githubusercontent.com"

Make sure that it does not start with https:// or end with /. Make sure to replace the 5432 with 3000. This specifies what port you are using for the web server.

Then, save your changes to the file and run bundle exec rails server to start your Canvas instance. If everything is working, you should see * Listening on http://127.0.0.1:3000 and be able to access the instance in your browser from clicking on the "Ports" tab and hitting the globe icon on the port with "3000". You should be able to login with the credentials you created in the script and access everything.

When you are done using your instance (important to avoid data corruption)

Codespaces automatically expire in 30 minutes, and they will sometimes shutdown, which can cause database corruption if the database is still running when it gets shutdown. Use the following commands to shutdown the database when you are ready to end it:

export PGHOST=localhost
/usr/lib/postgresql/14/bin/pg_ctl stop -D ~/postgresql-data/

Then, press on the Settings icon in the bottom-left > Command Palette and then type in "Codespaces: Suspend Current Codespace". This will end your session and allow you to exit peacefully.

Starting it again

To start it again, you need to use the following commands:

export PGHOST=localhost
/usr/lib/postgresql/14/bin/pg_ctl start -D ~/postgresql-data/
bundle exec rails server

This should allow you to open your Canvas instance in your browser, provided you are logged in to GitHub while you do it. Your instance is now ready to be used for development and testing! You may want to take a look at all of the other sections in this guide, as they provide useful information that you might use to run tests and use other resources that might require additional setup.

Dependency Installation

Canvas currently requires Ruby 3.1. Ruby 3.2+ is not supported.

External Dependencies

Debian/Ubuntu

We now need to install the Ruby libraries and packages that Canvas needs. On Debian/Ubuntu, there are a few packages you're going to need to install. Depending on the currently-required version of Ruby and whether it is available from your version of Debian/Ubuntu, additional steps may be required to install Ruby (such as using a Ruby environment manager like rbenv).

You can use our PPA to install ruby:

sudo apt-get install software-properties-common
sudo add-apt-repository ppa:instructure/ruby
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get install ruby3.1 ruby3.1-dev zlib1g-dev libxml2-dev \
                     libsqlite3-dev postgresql-14 libpq-dev \
                     libxmlsec1-dev libyaml-dev curl build-essential

Node.js installation:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
NODE_MAJOR=18
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
sudo apt-get update
sudo apt-get install nodejs -y

Yarn installation:

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt-get update && sudo apt-get install yarn=1.19.1-1

After installing Postgres, you will need to set your system username as a postgres superuser. You can do so by running the following commands:

sudo -u postgres createuser $USER
sudo -u postgres psql -c "alter user $USER with superuser" postgres

macOS

For macOS, you'll need to install the Command Line Tools for Xcode, and make sure you have Ruby 3.1. You can find out what version of Ruby your Mac came with by running:

ruby -v

You also need Postgres and the xmlsec library installed. The easiest way to get these is via homebrew. Once you have homebrew installed, just run:

brew install postgresql@14 node@18 xmlsec1 libyaml shared-mime-info
npm install -g npm@latest

Ruby Gems

Most of Canvas' dependencies are Ruby Gems. Ruby Gems are a Ruby-specific package management system that operates orthogonally to operating-system package management systems.

Bundler

Canvas uses Bundler as an additional layer on top of Ruby Gems to manage versioned dependencies. Bundler is great!

You can install Bundler using Ruby Gems:

sudo gem install bundler

Canvas Dependencies

Once you have installed Bundler, please navigate to the Canvas application root, where you can install all of the Canvas dependencies using Bundler.

cd canvas
bundle install
yarn install --pure-lockfile
# Sometimes you have to run this command twice if there is an error
yarn install --pure-lockfile

Known issues:

unicode gem

gem install unicode -- --with-cflags="-Wno-incompatible-function-pointer-types"

thrift gem

bundle config build.thrift --with-cppflags='-D_FORTIFY_SOURCE=0'
  • If you are on El Capitan and encounter an error with the thrift gem that has something like the following in the text.
compact_protocol.c:431:41: error: shifting a negative signed value is undefined [-Werror,-Wshift-negative-value]

Use the following command to install the gem and then continue with another bundle install.

gem install thrift -v 0.8.0 -- --with-cppflags=\"-D_FORTIFY_SOURCE=0 -Wno-shift-negative-value\"

The problem is the clang got updated in El Capitan and some of the flags cause problems now on install for the old version of thrift.

  • If you get the following error during bundle install:
An error occurred while installing thrift (0.9.3.0), and Bundler cannot continue.
Make sure that `gem install thrift -v '0.9.3.0' --source 'https://rubygems.org/'` succeeds before bundling.

Install separately the thrift gem using the following command and restart bundle install:

gem install thrift -v '0.9.3.0' -- --with-cppflags="-Wno-compound-token-split-by-macro"

then if bundle install fails looking for the idn library, brew install libidn

eventmachine gem

  • If you hit an error with the eventmachine gem, you might have to set the following bundler flag and then run bundle install again:
bundle config build.eventmachine --with-cppflags=-I/usr/local/opt/openssl/include

Data setup

Canvas default configuration

Before we set up all the tables in your database, our Rails code depends on a small few configuration files, which ship with good example settings, so, we'll want to set those up quickly. We'll be examining them more shortly. From the root of your Canvas tree, you can pull in the default configuration values like so:

for config in amazon_s3 delayed_jobs domain file_store outgoing_mail security external_migration; \
          do cp -v config/$config.yml.example config/$config.yml; done

Dynamic settings configuration

This config file is useful if you don't want to run a consul cluster with canvas. Just provide the config data you would like for the DynamicSettings class to find, and it will use it whenever a call for consul data is issued. Data should be shaped like the example below, one key for the related set of data, and a hash of key/value pairs (no nesting)

cp config/dynamic_settings.yml.example config/dynamic_settings.yml

File Generation

Canvas needs to build a number of assets before it will work correctly. You will need to run:

bundle exec rails canvas:compile_assets

Note that we've seen trouble with npm trying to hold too many files open at once. If you see an error with libuv while running npm, try increasing your ulimit. To do this in macOS add ulimit -n 4096 to your ~/.bash_profile or ~/.zsh_profile.

Database configuration

Now we need to set up your database configuration. We have provided a sample file for quickstarts, so you just need to copy it in. You'll also want to create two databases. Depending on your OS (i.e. on Linux), you may need to use a postgres user to create the database, and configure database.yml to use a specific username to connect. See the Production Start tutorial for details on doing that. On macOS your local user will have permissions to create databases already, so no special configuration is necessary.

cp config/database.yml.example config/database.yml
createdb canvas_development

Note: When installing postgres with brew, you may have trouble connecting to the database and you may get an error like:

createdb canvas_development
createdb: could not connect to database postgres: could not connect to server: No such file or directory
    Is the server running locally and accepting
    connections on Unix domain socket "/var/pgsql_socket/.s.PGSQL.5432"?

If you get a connection error when creating your databases, run the following and add it to your .bash_profile:

export PGHOST=localhost

If, after that, you get another error like:

createdb canvas_development
createdb: could not connect to database template1: could not connect to server: Connection refused
    Is the server running on host "localhost" (::1) and accepting
    TCP/IP connections on port 5432?
could not connect to server: Connection refused
    Is the server running on host "localhost" (127.0.0.1) and accepting
    TCP/IP connections on port 5432?
could not connect to server: Connection refused
    Is the server running on host "localhost" (fe80::1) and accepting
    TCP/IP connections on port 5432?

then postgres may not be running. To start it:

initdb /usr/local/var/postgres -E utf8
pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log start

Database population

Once your database is configured, we need to actually fill the database with tables and initial data. You can do this by running our migration and initialization tasks from your application's root:

bundle exec rails db:initial_setup

Test database configuration

If you want to test your installation, you'll also need to create a test database:

psql -c 'CREATE USER canvas' -d postgres
psql -c 'ALTER USER canvas CREATEDB CREATEROLE' -d postgres
createdb -U canvas canvas_test
psql -c 'GRANT ALL PRIVILEGES ON DATABASE canvas_test TO canvas' -d canvas_test
psql -c 'GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO canvas' -d canvas_test
psql -c 'GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO canvas' -d canvas_test
env RAILS_ENV=test bundle exec rails db:test:reset
psql -c 'GRANT canvas_readonly_user TO canvas' -d postgres

Make sure you can run a spec file (the full suite takes too long to run locally):

bundle exec rspec spec/models/assignment_spec.rb

If you get an error about peer authentication failed for user "canvas", go to this gist.

Performance Tweaks

Installing redis will significantly improve your Canvas performance. For detailed instructions, see Production Start#redis. On macOS, use the following:

brew install redis
redis-server /usr/local/etc/redis.conf
echo -e "development:\n  cache_store: redis_cache_store" > config/cache_store.yml
echo -e "development:\n  url:\n  - redis://localhost" > config/redis.yml

On Ubuntu, use the following:

sudo apt-get update
sudo apt-get install redis-server
redis-server
echo -e "development:\n  cache_store: redis_store" > config/cache_store.yml
echo -e "development:\n  url:\n  - redis://localhost" > config/redis.yml

If you're just looking to try out Canvas, there's some minor configuration tweaks you can make to give yourself a real performance boost. All you need to do is add three lines to a file in your configuration directory. (If you plan on doing Canvas development, you may want to skip this step or only enable class caching, as these settings will require you to restart your server each time you change Ruby or ERB files.)

echo -n 'config.cache_classes = true
config.action_controller.perform_caching = true
config.action_view.cache_template_loading = true
' > config/environments/development-local.rb

Please be aware that the instructions described in the Production Start tutorial will give you a much faster Canvas installation.

A note about emails

Canvas will often attempt to send email. With the Quick Start instructions, email will go straight to the console that rails server is running on. If you want to set up email that actually goes to email addresses, please follow the Production Start instructions.

Ready, Set, Go!

Now you just need to start the Canvas server! You will need to run the rails server daemon:

bundle exec rails server

Open up a browser on the same computer as the one running the server and navigate to http://localhost:3000/ and log in with the user credentials you set up during database configuration. If you don't have a browser running on the same computer:

bundle exec rails server --binding=IPAddress

Then you can connect using the external hostname or IP address of the computer, be going to http://<hostname>:3000/.

Logging in For the First Time

Your username and password will be whatever you set it up to be during the rails db:initial_setup step above. (You should have seen a prompt on the command line that asked for your email and password.)

A note about long-running jobs

Canvas relies heavily on background job processors to perform tasks that take too long to do in-line during a web request. The Production Start instructions have details of how to set up dedicated job processors for production environments. To start a background job processor, run the following command:

bundle exec script/delayed_job run

Running Canvas securely locally

Install puma-dev and follow the set up instructions. Add export THEADS=1 to ~/.powconfig. In Canvas, in domain.yml add ssl: true under the development section. In session_store.yml under development, add secure: true.

To start for Mac, set up puma-dev in launchctl launchctl load ~/Library/LaunchAgents/io.puma.dev.plist. You can view server logs by tailing the logs in log/development.log. You can have the certificates accepted by opening Keychain Access, and move the Puma-dev CA to System.

Troubleshooting

We have a full page of frequently asked questions about troubleshooting your Canvas installation. See our Troubleshooting page.

Production ready configuration

These instructions were meant to give you a taste of Canvas. If you want to actually set up a production ready Canvas instance, please read the Production Start page.

Are you looking for one of our commercial subscriptions, professional services, support, or our hosted solution? Check out canvaslms.com.

Add a custom sidebar
Clone this wiki locally