This is the same as the md version, so its better to look at that one somewhere 
that renders md. This guide is for the GraderFinder folder in this directory.

# GraderFinder
This guide is for the GraderFinder folder in this directory

GraderFinder is a tool to help teachers find graders. It is based off of Instructure's open source
Canvas LMS, which can be found here:

* [Canvas Open Source LMS](https://github.com/instructure/canvas-lms)

GraderFinder, like Canvas, is built on Ruby on Rails, and makes use of a postgresql database. It
also uses Apache2 as a file server. 


* [Go to installation guide](#installation)

# Canvas Code and Directory Structure

Canvas's code base is very big, so we will only go over the files and directories relevant to GraderFinder.
Rails applications follow a MVC architecture, so we will follow the same in this 
guide.

The majority of the code that provides functionality are located in the app folder.

## app/models
Models represent objects in the database, and their functions are used to manipulate
the database.

You will see near the beginning of the classes in these files associations 
such as has_many, has_one. By searching for the comment GraderFinder, you will
be able to go to the sections of the code where associations with graderfinder
classes have been defined.
* ### Relevant Canvas Models
  * #### account.rb
    This represents an account, which can represent an organization, maybe a department. 
    An account is not a user, rather an account has many users. For graderfinder, prerequisites
    belong to accounts, so different accounts will have different sets of available
    prerequisites.
  * #### user.rb
    This represents users. User information is also held in the pseudonym table
    of the database, which holds the user's unique id and encrypted password. Users
    interact with graderfinder through the class in gf_user.rb
  * #### course.rb
    This represents a course in the database. It has prerequisites through the class
    in gf_course.rb
  * #### course_section.rb
    This represents course sections
  * #### enrollment.rb
    Represents a user's enrollment in a course
  * #### course_account_association.rb
    Represents which account each course belongs to
  * #### assignment_override.rb
    When an assignment is to be assigned to only specific groups, an assignment
    override associates the assignment to the groups
  * #### assignment_groups.rb
    Details about the actual groups the assignment is meant for
  * #### assignment_override_student.rb
    Associates a student to an assignment group   
* ### GraderFinder Models
  * #### gf_course_prereq.rb
    Represents a prerequisite that is associated to a course
  * #### gf_course.rb
    Associates a course from course.rb to its prerequisites and the graders
    that are assigned to grade it
  * #### gf_grader_application.rb
    Represents a grader's application to grade an assignment
  * #### gf_grader_assignment_association
    Represents a grader's association to an assignment that they are grading
  * #### gf_grader_prereq.rb
    Represents a prerequisite course that a grader has taken
  * #### gf_grader.rb
    Represents a grader. Graders are associated to users through gf_user
  * #### gf_prereq.rb
    Represents a prerequisite for an account
  * #### gf_section_assignment.rb
    Represents an assignment, one is created for each section the assignment is 
    assigned to. This is so that graders can apply to assignments on a section basis
  * #### gf_user.rb
    An intermediary between user and graderfinder. This class only says whether the 
    user is a grader or not.

## app/controllers
Controllers are the communication between models and views. Most models have a controller
through which a user can interact with the model. If a model does not have a controller,
that is because the user interacts with that model with another model that it is 
associated with. 

Controller follow this naming convention: controller_name(in plural)_controller.rb.
For example, the controller for user.rb is users_controller.rb. all graderfinder controllers,
like models, are labelled with gf before their names.

**Note**: assignments_api_controller.rb is probably where you want to go to edit 
assignment functionality.

The only specific controller we will go over her is the following:
#### application_controller.rb
This controller is the base for all other controllers in Canvas and GraderFinder.
If you ever wonder why a specific action is happening in all your controllers, it
is because it is defined here, and all controllers extend this one. If you want to 
define a new controller not extending this one, make it extend ActionController::Base
instead. This controller also extend ActionController::Base, which makes its
children extend it too. 

## app/views
Any controller that has views, their views will be located in a sub directory of views
names after the controller, without the controller part. For example:

The views for users_controller.rb will be located in the folder app/views/users

There are also folders in the views directory that are shared between controllers,
such as the shared folder and the jst folder.

## app/(others)

The other folder in the app directory are not as important, if folders are left 
out it is because we don't know what they are for/we never interacted with them:
* **assets** This folder contains automatically generated css/js scaffolding for 
  files that were created for graderfinder. As of now there is not functionality
  implemented here.
* **coffeescripts** This is where most of canvas's javascript is written
* **helpers** Functions that are shared between controllers
* **jsx** Mostly javascript files that control forms and views
* **presenters** Seems to have files that control links in views. The only 
  presenter I worked with was section_tab_presenter.rb, which controls the 
  url that sidebar tab takes you to
* **stylesheets** Contains most of Canvas's css/scss assets.

## bin
This directory seems like its for rails configuration. We never interacted with it

## build
This seems to be for the docker setup script which is supposed to automatically 
setup canvas for you. We never were able to successfully install Canvas this way.
See Instructure's guides for more information about this.

## client_apps
This seems to have files that control some applications that are integrated into canvas but are
not integrated into its code. We never interacted with this

## config
Most rails config files go here. The most important file here is routes.rb, where
you can define the urls of your pages. Here is where urls are associated with views

## db 
### db/migrate
Contains all of the database migration files. Here is where you can manipulate
the schema of the database by creating a migration file. Use the command
**rails g migration <migration_name>** to generate the file. To run migrations, 
enter the command rails db:migrate

### db/structure.sql
The postgresql database dump

## doc
This folder contains various documentation explaining canvas

## docker-compose
For docker setup

## Gemfile.d
This directory has files which determine which gems are going to be installed


## public
Stores logos and other resources that are shared 

# Installation

For more details on how to install GraderFinder, including on systems like macOS and
Ubuntu 16.04, please see the two guides provided by Instructure.

 * [Quick Start](http://github.com/instructure/canvas-lms/wiki/Quick-Start)
 * [Production Start](http://github.com/instructure/canvas-lms/wiki/Production-Start)

The following installation instructions are based on what can be found in the above 
two links. They will assume that you are using Ubuntu 18.04, which is the preferred 
OS for running GraderFinder.

Firstly, create a local directory containing all of GraderFinder's files. This will
be the root of the application, and most of the installation will take place from within
this folder. In fact, you can perform the entire installation from within this folder.

## External Dependencies

Firstly, we will install most of the external dependencies using the following commands:

```bash
sudo apt-get update 
sudo apt install ruby ruby-dev postgresql zlib1g-dev libxml2-dev libsqlite3-dev libpq-dev libxmlsec1-dev
```

In the second command, you will be asked to confirm the installation, type Y for yes.

## Node.js

Now we need to install Node.js and Yarn

Node.js needs to be installed from a source that provides a newer version than Ubuntu 18.04
has by default:

```bash
$ curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash – 
$ sudo apt-get install -y nodejs 
```

## Yarn

Use the following commands to install Yarn

```bash
$ curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
$ echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
$ sudo apt-get update && sudo apt-get install yarn=1.10.1-1
```


## Postgres User Configuration

If postgres is not already running, which is probably the case if you are using WSL, start it with
the command:
 
```bash
$ sudo service postgresql start
```

Next run the following two commands to create a postgres user:

```bash
sudo -u postgres createuser $USER
sudo -u postgres psql -c "alter user $USER with superuser" postgres
```

## Bundler

Bundler is used to manage Ruby gems. GraderFinder is built on a version of Canvas that uses Bundler
version 2.1.4. This was the latest version at the start of development, but Bundler 2.2.0 was released
on December 10, 2020. Therefore, the version must be specified when installing Bundler. This is not yet
reflected in Instructure's guides. 

```bash
sudo gem install bundler –v ‘>= 1.13.3, <= 2.1.4’
```

## GraderFinder Dependencies

If you are not already in your GraderFinder directory, please go there and stay there for the rest of the
installation.

Run the following commands to install GraderFinder's gems and other dependencies:

```bash
$ cd <graderfinder_dir> #wherever your graderfinder directory is
$ bundle install 
$ yarn install --pure-lockfile
```

Yarn install may need to be run twice if any errors occur in the first run.

## Data Setup

The following commands sets up Rails configuration files with the default
configuration files:

```bash
$ for config in amazon_s3 delayed_jobs domain file_store outgoing_mail security external_migration; \
          do cp -v config/$config.yml.example config/$config.yml; done
          
$ cp config/dynamic_settings.yml.example config/dynamic_settings.yml
```

## File Generation/Compiling Assets

The following command compiles GraderFinder's assets.

```bash
bundle exec rails canvas:compile_assets
```

If you change files such as javascript or css files, then you will have to recompile assets. Generally, if 
you change something and the change does not take place immediately, you will have to recompile assets.
The command **bundle exec rails canvas:compile_assets_dev** can be used to do this and is faster because it only
compiles files that are relevant to development.

## Database Configuration

The following will setup graderfinder with the default database configuration files,
make sure that postgres is running:

```bash
$ cp config/database.yml.example config/database.yml
$ createdb canvas_development
$ bundle exec rails db:initial_setup
```

After running the last command here, you will be asked to enter an email, password, and account name.
These will be used to access the admin account in GraderFinder.

## Test database configuration

The following commands will setup a test database to use with Canvas. I don't know why this is part 
of the instructions in the quickstart guide, we never used the test database during development, but 
its here for the sake of completeness and also to explain how to get around a common error when setting 
this up.

The commands to setup a test database are:

```bash
psql -c 'CREATE USER canvas' -d postgres
psql -c 'ALTER USER canvas CREATEDB' -d postgres
createdb -U canvas canvas_test
psql -c 'GRANT ALL PRIVILEGES ON DATABASE canvas_test TO canvas' -d canvas_test
psql -c 'GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO canvas' -d canvas_test
psql -c 'GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO canvas' -d canvas_test
RAILS_ENV=test bundle exec rails db:test:reset
```

You will probably run into an error in the third command **createdb -U canvas canvas_test** telling you about 
failed peer authentication. To fix this, enter the following command to enter postgres console:

```bash
psql postgres
```

In the postgres console, type:

```SQL
show hba_file
```

This will give you the location of the configuration file we will need to edit.

### Editing pg_hba.conf

Open this file and you will see something like the following at the bottom of the
file:

```text
# Database administrative login by Unix domain socket
local   all             postgres                                peer

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   all             all                                     trust
# IPv4 local connections:
host    all             all             127.0.0.1/32            trust
# IPv6 local connections:
host    all             all             ::1/128                 md5
# Allow replication connections from localhost, by a user with the
# replication privilege.
local   replication     all                                     peer
host    replication     all             127.0.0.1/32            md5
host    replication     all             ::1/128                 md5
```

In your file, change each METHOD field to trust where it is set in the example above.
You may want to find a safer way to do this if you are releasing the application for 
production.

More information about this issue can be found here:
* https://gist.github.com/AtulKsol/4470d377b448e56468baef85af7fd614


## Apache Installation

This part of the guide comes from the production start guide. At the moment,
you would be able to run Canvas with all of its assets with the following command:

```bash
bundle exec rails s
```

but you would not be able to download files or zip submissions. To do that, 
first we will install apache and all of it's dependencies. Remember that this part of 
the guide also takes place withing your GraderFinder directory. Run the following commands:

```bash
$ sudo apt-get install passenger libapache2-mod-passenger apache2
$ sudo a2enmod rewrite
$ sudo service apache2 restart

$ sudo a2enmod passenger
$ sudo service apache2 restart

$ sudo a2enmod ssl
$ sudo service apache2 restart
```

## Apache Configuration

We will now need to configure apache. This is probably the most complex part
of the guide. 

First create the configuration file: 

```bash
sudo nano /etc/apache2/sites-available/canvas.conf
```

And paste the following text:

```text
<VirtualHost *:80>
  ServerName canvas.example.com
  ServerAlias canvasfiles.example.com
  ServerAdmin youremail@example.com
  DocumentRoot /var/canvas/public
  RewriteEngine On
  RewriteCond %{HTTP:X-Forwarded-Proto} !=https
  RewriteCond %{REQUEST_URI} !^/health_check
  RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [L]
  ErrorLog /var/log/apache2/canvas_errors.log
  LogLevel warn
  CustomLog /var/log/apache2/canvas_access.log combined
  SetEnv RAILS_ENV production
  <Directory /var/canvas/public>
    Allow from all
    Options -MultiViews
  </Directory>
</VirtualHost>
<VirtualHost *:443>
  ServerName canvas.example.com
  ServerAlias canvasfiles.example.com
  ServerAdmin youremail@example.com
  DocumentRoot /var/canvas/public
  ErrorLog /var/log/apache2/canvas_errors.log
  LogLevel warn
  CustomLog /var/log/apache2/canvas_ssl_access.log combined
  SSLEngine on
  BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown
  # the following ssl certificate files are generated for you from the ssl-cert package.
  SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
  SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
  SetEnv RAILS_ENV production
  <Directory /var/canvas/public>
    Allow from all
    Options -MultiViews
  </Directory>
</VirtualHost>
```

The most important things to change here are:

* SetEnv RAILS_ENV production to SetEnv RAILS_ENV development (2 instances)
* Directory to your GraderFinder directory (2 instances)
* DocumentRoot to the public folder in your GraderFinder directory (2 instances)

You may also want to change the following:

* ServerName
* ServerAdmin
* SSLCertificateField
* SSLCertificateKeyFile
  
The latter two are for when the program is going to be released and already 
has an SSL certificate.

You will also want to change the options within the directory segment to
the following:

```text
<Directory /var/canvas/public>
    Options All
    AllowOverride All
    Require all granted
</Directory>
```

Of course, /var/canvas should have already been set to your directory.

### Optimizing File Downloads

To optimize file downloads you will want to install xsendfile with the following 
commands: 

```bash
sudo apt-get install libapache2-mod-xsendfile
sudo apachectl -M | sort
```

Now reopen the config file **/etc/apache2/sites-available/canvas.conf** and add 
the following two lines under each virtual host:

```bash
XSendFile On
XSendFilePath /var/canvas
```

Remember to replace the file path in the second command with your GraderFinder 
directory.

## Background Jobs

Configure background jobs with the following commands:

```bash
$ sudo ln -s <your_graderfinder_dir>/script/canvas_init /etc/init.d/canvas_init
$ sudo update-rc.d canvas_init defaults
$ sudo /etc/init.d/canvas_init start
```

Replace your_graderfinder_dir with your graderfinder directory. You may want to
check the file **/etc/init.d/canvas_init** with a text editor and make sure 
that it is configured for development instead of production.

## Starting Canvas

Every time that you want to start graderfinder, you will want to run the following 
commands to start all of the servers that graderfinder needs. If you are doing 
this right after installation, they will all probably already be running.

Commands:
```bash
$ sudo service postgresql start
$ sudo service apache2 start
$ sudo /etc/init.d/canvas_init start
$ bundle exec rails s
```

The final command starts graderfinder, you will be able to access it in localhost:3000.

If background jobs are not working, you may want to open another terminal and 
use the command **sudo /etc/init.d/canvas_init run**, which allows them to 
run in the foreground. Remember to close the instance already running beforehand.

## GraderFinder In-Program Setup

After starting GraderFinder, you will want to do the following.

#### Enable Self Registration

* Log in with the email and password you entered during database initialization
* Click on the admin button on the sidebar
* Click on the account you named in database initialization
* Click on the authentication tab in the sidebar of the resulting page
* Scroll down and select All Account Types
* Click on save settings in the bottom right corner

#### Enable Teacher Course Creation

* From the same account click on the settings tab in the sidebar
* Scroll down to the bottom of the page and select Teachers
* Click on update Settings

For more information check Canvas's guides.



