Local Environment Setup Guide: Docker & Canvas LMS

Portfolio Context

This documentation captures the internal architecture and developer runbooks for an academic evaluation system. It has been genericized and published here to demonstrate technical writing, system architecture design, and Developer Experience (DevEx) engineering. There are no proprietary IP or NDA encumbrances.

To test Canvas LMS API integrations locally or in a staging environment, developers must provision a standalone Canvas LMS instance and configure the OAuth 2.0 developer keys.

We utilize a containerized Canvas instance hosted on an AWS EC2 server. While this Docker-based instance lacks some enterprise features, it provides a sufficient environment for full API and integration testing.

Prerequisites

If you need to provision a Canvas instance from scratch rather than using the existing pre-configured AWS server, ensure the host machine has the following dependencies installed:

• Git
• Docker & Docker Compose
• Mutagen & Mutagen Compose
• Dory

Caution

Environment Variances: Installation commands vary based on the host operating system (e.g., using yum on Amazon Linux versus apt-get on Ubuntu/Debian). Furthermore, Canvas is highly memory-intensive; ensure your EC2 instance is sufficiently provisioned to avoid out-of-memory (OOM) crashes. Ensure all necessary firewall ports are open for HTTP/HTTPS traffic.

For a comprehensive from-scratch installation guide, refer to the Canvas LMS GitHub Repository Quick Start.

---

1. Starting the Canvas Instance

Follow these steps to boot the pre-configured Canvas testing environment on AWS:

1. SSH into the Host Server: Connect to your designated EC2 instance. You can find the public IPv4 address for the testing server in the AWS EC2 dashboard.

2. Navigate to the Repository:

   cd canvas-lms

3. Initialize the Dev Setup (First Time Only): If the instance is not already running, execute the setup script.

   ./script/docker_dev_setup.sh

   Note: This process takes significant time. When prompted to create an administrator account, provide a testing email address.

4. Start the Containers: Spin up the Docker stack using Mutagen.

   mutagen-compose up -d

5. Verify Container Health: Ensure all containers booted successfully.

   docker ps -a

6. Access the Web Interface: Open your browser and navigate to http://<EC2_PUBLIC_IPV4_ADDRESS>. Log in using the testing credentials established during step 3.

---

2. Generating the OAuth Developer Key

To allow your application to communicate with Canvas, you must register it as an authorized client application.

1. Navigate to Developer Keys: Within the Canvas web interface, click Admin > Site Admin > Developer Keys from the left sidebar.
2. Create a New Key: Click + Developer Key > + API Key.
3. Configure Key Parameters:
   • Key Name: Local Integration Testing
   • Owner Email: Enter your designated testing admin email.
   • Redirect URIs: Enter your application’s OAuth callback URL (e.g., https://api.your-app.com/oauth/callback).
   • Redirect URI (Legacy): (Enter the same URI as above to prevent legacy routing issues).
4. Enforce Scopes: Toggle Enforce Scopes and select the specific API endpoints required by your application.
5. Save and Extract Credentials: Click Save Key. The system will generate two critical values:
   • Client ID: The numerical string visible under the “Details” column.
   • Client Secret: Click Show Key to reveal the alphanumeric secret. Store these securely.

Your Canvas instance is now actively running and configured to accept OAuth 2.0 requests from your client application!