Canvas RCE API is a service that proxies all API requests needed for the Canvas rich content editor and sidebar. Requests are authenticated via a JWT generated by Canvas.
In the future running the Canvas RCE API service will be required for full functionality of the rich content editor in Canvas.
Canvas RCE API is a Node.js application. It can either be run with node directly
or in a Docker container. In either case be sure to properly configure the
application via environment variables and to have a web server or load balancer
in front of the application to terminate TLS connections. The application does
not handle https requests directly.
The application can be run directly with Node.js by either running npm start
or node app.js. It is designed to work with the current Node.js LTS (18.x)
release. Be sure to run npm install --production first to install all of the
package dependencies.
A Node.js process only runs on a single thread. To take full advantage of multiple CPU cores on your application server, it is recommended that you use something to manage and balance load between node processes such as Passenger or PM2.
A Docker image is available on Docker Hub at instructure/canvas-rce-api:latest
or Starlord at starlord.inscloudgate.net/jenkins/canvas-rce-api:latest. The
container will run the application behind Nginx with Passenger listening on port
80. Please refer to the documentation for the instructure/node-passenger base image
for nginx and passenger configuration environment variables.
docker run \
-e ECOSYSTEM_KEY \
-e ECOSYSTEM_SECRET \
-e FLICKR_API_KEY \
-e YOUTUBE_API_KEY \
-e STATSD_PORT=8125 \
-e STATSD_HOST=127.0.0.1 \
instructure/canvas-rce-apiTo ensure that credentials and payloads are encrypted over the wire, https
should be used. https requests are not directly supported by the application.
Be sure to have a TLS termination proxy in front of the application. This can be
done with a load balancer such as HAProxy or Amazon ELB/ALB. It
can also be done with Apache or Nginx running on the same server if
you are only running a single server.
Configuration options are set via the following environment variables:
ECOSYSTEM_KEY: Required The encryption secret shared with Canvas.ECOSYSTEM_SECRET: Required The signing secret shared with Canvas.FLICKR_API_KEY: Required to support Flickr image search.YOUTUBE_API_KEY: Required for querying titles of YouTube embeds.NODE_ENV: This should always be set toproductionwhen running in production.PORT: Defaults to port3000. This is not used when running with Docker since Node Passenger monkey patches nodehttpto control the port each node process is listening on.STATSD_HOST: If you would like to collect metrics with statsd, this should be set to the host of your statsd server.STATSD_PORT: If you would like to collect metrics with statsd, this should be set to the port of your statsd server.
Canvas needs to be configured to find the rich content service via the
config/canvas/rich-content-service/app-host value in Consul or, for local
development, the following value in dynamic_settings.yml:
development:
config:
canvas:
rich-content-service:
app-host: "canvas-rce-api-host"Canvas also needs to be configured to use the same encryption key and signing secret as the rich content service, for example:
development:
"app-canvas/data/secrets":
data:
canvas_security:
encryption_secret: "astringthatisactually32byteslong"
signing_secret: "astringthatisactually32byteslong"The only dependency needed to develop canvas-rce-api is a recent LTS release
of Node.js (18.x). All other dependencies are installed via npm. Alternatively
if you don't want to install Node.js on your machine you can run in docker
using the included docker-compose file.
Make a copy of the example .env file. Environment variables defined in this
file will be available when running the application. See the previous section
for configuring Canvas to setup a local Canvas environment to test with.
cp .env.example .env
Additionally, make a copy of the docker-compose.override.yml.dev file with
the following command:
cp docker-compose.override.yml.dev docker-compose.override.yml
If you'd like to use Instructure's Traefik set up for networking, copy ./inst-cli/docker-compose/docker-compose.local.dev.yml to docker-compose.local.dev.yml and set up the COMPOSE_FILE variable in your .env file to include docker-compose.local.dev.yml
COMPOSE_FILE=docker-compose.local.dev.yml
npm install
npm run start:dev # will automatically restart the app when you make changes
or can build docker locally:
docker-compose build
docker-compose up
Docker requires canvas to use rce.docker as the app-host in instead of whatever is being used by localhost.
This project uses prettier to automatically format source code. Code will be
automatically formatted via a pre-commit hook, but it is reccomended that you
configure your editor to format on save if possible.
This project uses eslint to catch non-stylistic code issues. Linting errors
will cause the build to fail, so it is recommended that you configure your
editor to report eslint errors.
All tests live under the top level test directory and have a *.test.js
filename. Tests are written using mocha and the standard assert package.
Sinon is availble for stubbing dependencies, but prefer injecting dependencies
over stubbing shared bindings where possible.
To run all tests, do yarn test
Example of running a single test file:
yarn test:one test/service/api/folders.test.js
For now releasing to NPM is a manual process.
We use a post-merge Jenkins job to auto-publish :latest Docker images to
Dockerhub and our internal registry, Starlord.
When preparing a release, make sure to tag the release commit with the v1.2.3
semantic release tagging convention. For example:
git tag "v1.2.3"
git push --tags originImportant: without the v in the git tag, the post-merge Jenkins job won't
publish a version-specific Docker image.
This project is is released under the MIT license.