-
Notifications
You must be signed in to change notification settings - Fork 2.8k
Quick Start
This page contains many grammatical errors. This page was originally only in Chinese, but was translated into English. However, no translation software is perfect, so there are bound to be issues with the result. You can help by editing this page to fix issues.
Translator: This page was missing entirely. This is an automatic translation from the Chinese version. May be inaccurate.\
This article is intended to help you quickly build the development environment of Canvas LMS locally. This environment lacks some features (e.g. messages are not sent, delayed tasks are not protected, appropriate application servers are not provided, and message bus integration is not installed) and are not suitable for production use.
See the Production Start guide to build a production environment system.
If you need help during the installation or troubleshooting process, the best way is to join the community mailing list or IRC channel (see the Home page) and ask specific questions there. It is likely that others have solved the same problem. Common problem categories are those that arise from following this guide rather than the Production Start guide. If you are sure to continue using the Quick Start Guide, keep reading. Configuration Automatic configuration
If you are using macOS or Ubuntu, you can clone the repository and run the docker_dev_setup.sh script to automatically configure a development environment with Docker. It is recommended that you have at least 150GB of hard disk space, 8GB of memory, and a quad-core CPU to use this script.
./script/docker_dev_setup.sh
For some systems, you may need to run the following command first:
export DOCKER_BUILDKIT=0
export COMPOSE_DOCKER_CLI_BUILD=0
But if the problem is not caused by a Docker file permissions issue, please do not run these commands.
The doc/docker directory contains more detailed information about Canvas development using Docker . Manual configuration
This tutorial is aimed at POSIX-based systems such as macOS and Linux. This tutorial was written and tested on Ubuntu LTS 20.04 Focal and macOS 13 Ventura. If you are using another system, consider setting up an environment on a server or virtual machine running Ubuntu 20.04 LTS. We’ll assume that you’ve done so, or that the parts of the work are familiar enough to work on their own. Access to source code
There are two main ways to get Canvas source code: git or zip/tar download. Use of Git
If you don't already have Git installed, you can install it on Debian/Ubuntu by running the following command:
sudo apt-get install git
When you have Git installed on your system, getting the latest source code for Canvas is as simple as checking out code from a repository, as follows:
mkdir ~/exempt; cd ~/exempt
git clone https://github.com/instructure/canvas-lms.git canvas
cd canvas
git checkout prod
Download Zip/Tar
You can also download a tarball or zip file to get the Canvas source code.
Application root directory
Wherever you look out your code, we’ll call it your application root. The application root directory is a folder containing folders such as apps, config, and script. In this tutorial, we will assume that your application root directory is /home/user/canvas . GitHub Codespaces
If you’re using GitHub Codespaces beta, you can create a Codespaces that will automatically run Canvas for you without having to install anything on your computer, which is useful in situations where you can’t set it up manually. First, you need fork this repository so that you can create a Codespaces. When you're done, press the "code" button on the repository, select "Open with Codespaces", and create a new Codespaces. GitHub will start building Codespaces for you. On the first run, this can take a minute.
After Codespaces is created, you will need to install dependencies to start installing Canvas. This can be done by running the following command:
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 use Node 17+ by default. You can run. nvm installTo use the required versions of node and npm, so that compile_assetsThe script can be successfully completed without error.
When done, then run the following commands (if you want, you can paste them directly into the integrated terminal):
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
Attention:
- If the resource compilation fails, you may encounter memory limitations, at which point you may need to switch to a larger machine type .
- When these commands are completed, the last command (bundle exec rails db:initial_setupRequires user input to set the login credentials of the administrator user. If no prompt appears, make sure that no errors occur during setup, resulting in dependencies or gems not installed.
When you’re done with these, if you’re using Codespaces through your browser instead of VS Code, you’ll need to make some minor configuration changes. In GitHub Codespaces, go to the Port tab next to the Terminal tab and copy the host of the auto-forward port (should look like https://7af34f90-...). Go to the Codespaces editor. config/domain.yml. . will developmentPartially modified to the following:
development:
domain: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa-3000.apps.codespaces.githubusercontent.com"
Ensure that it does not start with a protocol declaration (https://) or end with a slash (/). **Ensure that 5432Replaced by 3000. . **This specifies the port you use for the web server.
Next, save your changes to the file and run it. bundle exec rails serverStart your Canvas instance. If everything is normal, you should see the following message:
* Listening on http://127.0.0.1:3000
And you can access your instance in your browser by clicking on the “Ports” tab and clicking the Earth icon on the port with “3000”. You should be able to log in and access everything with the credentials you created in the script. After the use of the example (it is important to avoid data corruption)
Codespaces expire automatically after 30 minutes, sometimes closing, which can cause the database to remain running when it shut down, causing database corruption. When you are ready, close the database with the following command:
export PGHOST=localhost
/usr/lib/postgresql/14/bin/pg_ctl stop -D ~/postgresql-data/
Then, click on the Settings icon > Command panel in the bottom left corner, and type "Codespaces: Suspend Current Codespace". This will end your session and allow you to exit safely. Restarting examples
You can restart your Codespaces instance with the following command:
export PGHOST=localhost
/usr/lib/postgresql/14/bin/pg_ctl start -D ~/postgresql-data/
bundle exec rails server
This should restart your Canvas instance, provided you log in to GitHub. Your example is now ready for development and testing! You may want to check out all the other parts of this guide, which contain useful information and explains some of the resources that may require additional settings. Environmental dependence
Canvas currently requires Ruby 3.1. Ruby 3.2+ is not supported. This information is not accurate, I encountered Gemfile error when using 3.1, and the minimum version required by Gemfile is 3.3.1). External dependency Debian and Ubuntu
First, we need to install the Ruby libraries and packages that Canvas requires. On Debian/Ubuntu, you need to install some packages. Depending on whether the Ruby version you currently need and whether your Debian/Ubuntu version is available, you may need to take additional steps to install Ruby (for example, using it). rbenvthe Ruby environment manager).
You can use our PPA to install Ruby: (translator: this PPA is not available, I use rvm installed 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
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
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 need to set your system username to superuser. You can do this by running the following command:
sudo -u postgres createuser $USER
sudo -u postgres psql -c "alter user $USER with superuser" postgres
macOS
For macOS, you need to install the command line tool for Xcode and make sure that your Ruby version is 3.1. You can view the Ruby version of your Mac that comes with you by running the following command: (Translator's note: If you use a Ruby environment manager such as rvm or rbenv, you can ignore this step and encounter Gemfile reporting error when using 3.1, and the minimum version required by Gemfile is 3.3.1.)
ruby -v
You also need to install the Postgres and xmlsec library. The easiest way is to install it via Homebrew. Once you have installed Homebrew (REQUIRED, just run:
brew install postgresql@14 node@16 xmlsec1 libyaml
npm install -g npm@latest
Ruby Gems
Most of the Canvas dependencies are Ruby Gems. Ruby Gems is a unique package management system for Ruby that runs orthogonally with the operating system's package management system (without interfering with each other). Ruby Bundler
Canvas uses Bundler as an extra layer for Ruby Gems to manage versioning dependencies. Bundler is great!
You can install Bundler using Ruby Gems:
sudo gem install bundler
Canvas Dependence
After you install the Bundler, navigate to the root directory of the Canvas app, and you can use Bundler to install all Canvas dependencies.
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
If you encounter an error installing unicode gem on macOS, use the following command to install it (see [https://github.com/blackwinter/unicode/pull/11):](https://github.com/blackwinter/unicode/pull/11%EF%BC%89%EF%BC%9A)
gem install unicode -- --with-cflags="-Wno-incompatible-function-pointer-types"
Thrift gem
If you encounter a thrift gem error on macOS Mavericks or macOS Yosemite, set the following bundler parameter and run bundle install again (see [https://issues.apache.org/jira/browse/THIFT-2219):](https://issues.apache.org/jira/browse/THRIFT-2219%EF%BC%89%EF%BC%9A)
bundle config build.thrift --with-cppflags='-D_FORTIFY_SOURCE=0'
If you encounter a thrift gem error on El Capitan, the error message is similar to the following:
compact_protocol.c:431:41: error: shifting a negative signed value is undefined [-Werror,-Wshift-negative-value]
Use the following command to install gem, and then proceed to run bundle install.
gem install thrift -v 0.8.0 -- --with-cppflags="-D_FORTIFY_SOURCE=0 -Wno-shift-negative-value"
This issue comes from the clang update in El Capitan, and some parameters can now cause problems with older versions of thrift during installation.
If you are in operation. bundle installThe following errors were encountered:
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.
Use the following instructions to install separately thriftgem and then re-run bundle install::
gem install thrift -v '0.9.3.0' -- --with-cppflags="-Wno-compound-token-split-by-macro"
And then if bundle installIn Search idnThe library fails, please run. brew install libidn Eventmachine gem
If you encounter an error installing the eventmachine gem, set the following bundler parameter and run bundle install again:
bundle config build.eventmachine --with-cppflags=-I/usr/local/opt/openssl/include
Data initialization Canvas Default Configuration
Before we set up all the tables in the database, our Rails code relies on a few small configuration files that contain good example settings, so we need to set them up quickly. We will discuss them in more detail later. From the Canvas root, you can pull the default configuration value like this:
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
This configuration file is useful for users who do not want to run the consul cluster in Canvas. Simply provide the configuration data you want the DynamicSettings class to find, and it will use it when a call to the consul data is made. The data should be like the following example, a key to the relevant dataset, and a hash of the key/value pair (not nested):
cp config/dynamic_settings.yml.example config/dynamic_settings.yml
File generation
Canvas needs to build many static files before it works correctly. You need to operate:
bundle exec rails canvas:compile_assets
Note that npm sometimes tries to open too many files at the same time and there is a problem. If you see it when running npm libuvErrors, please try to increase ulimit. . On macOS, you can ulimit -n 4096Added to ~/.bash_profileor ~/.zsh_profile. . Database configuration
Now we need to set up the database configuration. We provided an example file for a quick start, so you just have to copy it. You also need to create two databases. Depending on your operating system (for example, on Linux), you may need to use the postgres user to create the database and configure database.yml to connect with a specific username. For more information about how to do this, see the Production Start tutorial. On macOS, your local users will already have permission to create a database, so no special configuration is required. Before, we have added super user permissions to the current user, so we can use the current login user directly.)
cp config/database.yml.example config/database.yml
createdb canvas_development
Note: When you install postgres with brew, you may experience problems connecting to the database, and the following errors may occur:
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 encounter a connection error when you created a database, run the following command and add it to .bash_profile:
export PGHOST=localhost
After adding, you may encounter the following errors:
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?
At this point, postgres may not be running, you can start postgres with the following command:
initdb /usr/local/var/postgres -E utf8
pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log start
Database Filling
When your database is configured, we need to actually populate the database table and the initial data. You can do this by running our migration and initialization tasks from the application root directory:
bundle exec rails db:initial_setup
Test database
If you want to test your installation, you 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 package runs for too long):
bundle exec rspec spec/models/assignment_spec.rb
If you encounter a peer authentication failed error for the user "canvas", check out this gist . Performance adjustment
Installing Redis will significantly improve the performance of Canvas. For more details, see Production Start#redis . On macOS, use the following command:
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 command:
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 just want to try Canvas, there are some small configuration tweaks that allow you to get real performance improvements. You only need to add three lines to a file in the configuration directory. If you’re planning to develop Canvas, you may need to skip this step or only enable class caching, because these settings will require you to restart the server every time you change a Ruby or ERB file.
echo -n 'config.cache_classes = true
config.action_controller.perform_caching = true
config.action_view.cache_template_loading = true
' > config/environments/development-local.rb
Note: Using the production environment configuration process (see Production Start ) will make your Canvas run faster. About the mail
Canvas usually tries to send an email. Using the Quick Start Guide, Mail will be sent directly to Run rails serverThe control panel. If you want to set up the mail that is actually sent to the email address, follow the Production Start guide. Start-up service
Now you just need to start the Canvas server! You need to run the rails server daemon:
bundle exec rails server
Open the browser on the same computer and navigate to http://localhost:3000/ , logging in using the user credentials you set during the database configuration process. If you don't run your browser on the same computer:
bundle exec rails server --binding=IPAddress
After that, you can connect via the computer's external host name or IP address to visit http://:3000/. First login
The first time you log in, you need to use it. rails db:initial_setupThe administrator credentials set up during the process are logged in. You should see a prompt on the command line asking you to enter your email and password. Tasks for long-term operation
Canvas relies heavily on the back-office worker processor to perform tasks that cannot be completed during a web request. The Production Start guide contains detailed information on how to set up dedicated job processors for production environments. To start the background job processor, run the following command:
bundle exec script/delayed_job run
Safely run Canvas locally (https)
Install puma-dev and follow the settings instructions. In the~/.powconfigIn the meantime, addexport THEADS=1. . In Canvas domain.yml, add under the development section ssl: true. . In session_store.yml , add under the development section secure: true. .
Set up puma-dev with launchctl on macOS: launchctl load ~/Library/LaunchAgents/io.puma.dev.plist. . You can pass. tail log/development.logThe logs in to view the server log. You can accept the certificate by opening Keychain Access and moving the Puma-dev CA to the System. Question investigation
We have a full page that lists the frequently asked questions about troubleshooting Canvas installations. Please check out our Troubleshooting page. Production Environment Configuration The above instructions are designed to give you a quick understanding of Canvas. If you want to actually set up a Canvas instance of a production environment, 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.