Setup Dev Environment

These instructions will set up a development environment with the Torus server running directly on the host machine.

Mostly Automated Steps

1. Install dependencies:

   • Docker and docker-compose
   • Elixir ($ brew install elixir)
   • Phoenix ($ mix archive.install hex phx_new 1.5.9)

2. Clone this repository $ git clone https://github.com/Simon-Initiative/oli-torus

3. Run $ sh ./devmode.sh

4. Run $ mix phx.server

5. Open your web browser to https://localhost.

Mostly Manual Steps

1. Install dependencies:

   • Docker and docker-compose
   • Elixir ($ brew install elixir)
   • Phoenix ($ mix archive.install hex phx_new 1.5.9)

2. Clone this repository $ git clone https://github.com/Simon-Initiative/oli-torus

3. Create configuration env files:

   $ cp oli.example.env oli.env
   $ cp postgres.example.env postgres.env
   

4. Configure oli.env for running natively: REPLACE:

   DB_HOST=postgres
   

   WITH:

   DB_HOST=localhost
   

5. Start dockerized postgres 12 via the included docker-compose file:

   $ docker-compose up -d postgres
   

6. Install server and client dependencies:

   $ mix deps.get
   $ cd assets && yarn
   

7. Create database

   $ cd ../ && mix ecto.create
   

8. Run migration to create schema

   $ mix ecto.migrate
   

9. Seed the database

   $ mix run priv/repo/seeds.exs
   

10. Configure bash to properly source environment variable configurations

    $ set -a
    

11. Load phoenix app configuration from environment file. This step is necessary anytime you change a configuration variable

    $ source oli.env
    

12. Start Phoenix server

    $ mix phx.server
    

    Note: Use Ctrl+c to stop the Phoenix server

13. Open your web browser to https://localhost.

Notes

In order to sign in, you must use https and accept the self-signed cert browser warning to avoid CSRF issues. If you would like to provide your own cert instead of accepting the included one, simply replace priv/ssl/localhost.crt -or- use the localhost tunneling method below to generate a public URL with SSL enabled.

Docker is not a strict dependency. We use it here to simplify the install and running of Postgres. You can choose to install and run Postgres bare-metal, but you will not be able to use the Mostly Automated Steps above (since the ./devmode.sh script depends on Docker).

Working on NG23?

If so, you will have to make some additional setup steps

Running Tests

Note: If you are running using docker-compose as described in Quick Start, you can create a bash session to execute any of the following commands using docker-compose exec app bash

1. Run JavaScript tests

   $ cd assets && npm run test
   

2. Run elixir tests

   $ mix test
   

3. Run elixir tests for a specific file, watch for changes and automatically re-run tests

   $ mix test.watch --stale --max-failures 1 --trace --seed 0 lib/some_dir/file_to_watch.ex
   

   Re-run only failed tests

   $ mix test.watch --failed --trace --seed 0 lib/some_dir/file_to_watch.ex
   

   Using fswatch, re-run only the test files that have changed as well as the tests that have gone stale due to changes in lib and pause on any failures

   $ fswatch lib test | mix test --listen-on-stdin --stale --seed 0 --trace --max-failures 1
   

4. Generate an html coverage report

   $ mix coveralls.html
   

5. Occasionally the test database will need to be reset (e.g. if tests were cancelled partway through)

   $ MIX_ENV=test mix ecto.reset
   

Tunneling localhost connection for LTI development

When making an LTI connection from an LMS such as Canvas, we need an internet accessible FQDN with SSL to properly configure a connection. The service ngrok offers an easy to use command line tool that does just this.

1. Download ngrok and install using their instructions (Create a free account if required)
2. Run ngrok locally to tunnel to phoenix app on port 4000 ngrok http 4000
3. Access your running webapp using the generated https address (shown in console after Forwarding). This will be the same address used to configure the LMS LTI connection

Configuring an LTI 1.3 Connection

Torus supports LTI 1.3 integration and leverages the Learning Management System for course delivery.

To configure an LTI connection, refer to the Torus LTI 1.3 Manual Configuration.