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 Reason CSS HTML JavaScript CoffeeScript C++
Branch: master
Clone or download

Latest commit

Latest commit ca8c1eb May 29, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows Allow setting of user time zone for specs May 6, 2020
app Rename the user's home page to user "dashboard" (#348) May 28, 2020
bin Appease Rubocop May 12, 2020
config Rename the user's home page to user "dashboard" (#348) May 28, 2020
db Remove old user fields, plus other cleanup (#339) May 27, 2020
docs Rename the user's home page to user "dashboard" (#348) May 28, 2020
lib Remove old user fields, plus other cleanup (#339) May 27, 2020
log initial commit Dec 3, 2013
public Update default favicon and use that in docs #142 Dec 11, 2019
spec Rename the user's home page to user "dashboard" (#348) May 28, 2020
storage Upgrade to Rails May 26, 2020
tmp/pids Upgrade to Rails May 26, 2020
.browserslistrc Upgrade to webpacker 4 RC2 Dec 17, 2018
.editorconfig Adding .editorconfig file. Apr 16, 2015
.gitignore Upgrade to Rails May 26, 2020
.overcommit.yml Set up overcommit to run stylelint pre-commit Feb 8, 2020
.prettierignore Instruct prettier to ignore Tailwind config file May 3, 2019
.rspec Use Fuubar as formatter for RSpec Oct 10, 2016
.rubocop.yml Prevent Rubocop from policing code-style May 12, 2020
.ruby-version Get CI working using Github Actions Apr 20, 2020
.rufo Add specs for level merge action May 12, 2020
.stylelintrc.json Remove trailing semicolon from v2 Markdown editor's CSS Feb 8, 2020
.tool-versions Add actions tab to level editor form May 12, 2020 Update links [skip ci] May 15, 2020
Gemfile Bump kaminari from 1.2.0 to 1.2.1 May 28, 2020
Gemfile.lock Bump kaminari from 1.2.0 to 1.2.1 May 28, 2020
LICENSE Use new company name! [skip ci] May 13, 2020
Procfile Remove vocalist from Procfile Jul 26, 2019 Introduce AWS_REGION environment variable May 26, 2020
Rakefile Require webdrivers Rakefile only in dev Jun 11, 2019 Introduce AWS_REGION environment variable May 26, 2020
app.json Add the apt buildpack to app.json Jul 24, 2017
babel.config.js Add syntax highlighting for ERB format Apr 24, 2020
bsconfig.json Replace date-fns v1 with v2 [skip ci] May 1, 2020
cloc-exclude Remove all of changelog Oct 21, 2019
codecov.yml Disable codecove from preventing deploys due to coverage changes Feb 23, 2018
codegen.yml Upgrade graphql_ppx_re to latest v0.3.2 Oct 30, 2019 Rubocop AA. Sep 17, 2015
example.env Remove old user fields, plus other cleanup (#339) May 27, 2020
graphql_schema.json Remove old user fields, plus other cleanup (#339) May 27, 2020
lerna.json Add lerna and initalize search package Jan 9, 2020
package.json Replace date-fns v1 with v2 [skip ci] May 1, 2020
postcss.config.js Replace primary to primary-500 May 15, 2019
tailwind.config.js Improve styling of students list search bar Jan 7, 2020
yarn.lock Replace date-fns v1 with v2 [skip ci] May 1, 2020

Pupilfirst Logo

License: MIT Maintainability Test Coverage Continuous Integration



Visit to view the full changelog.


Visit for a detailed explanation of Pupilfirst's features.

Deploying to production

There's an article in the wiki discussing how to deploy Pupilfirst to Heroku. Even if you're not using Heroku, we highly recommend going through the instructions before getting started.

Have doubts? Talk to our development team on our Discord server.


See for details on changes that should be accounted for when upgrading an existing installation of Pupilfirst.

The rest of this README file discusses how to set up this repository for development.

Setup for development

This documentation covers three platforms: macOS (10.15), Ubuntu (20.04), and Windows 10 (WSL 2, with Ubuntu 20.04). Instructions for Ubuntu also apply to Windows, except where special instructions are noted.

  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

On macOS

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

  • imagemagick - brew install imagemagick
  • redis - brew install redis. Start Redis server after installation.
  • nginx - brew install nginx. Start Nginx server after installation.
  • postgresql - Install and follow its instructions, including the part about setting up command-line tools.

Important: Make sure that you start both Nginx and Redis after you install them. Instructions on how to do that will be printed to the command-line after they're successfully installed.

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

You may need to install the bundler gem if the version of Ruby you have installed comes with a different bundler version. Simply follow the instructions in the error message, if this occurs.

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

On macOS:
# Find the exact path to pg_config.
$ find /Applications -name pg_config

# Use the path returned by the above command in the following one. Replace X.Y.Z with the same version that failed to install.
$ gem install pg -v 'X.Y.Z' -- --with-pg-config=/path/to/pg_config
On Ubuntu:
$ sudo apt-get install libpq-dev

Setup ReasonML & 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..
  4. From the root of the repository, run the yarn command to install all node modules.

Set credentials for local database

We'll now set a password for the postgres database username.

Make sure that the PostgreSQL server is running. Once that's done, run the following commands:

# Run psql for the postgres database username.
$ psql -U postgres

# Set a password for this username.
\password postgres

# Quit.

Feel free to alter these steps if you're familiar with setting up PostgreSQL.

Configure application environment variables

  1. Copy example.env to .env.

    $ cp example.env .env
  2. Update the values of DB_USERNAME and DB_PASSWORD in the new .env file.

    Use the same values from the previous step. The username should be postgres, and the password will be whatever value you've set.

The .env file contains environment variables that are used to configure the application. The file contains documentation explaining where you should source its values from.

Setup Overcommit

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

$ overcommit --install
$ overcommit --sign

Seed local database

$ bundle exec rails db:setup

This will also seed data into the database that will be useful for testing during development.

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:

  1. Place the following configuration at /usr/local/etc/nginx/servers/pupilfirst (macOS) 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;
  2. Restart nginx so that it picks up the new configuration.

    # macOS
    $ brew services restart nginx
    # Ubuntu
    $ sudo systemctl restart nginx
  3. You may also need to point the local school domain school.localhost, and the www and sso subdomains, to in the /etc/hosts file (on macOS and Ubuntu), and the C:\Windows\System32\Drivers\etc\hosts file on Windows:

    # Append to 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 re:watch

Once the compilation is complete, start the Webpack Dev Server on another tab or window:

$ bin/webpack-dev-server

On a third 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 http://school.localhost.

Browse the school with seeded data

You should be able to sign in as (use the Continue as Developer option on the sign-in page), to test access to all interfaces. Test data has been seeded to the development database to make this process easier.

Automated Testing

The default settings expect Google Chrome to be installed to run specs. To execute all tests, run:

$ rspec

You can choose which browser the specs run in, using the JAVASCRIPT_DRIVER environment variable. Check the spec/rails_helper.rb file for its possible options.

Generating coverage report

To generate spec coverage report, run:

$ COVERAGE=true rspec

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

Updating GraphQL schema

If you make any changes to the GraphQL schema, you'll need to update the graphql_schema.json file by running an introspection query.

With the Pupilfirst server running, run the graphql-codegen script.

$ yarn run graphql-codegen

It'll visit the local GraphQL end-point which is configured in the codegen.yml file, fetch the schema and store it in the graphql_schema.json file.

Running Background Jobs

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

Editing Documentation

The source of is stored in the /docs folder in this repo, and is managed using docsify.

First, install the docsify CLI globally:

$ npm i docsify-cli -g

Then serve the docs folder on the desired port.

$ docsify serve docs -p 3010

The -p option sets the port. Visit localhost:PORT to view docs locally.

You can’t perform that action at this time.