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.
git clone git@github.com:berkeley-cdss/flextensions.git
cd flextensions
Install mise, such as brew install mise or any other ruby language manager.
Either Ruby 3.3 or 3.4 will work. CI runs 3.4, but the deployed Elastic
Beanstalk platform runs Ruby 3.3, so the app must remain compatible with
both (the Gemfile allows >= 3.3, < 3.5):
mise use ruby@3.4
bundle install --without production
brew install postgresql
# Optionally, if it does not start by default
brew services start postgresql@16
/opt/homebrew/opt/postgresql@16/bin/postgres -D /opt/homebrew/var/postgresql@16
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
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
.env.sample to .env.admin on the sidebar on the left, then Click UC Berkeley SandboxDeveloper Keys section on the left sidebar, add an API key.Redirect_URI should be the same as your APP_HOST in .env (See the code block below)CANVAS_CLIENT_ID should be something like 2653xxxxxxxxx; the APP_KEY should be the secret corresponding to it.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")
CANVAS_CLIENT_ID (Ask the instructor for this. Used for authentication token request)
APP_HOST (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
run rails db:setup
To start the server locally, run rails server . You should be able to land to the login page.
Hypershield is a tool which allows admins to query data, without relevaing sensitive tokens.
You may need to run:
rake hypershield:refresh:dry_run
Background jobs run on GoodJob, backed by
the app’s Postgres database. In production and staging GoodJob runs inside the
Puma process (config.good_job.execution_mode = :async), so Elastic Beanstalk does
not need a worker tier, a Procfile worker entry, or an EC2 crontab.
Recurring jobs are defined once, in config/application.rb under
config.good_job.cron, and executed by GoodJob’s own cron thread wherever
config.good_job.enable_cron is true (production and staging). Times use an
explicit America/Los_Angeles timezone field, so they do not depend on the
server clock, and GoodJob’s unique index on (cron_key, cron_at) means an
occurrence is enqueued once even if several processes are running.
| Cron key | Schedule | Job |
|---|---|---|
pending_digests_hourly |
Top of every hour | PendingRequestsNotificationJob('hourly') |
pending_digests_daily |
4:00 PM PT daily | PendingRequestsNotificationJob('daily') |
pending_digests_weekly |
4:00 PM PT Thursdays | PendingRequestsNotificationJob('weekly') |
Each run emails the courses whose Pending Request Notifications setting matches that frequency and that currently have pending requests.
Admins can inspect queues, schedules and past runs at /admin/good_job. To send a
digest by hand (locally, or to backfill after downtime):
bundle exec rake 'notifications:send_pending_digests[hourly]'
Set GOOD_JOB_ENABLE_CRON=false on an instance to stop it from enqueueing
recurring jobs — for example when moving them to a dedicated worker started with
bundle exec good_job start --enable-cron.
Staging and production run on the Ruby 3.3 on Amazon Linux 2023 platform, built
by CodeBuild (buildspec.yml) and deployed by CodePipeline.
ProcfileThe repository intentionally ships no root Procfile. When one is absent,
Elastic Beanstalk generates the default
for the Ruby platform:
web: bundle exec puma -C /opt/elasticbeanstalk/config/private/pumaconf.rb
That platform-provided pumaconf.rb binds Puma to the Unix socket
/var/run/puma/my_app.sock, which is what the platform’s nginx config proxies
to (upstream my_app { server unix:///var/run/puma/my_app.sock; }). Note that
this is not the generic PORT / TCP-5000 convention used by the Go and Java SE
platforms — the Ruby platform does not set a PORT environment variable, so
a Procfile line like web: bundle exec rails server -p $PORT starts Rails with
an empty --port argument and the web process dies at boot with
Thor::MalformattedArgumentError: No value provided for option '--port'.
If you ever do need a custom Procfile, two platform behaviours are worth
knowing:
^[A-Za-z0-9_-]+:\s*[^\s].*$. A # comment makes the whole file invalid, and
Elastic Beanstalk silently falls back to its generated default — so a
Procfile with comments appears to work while none of its lines are
actually running. Document the process model here instead.web process must bind unix:///var/run/puma/my_app.sock, not a TCP port,
or nginx will return 502.Because GoodJob runs in-process (see Background and Scheduled Jobs),
the single platform-managed web process is all this app needs.
APP_HOST
CANVAS_CLIENT_ID
CANVAS_URL
# Active Record Encryption Values
# SMTP Email Settings
heroku login
git remote add golden https://git.heroku.com/flextensions.git
git push golden main
| 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 |
| 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 |
Accessibility auditing is wired up as an after-hook in both test frameworks,
so any test opted in with the a11y/@a11y tag has its final rendered page
audited with axe-core automatically – individual tests do not need to call the
axe matcher themselves.
spec/support/accessibility_helper.rb): every feature spec tagged
:a11y runs expect(page).to be_axe_clean against the current page after the
example. See spec/features/accessibility_spec.rb for usage.features/support/axe_helper.rb): every scenario tagged @a11y
is audited after it runs. Because axe-core needs a real browser, @a11y
scenarios run under the JavaScript driver.~ (RSpec) or not (Cucumber) to exclude tagsand/or: --tags '@javascript and not @skip'<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-
For how Flextensions reads Canvas assignment due dates and reads/writes
assignment overrides (and the gotchas around override_assignment_dates, the
25-date all_dates limit, and /date_details), see
Canvas Dates API notes (docs/Canvas_Dates_API.md).
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:
