Skip to content
PupilFirst is a feature-rich open-source Learning Management System (LMS) that is built around the philosophy that true learning cannot happen by just consuming information; it happens when students attempt relevant tasks and get personalised feedback for improvement from domain experts.
Ruby OCaml CSS HTML JavaScript CoffeeScript C++
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
app Show linked targets when showing question details Sep 16, 2019
bin Upgrade to webpacker 4 RC2 Dec 17, 2018
changelog Show linked targets when showing question details Sep 16, 2019
config Merge branch 'master' into open-source-cleanup Aug 29, 2019
db Simplify docs around school domains and its seeding for dev Aug 27, 2019
lib Avoid stringifying values of null 'id' keys Sep 16, 2019
log initial commit Dec 3, 2013
public Improve typography, pupilfirst logo for mailers Jul 25, 2019
spec Show linked targets when showing question details Sep 16, 2019
.browserslistrc Upgrade to webpacker 4 RC2 Dec 17, 2018
.editorconfig Adding .editorconfig file. Apr 16, 2015
.gitignore Update sign in spec Jul 18, 2019
.overcommit.yml Remove all third-pary libraries from the vendor directory Jan 24, 2019
.prettierignore Instruct prettier to ignore Tailwind config file May 3, 2019
.rspec Use Fuubar as formatter for RSpec Oct 10, 2016
.rubocop.yml Upgrade Rubocop to v0.74 Aug 14, 2019
.ruby-version Upgrade to Ruby 2.6.3 and Rails 5.2.3 Apr 22, 2019
Gemfile Replace sleep with rspec eventually Sep 16, 2019
Gemfile.lock Replace sleep with rspec eventually Sep 16, 2019
LICENSE Add the MIT license Aug 22, 2019
Procfile Remove vocalist from Procfile Jul 26, 2019 Instruct to use non-SSL domain in development Aug 27, 2019
Rakefile Require webdrivers Rakefile only in dev Jun 11, 2019
app.json Add the apt buildpack to app.json Jul 24, 2017
babel.config.js Upgrade Webpacker to latest v4.0.7 Jul 11, 2019
bsconfig.json Finish first version of client-side target status computer May 21, 2019
cloc-exclude Remove all third-pary libraries from the vendor directory Jan 24, 2019
codecov.yml Disable codecove from preventing deploys due to coverage changes Feb 23, 2018 Rubocop AA. Sep 17, 2015
example.env Update PostmarkWebhookController and spec it Sep 5, 2019
graphql_schema.json Add mutation for sorting target resources Aug 22, 2019
package.json Add support for table rendering with Markdown Aug 28, 2019
postcss.config.js Replace primary to primary-500 May 15, 2019
tailwind.config.js Improve style for course-show and apply page Jul 31, 2019
yarn.lock Add support for table rendering with Markdown Aug 28, 2019

PupilFirst Logo

TeamCity Status for SVdotCO/pupilfirst Maintainability Test Coverage

Setup for development

  1. Install and configure dependencies
    1. Install third-party software
    2. Install Ruby environment
    3. Setup Javascript environment
    4. Setup ReasonML environment
  2. Set credentials for local database
  3. Configure application environment variables
  4. Setup Overcommit
  5. Seed local database
  6. Set up a reverse-proxy using Nginx
  7. Compile ReasonML, run Webpack Dev Server, and run the Rails Server

Install and configure dependencies

Install third-party software


We'll use Homebrew to fetch most of the packages on OSX:

  • imagemagick - brew install imagemagick
  • redis - brew install redis
  • nginx - brew install nginx
  • postgresql - Install and follow its instructions.
On Ubuntu

The following command should install all required dependencies on Ubuntu. If you're using another flavour of Linux, adapt the command to work with the package manager available with your distribution.

sudo apt-get install imagemagick redis-server postgresql postgresql-contrib autoconf libtool nginx

Install Ruby and Rubygems

Use rbenv to install the version of Ruby specified in the .ruby-version file.

Once Ruby is installed, fetch all gems using Bundler:

$ bundle install

If installation of of pg gem crashes, asking for libpq-fe.h, install the gem with:

find /Applications -name pg_config
gem install pg -- --with-pg-config=/path/to/pg_config
On Ubuntu:
sudo apt-get install libpq-dev

Setup Javascript Environment

  1. Install NVM following instructions on the offical repository.
  2. Install the LTS version of NodeJS: nvm install --lts
  3. Install Yarn following offical instructions.. Make sure you do not install NodeJS again along with it (read Yarn instructions).
  4. Install all node modules with yarn command.

Setup ReasonML environment

If you've installed all node modules using Yarn, then the basic environment should be ready at this point. However, you'll also need to install the Reason CLI toolchain to get all add-on features to work properly in VSCode:

npm install -g reason-cli@latest-macos (OSX) or @latest-linux (Linux)

Set credentials for local database

# Run psql command as postgres user.
sudo -u postgres psql postgres

# Set the password for this user.
\password postgres

# Quit.

Configure application environment variables

Copy example.env to .env.

$ cp example.env .env

The file contains documentation explaining where you should source its values from. At minimum, edit .env and set values for Postgres DB username and password that you used in the previous step.

Setup Overcommit

Overcommit adds automatic checks that prevents us from making silly mistakes when committing changes.

$ overcommit --install
$ overcommit --sign

Seed local database

$ rails db:setup

This will also seed data useful for development. Once you've started the server, you should be able to sign in as (use the Continue as Developer option in dev env), to test access to all interfaces.

Set up a reverse-proxy using Nginx

Use Nginx to set up a reverse proxy on a .localhost domain to point it to your web application running on port 3000 (the default Rails server port). Use following server configuration as an example:

Place the following configuration at /usr/local/etc/nginx/servers/pupilfirst (OSX) or at /etc/nginx/sites-enabled/pupilfirst (Linux).

server {
  listen 80;
  server_name school.localhost;

  location / {
    proxy_pass http://localhost:3000/;
    proxy_set_header Host $host;

You may also need to point the local school domain school.localhost, and the www and sso subdomains, to in the /etc/hosts file:       school.localhost

Compile ReasonML, run Webpack Dev Server, and run the Rails Server

Compile and watch ReasonML files for changes:

yarn run bsb -make-world -w

On another tab or window, start the Webpack Dev Server:


On another tab or window, run the Rails server:

bundle exec rails server

You'll want all three of these processes running for best performance when developing.

If your Nginx reverse-proxy has been set up correctly, then visit the school using your browser at


You might need to create the test database that you've configured with environment variables.

To execute all tests manually, run:

$ rspec

Generating coverage report

To generate spec coverage report, run:

COVERAGE=true rspec

This will generate coverage report as HTML within the /coverage directory.


Background jobs are written using Rails ActiveJob, and deferred using delayed_job in the production environment.

By default, the development and test environment run jobs in-line with a request. If you've manually configured the application to defer them instead, you can execute the jobs with:

$ rake jobs:workoff
You can’t perform that action at this time.