flextensions

Standing Up the Application

This guide walks you through setting up the Flextensions app on your local machine and on your Heroku server and preparing it for development and deployment.

Set Up in Your Local Environment

Clone the Repository

git clone git@github.com:berkeley-cdss/flextensions.git
cd flextensions

Set Up Ruby Environment

Linux / WSL (If you are on Windows, please use WSL instead).

Make sure you are using Ruby 3.3.0:

rvm use 3.3.0

If the above command errors because rvm 3.3.0 is not installed, then install it instead:

rvm install 3.3.0

Macs

Similar to rvm for Linux, use asdf instead of RVM to make sure you are using the right version of Ruby on Rails（3.3.0). If you are unsure how to do this, please follow Athe ssignment [Cue-to-Cue Dry Run of the Tool-Rich Agile Workflow] on bcourses.

Install dependencies:

bundle install --without production

Install PostgreSQL

On macOS:

brew install postgresql
brew services start postgresql@14
/opt/homebrew/opt/postgresql@14/bin/postgres -D /opt/homebrew/var/postgresql@14

On Linux / WSL:

sudo apt install postgresql
# Create a postgres user.
sudo su-postgres #(to get into postgres shell)
createuser --interactive --pwprompt #(in postgres shell)0
Save DB_USER and DB_PASSWORD fields in the .env file.
#Start postgres if necessary. 
pg ctlcluster 12 main start 
#Note: if you are using WSL2 on windows, the command to start postares is 
sudo seryice posteresal start

Install Overmind

In order to stand up the server you must first install Overmind. Development has been tested with overmind 2.4.0

With Overmind, you can run $make dev or $make

Environment Variables

Create a new file named .env under the root directory of Flextensions app.
Get client secrets from your Instructure sandbox account. Flextensions uses bcourses (Canvas) third-party authentication. For developers, you need a sandbox admin account to generate client ID and secrets for your app when using Canvas authentication APIs.
1. Log into your sandbox admin account. Contact your instructor if you do not have one.
2. Click admin on the sidebar on the left, then Click UC Berkeley Sandbox
3. Go to the Developer Keys section on the left sidebar, add an API key.
4. Fill in each field with your own information. Redirect_URI should be the same as your CANVAS_REDIRECT_URI in .env (See the code block below)
5. For your environment variables, the CANVAS_CLIENT_ID should be something like 2653xxxxxxxxx; the APP_KEY should be the secret corresponding to it.

Setup the following ENV variables in your .env file:

DB_PORT (default: 5432)
DB_USER (default: postgres)
DB_PASSWORD (default: password)
DB_NAME (default: postgres)
CANVAS_URL (No default, but if you are using instructure sandbox then it should be set as "https://www.instructure.com/canvas?domain=canvas")
RAILS_MASTER_KEY (Elaborated more in later sections)
CANVAS_CLIENT_ID (Ask the instructor for this. Used for authentication token request)
APP_KEY (Ask the instructor for this. Used for authentication token request)
CANVAS_REDIRECT_URI (URL to the app itself. If you are standing up the app locally then it should be "http://localhost:3000")

In the root directory of Flextensions app, run

make env

RAILS MASTER KEY

Flextensions app uses a RAILS_MASTER_KEY to encrypt the database. The master key is not made public for security reasons. Please contact your instructor or check slack messages for the link to our master key setup tutorial.

Rails Database

run rails db:create and then rails db:migrate.

To start the server locally, run rails server . You should be able to land to the login page.

Standing Up the Application on Heroku

Setup the following ENV variables in heroku, with the same values in your local .env file.
```
APP_KEY
CANVAS_REDIRECT_URI #Replace this with the uri to your heroku app.
CANVAS_CLIENT_ID
CANVAS_URL
RAILS_MASTER_KEY
```
Redirect uri should have domain-name/auth/callback
Pushing branch Iter4 to flextensions heroku

heroku login

git remote add golden https://git.heroku.com/flextensions.git

git push golden main

https://sp25-02-flextensions-4f5b4fbccd7f.herokuapp.com

Testing

Test Commands

Test Type	Command
RSpec Tests (no a11y)	`bundle exec rspec --tag '~a11y'`
Cucumber Tests (no a11y)	`bundle exec cucumber --tags 'not @a11y and not @skip'`
All Regular Tests	`bundle exec rspec --tag '~a11y' && bundle exec cucumber --tags 'not @a11y and not @skip'`
Accessibility Tests (RSpec)	`bundle exec rspec --tag a11y`
Accessibility Tests (Cucumber)	`bundle exec cucumber --tags @a11y`
All Tests (including a11y)	`bundle exec rspec && bundle exec cucumber --tags 'not @skip'`
Lint Code (RuboCop)	`bundle exec rubocop`
Auto-fix Lint Issues	`bundle exec rubocop -A`
Validate Swagger API	`npx @redocly/cli lint app/assets/swagger/swagger.json --extends=minimal`

Test Tags

Tag	Description
`@javascript`	Tests requiring JS execution in browser (uses Selenium/headless browser), without the tag, it will run in rack, which is exponentially faster to test
`@a11y`	Accessibility tests using axe-core to verify WCAG compliance
`@skip`	Temporarily skipped tests (known failures)
`@wip`	Work In Progress tests still under development

Tips

Use ~ (RSpec) or not (Cucumber) to exclude tags
Combine tags in Cucumber with and/or: --tags '@javascript and not @skip'
Run accessibility tests separately (slower)

Conventions

Testing convention css selector - <a class="nav-link testid-username" href="#"> Tashrique </a>

Notice the testid-usernameWe will be using this style in class to grab elements from DOM to test.

Please don’t remove any class that starts with testid-

Notes

There are now two separate instances of Canvas, each with it’s own triad of prod/test/beta environments:

We recommend developing in this order:

ucberkeleysandbox.instructure.com (no risk) - this is the one for which this repo currently has oauth2 keys (secrets)
bcourses.test.instructure.com (no risk of impacting courses, but contains real data)
bcourses.berkeley.edu

This site is open source. Improve this page.