cristianoc / pupilfirst

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.

Changelog

Visit pupilfirst.com/changelog to view the full changelog.

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

On OSX

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 Postgres.app 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:

On OSX:

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.

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

yarn run graphql-codegen

The GraphQL end-point is configured in the codegen.yml file.

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.
\q

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 [e-mail] (use the Continue as Developer option in dev env), to test access to all interfaces.

Optional: Manually mark data migrations as complete

There is an unacknowledged issue with the data-migrate gem that leaves the list of data migrations unpopulated when the database is seeded. If you intend to run data migrations, or are setting up the platform for production use, you'll need to manually mark all existing data migrations as up. To do this, run the contents of db/data_schema.rb in the Rails console - it should look something like this:

DataMigrate::Data.define(version: USE_VALUE_FROM_DATA_SCHEMA_FILE)

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 www.school.localhost sso.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 127.0.0.1 in the /etc/hosts file:

127.0.0.1       school.localhost
127.0.0.1       www.school.localhost
127.0.0.1       sso.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:

bin/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 http://www.school.localhost.

Testing

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.

Services

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