Setting up the Canvas LMS system: a comprehensive step-by-step guide

Canvas LMS is a popular open-source learning management system that supports educational institutions in creating and managing their courses online. While powerful, setting up Canvas LMS can sometimes be difficult exercise due to incomplete andunclear documentation. This blog post is designed to provide a clear, comprehensive guide to help you set up Canvas LMS on Linux and macOS systems. Note that Windows users should utilize the Windows Subsystem for Linux (WSL) with a Debian or Ubuntu-based image for optimal results. For detailed instructions, please refer to the Microsoft WSL Installation Guide.

Download and setup instructions for Canvas LMS

Download the Canvas LMS Source code: Begin by downloading the latest version of the Canvas LMS source code from GitHub using the wget command:

wget https://github.com/instructure/canvas-lms/archive/refs/heads/master.zip

Unzip the downloaded file: extract the Canvas LMS directory from the downloaded zip file:

unzip master.zip

Rename the extracted folder: this step makes the directory easier to access:

mv canvas-lms-master canvas-lms

Navigate to the Canvas LMS directory:

cd canvas-lms

Configure the Docker compose file: open the docker-compose.yml file in the vi editor (or your editor of choice) and replace its contents with the provided configuration. Remember to save your changes:

vi docker-compose.yml

Then, clear the existing content and replace it with the following configuration:

# See doc/docker/README.md or https://github.com/instructure/canvas-lms/tree/master/doc/docker
version: '2.3'
services:
  web: &WEB
    build:
      context: .
    links:
      - postgres
      - redis
    ports:
      - "80"
    volumes:
      - .:/usr/src/app
      - api_docs:/usr/src/app/public/doc/api
      - brandable_css_brands:/usr/src/app/app/stylesheets/brandable_css_brands
      - bundler:/home/docker/.bundle/
      - canvas-docker-gems:/home/docker/.gem/
      - js-utils_es:/usr/src/app/packages/js-utils/es
      - js-utils_lib:/usr/src/app/packages/js-utils/lib
      - js-utils_node_modules:/usr/src/app/packages/js-utils/node_modules
      - locales:/usr/src/app/config/locales/generated
      - log:/usr/src/app/log
      - node_modules:/usr/src/app/node_modules
      - pacts:/usr/src/app/pacts
      - public_dist:/usr/src/app/public/dist
      - reports:/usr/src/app/reports
      - styleguide:/usr/src/app/app/views/info
      - tmp:/usr/src/app/tmp
      - translations:/usr/src/app/public/javascripts/translations
      - yardoc:/usr/src/app/.yardoc
      - yarn-cache:/home/docker/.cache/yarn
    environment:
      POSTGRES_PASSWORD: sekret
      ENCRYPTION_KEY: facdd3a131ddd8988b14f6e4e01039c93cfa0160
      RAILS_ENV: development

  jobs:
    <<: *WEB
    command: bundle exec script/delayed_job run

  postgres:
    build: ./docker-compose/postgres
    environment:
      POSTGRES_PASSWORD: sekret

  redis:
    image: redis:alpine

volumes:
  api_docs: {}
  brandable_css_brands: {}
  bundler: {}
  canvas-docker-gems: {}
  i18nliner_node_modules: {}
  js-utils_es: {}
  js-utils_lib: {}
  js-utils_node_modules: {}
  k5uploader_es: {}
  k5uploader_lib: {}
  k5uploader_node_modules: {}
  locales: {}
  log: {}
  node_modules: {}
  pg_data: {}
  pacts: {}
  public_dist: {}
  reports: {}
  styleguide: {}
  tmp: {}
  translations: {}
  yardoc: {}
  yarn-cache: {}

Remove unnecessary configuration files: if there is an existing config/dynamic_settings.yml file, remove it as it may contain incorrect settings for your setup:

rm config/dynamic_settings.yml

Copy configuration files: copy the example configuration files from the Docker setup to your Canvas LMS configuration directory:

cp docker-compose/config/*.yml config/

Build Docker images: build the Docker images for Canvas LMS, ensuring you pull the latest versions of any dependencies:

docker-compose build --pull

Create Docker containers: prepare the Docker containers without starting them to allow for any necessary adjustments:

docker-compose up --no-start web

Install necessary assets: Run the Canvas LMS asset installation script:

docker-compose run --rm web ./script/install_assets.sh

Initialize the database: set up the initial database tables and default configurations:

docker-compose run --rm web bundle exec rake db:create db:initial_setup

Migrate the database for testing: prepare your instance for running tests by migrating the database:

docker-compose run --rm web bundle exec rake db:migrate RAILS_ENV=test

Start all services: launch all of the Canvas LMS services in detached mode:

docker-compose up -d

Verify that the services are running: finally, confirm that your Canvas LMS instance is up and running. Since the web container runs on a randomly assigned port, use the following command to find out which port it is using:

docker ps

Look for the 'web' service in the output. The PORTS column will show the mapping, for example, 0.0.0.0:32768->80/tcp. In this case, Canvas LMS would be accessible in your web browser at http://localhost:32768.

You should now have a fully functioning Canvas LMS environment set up and ready for use. Remember to adjust file permissions back to a secure setting after setup. Enjoy using Canvas LMS for your educational needs!