Skip to main content

Upgrading Guide

Run Migrations

When deploying an updated version of the LMS, please check for any pending migrations and run them after deployment. If your deployment target is DigitalOcean, and if you've follwed our guide, then the worker process should run migrations automatically when it starts up.

Breaking changes

These are a list of changes that should be accounted for when upgrading an existing installation of Pupilfirst. If you encounter any problems while following these instructions, please create a new issue on our Github repo.

Your current version can be found in Pupilfirst::Application::VERSION or in the Docker image tag.


This version adds a new start script (bin/start) for the LMS that responds to new environment variables PROCESS_TYPE, WORKER_MIGRATE and WORKER_SETUP_CRON. These variables must be set when deploying to DigitalOcean App Platform. When deploying to Heroku, the recommended approach has changed to pushing official Docker images to Heroku's Container Registry, and then releasing these images to dynos. This replaces the older time-consuming, failure-prone build process on Heroku. On Heroku, you'll also need to set a new environment variable - TINI_SUBREAPER. Please go through updated deployment documentation for both these platforms for more information.


This version replaces Skylight with New Relic for application performance monitoring and adds the NEW_RELIC_LICENSE_KEY environment variable to authenticate connection with New Relic. The version also replaces rack-throttle gem with rack-attack for throttling and blocking abusive requests. This change adds environment variables GRAPH_API_RATE_LIMIT, GRAPH_API_RATE_PERIOD and REDIS_URL to set the number of requests, the period of time in seconds and the URL to the Redis database store respectively.


This version adds the PREPARE_FOR_PRECOMPILATION environment variable. If you're building Pupilfirst in production, this environment variable will need to be set to true to allow the Rails asset precompilation step to work properly.


Markdown editors no longer support the Commonmark standard. Even prior to this version, support for mixing HTML, CSS and JS into Markdown was spotty because of very strict output sanitization. This means that Commonmark support was partial. With this change, scripting within Markdown text inputs has been completely disabled.

This means that any stored Markdown text that contained compliant HTML / CSS / JS within prior to this change will now be escaped and displayed as plaintext in the rendered output.

This also breaks the <img align="center"> approach for centering text. Since this method for centering text in HTML relied on writing HTML within Markdown, it doesn't work anymore. Instead, Markdown's syntax has been extended to support alignment of text using special markers. Check out the built-in documentation of Markdown for more information.


Introduced required environment variables I18N_AVAILABLE_LOCALES and I18N_DEFAULT_LOCALE.


Google's Recaptcha has been introduced to protect public-facing forms from automation. To enable the use of Recaptcha, register for access, and create v3 and v2 (checkbox) keys for your school's domains, and add environment variables RECAPTCHA_V3_SITE_KEY, RECAPTCHA_V3_SECRET_KEY, RECAPTCHA_V2_SITE_KEY, and RECAPTCHA_V2_SECRET_KEY.


List courses query is now paginated. This will affect users using the courses API query.


Introduced required environment variable VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY to support webpush notification.

You can generate the keys by running the following on the server.

vapid_key = Webpush.generate_key




Introduced required environment variables GRAPH_API_RATE_LIMIT, MEMCACHEDCLOUD_SERVERS, MEMCACHEDCLOUD_USERNAME, and MEMCACHEDCLOUD_PASSWORD to handle API rate limiting. Memcached Cloud add-on needs to be added while hosting on Heroku.


Introduced required environment variable DEFAULT_SENDER_EMAIL_ADDRESS. Prior to this, the default sender email id was assumed to be


Introduced required environment variable AWS_REGION. Prior to this, the region was assumed to be us-east-1; set the correct value for your S3 bucket.


Initial release.