Skip to content

setup.md

Latest commit

 

History

History
228 lines (151 loc) · 7.32 KB

setup.md

File metadata and controls

228 lines (151 loc) · 7.32 KB

Setup guide

Quick start locally

First ensure you have the following set up in your computer

  • elixir 1.11.2
  • nodejs > 12 LTS
  • Postgresql > 11

You can use the phoenix installation guide to ensure you have everything set up as expected

Start server

To start your Phoenix server:

  • Install dependencies with mix deps.get
  • Create and migrate your database with mix ecto.setup
  • Install Node.js dependencies with npm install inside the assets directory
  • Start Phoenix endpoint with mix phx.server

Now you can visit localhost:4000 from your browser.

Ready to run in production? Please check our deployment guides.

Set up Github OAuth app

Use Github guide to create an OAuth app. Provide the information for Homepage URL and Authorization Callback URL in the following formats:

Homepage URL:

http:External_IP

Authorization Callback URL:

http:External_IP/auth/github/callback

External_IP is provided once a VM instance is launched.

Set up Google OAuth app

Instructions to setup Google OAuth app can be found on google setup docs

Set up LinkedIn OAuth app

Instructions to setup LinkedIn OAuth app can be found on google setup docs

SBOM

To access the SBOM of the project, visit bom.json or bom.xml to get them in json or xml format

permission to run game

In order to run the game, you must be a configurable player who has been provided with permission access to play the game. Players are required to login with their github account.

Instruction of how to play the game has been provided on the dashboard. Once you start the game, you will be able to see list of instruction displayed.

6. misc Convenience make tasks

This project includes a couple of convenience make tasks. To get the full list of the tasks run the command make targets to see a list of current tasks. For example

Targets
---------------------------------------------------------------
compile                compile the project
deploy-existing-image  creates an instance using existing gcp docker image
docker-image           builds docker image
format                 Run formatting tools on the code
lint-compile           check for warnings in functions used in the project
lint-format            Check if the project is well formated using elixir formatter
lint                   Check if the project follows set conventions such as formatting
push-and-serve-gcp     creates docker image then push to gcp and launches an instance with the image
push-image-gcp         push image to gcp
release                Build a release of the application with MIX_ENV=prod
test                   Run the test suite
update-instance        updates image of a running instance

Contributing

This project uses semantic versioning as much as we can

Issue tracking

We use github issues to track issues , checkout the project board for issues

All issues have priorities with A being the highest priority

Deployment strategy

All work merged into the develop branch are automatically pushed to the staging server

working with questions

Adding questions

We currently have two folders for adding questions, it can be on the qna directory or the courses both on the project root directory. Contest questions are currently on the qna directory while courses contains questions for a classroom setup type of questions

To add a question, you will need to add a markdown file which should meet the following conditions

  1. It needs to define the question type

This is defined in the 'header' of the file. The two questions types currently allowed are free-form and multi-choice (take note of the -). The header is then followed by three dashes

Example

%{
 type: "free-form"
}

---
  1. Needs to clearly define the question

The main question is marked by the first level markdown header (using one #) followed by the word question

Example

## Software Bill of Materials
A “Software Bill of Materials” (SBOM) is
effectively a nested inventory,
a list of ingredients that make up

# Question:
What does SBOM stand for?

Anything before the answers header is considered part of the question

  1. The answers need to be clearly defined

Answers are marked by second level markdown header (that is two #) with the word answers

For multichoice answers, we use the markdown list (-) to show the options. The position of the correct answer is counted from 0 being the first option (this information will be used later when generating/updating answers)

Example

```markdown
## Answers
- Security Bungles Obfuscate Mission
- Software Bill of Materials
- Special Bureau of Meteorology
- Security Bill of Materials
```
  1. Scores should be provided

We need to provide the score for both right score and wrong score

Example

```markdown
## Score
- Right:25
- Wrong:5

```
  1. Power up for the question

This determines what powerup the user gets whenever they get the correct answer. Valid power ups are - deleteblock - addblock - moveblock - clearblocks - speedup - slowdown - fixvuln - fixlicense - rm_all_vulns - rm_all_lic_issues - superpower

Example

## Powerup
DeleteBlock

Generating answers

There is a convenience tasks that generates default answers (0 for multichoice and "secret" for free-form questions)

$ mix gen.answers

Compiling 67 files (.ex)
Generated quadblockQuiz app

12:57:05.448 [info]  Generating answers for qna..

12:57:05.483 [info]  Answers written to qna/answers.json

12:57:05.483 [info]  Generating answers for courses..

12:57:05.493 [info]  Answers written to courses/answers.json

If you run this command without any arguments, it will generate answers for both qna and courses directories. The generated answers do not override any previous answer if there was any existing answers

To generate answers for a single directory only, pass in the directory name as an argument to the command

$ mix gen.answers qna # genratates only for the qna folder

12:57:05.448 [info]  Generating answers for qna..

12:57:05.483 [info]  Answers written to qna/answers.json

$ mix gen.answers courses # genratates only for the courses folder

12:57:05.448 [info]  Generating answers for courses..

12:57:05.483 [info]  Answers written to courses/answers.json

Customising the answers

Once the default answers have been generated, we can open the answers.json file and provide the correct answers. Note that the answers you provide will not be overridden by the next mix gen.answers

For development purposes, the first multichoice answer is always the correct answer, the word "secret" is always the answer to a free-form question

If you add a new question to either qna or courses directory then running mix gen.answers will add the default answer to only the new files you have added (assuming you had generated the answers before adding those two files)