Compass Portal — 🟥 Edition

dev branch:

main branch: , live app: Heroku

A web application for finding your way, written in Ruby on Rails. Created in the Scalable Software Engineering course at the HPI in Potsdam.

Development Setup

Ensure you have access to a Unix-like environment through:

Your local Linux / MacOS installation
Using the Windows Subsystem for Linux (WSL)
Using a VM, e.g. Virtualbox and Vagrant
Using a docker container

Application Setup

ruby --version Ensure Ruby v2.7.4 using rbenv or RVM
sqlite3 --version Ensure SQLite3 database installation
node --version; yarn --version Ensure Node.js and Yarn installation
bundle --version Ensure Bundler installation (gem install bundler)
bundle config set without 'production' && bundle install Install gem dependencies from Gemfile
yarn install Install JS dependencies from package.json
rails db:migrate Setup the database, run migrations
rails db:reset Seeds the database
rails s Start dev server (default port 3000 required for local HPI OpenID Connect)
bundle exec rspec --format documentation Run the tests (using RSpec framework)

Commands to run after pulling new changes

rails db:migrate
rails db:reset

Developer Guide

Employed Frameworks

Fontawesome icons
Bootstrap for layout and styling
Devise library for authentication
OmniAuth & OmniAuth OpenID Connect for HPI OpenID
FactoryBot to generate test data
Capybara for feature testing
shoulda for additional RSpec matchers

Cheat Sheets

Setup

bundle exec rails db:migrate RAILS_ENV=development && bundle exec rails db:migrate RAILS_ENV=test Migrate both test and development databases
rails assets:clobber && rails webpacker:compile Redo asset compilation

Mapbox

To use the map's routing capabilities, you will need an access token for the Mapbox directions API. Place this token in an environment variable called MAPBOX_ACCESS_TOKEN

Testing

bundle exec rspec Run the full test suite
- --format doc More detailed test output
- -e 'search keyword in test name' Specify what tests to run dynamically
- --exclude-pattern "spec/features/**/*.rb" Exclude feature tests (which are typically fairly slow)
bundle exec rspec spec/<rest_of_file_path>.rb Specify a folder or test file to run
bundle exec rspec --profile Examine run time of tests
Code coverage reports are written to coverage/index.html after test runs (by simplecov)

Linting

rake factory_bot:lint Create each factory and catch any exceptions raised during the creation process (defined in lib/tasks/factory_bot.rake)
bundle exec rubocop Use the static code analyzer RuboCop to find possible issues (based on the community Ruby style guide).
- --auto-correct to fix what can be fixed automatically.
- RuboCop's behavior can be controlled using .rubocop.yml

Debugging

console anywhere in the code to access an interactive console
save_and_open_page within a feature test to inspect the state of a webpage in a browser
rails c --sandbox Test out some code in the Rails console without changing any data
rails dbconsole Starts the CLI of the database you're using
bundle exec rails routes Show all the routes (and their names) of the application
bundle exec rails about Show stats on current Rails installation, including version numbers

Generating

rails g migration DoSomething Create migration _db/migrate/*DoSomething.rb
rails generate takes a --pretend / -p option that shows what will be generated without changing anything

HPI OpenID Connect Configuration

config/initializers/devise.rb contains the OmniAuth OpenID Connect config for the HPI OIDC service
An OpenID Connect client for localhost:3000 is set up for local development. Additional clients registrable at oidc.hpi.de
For deployment OPENID_CONNECT_CLIENT_ID, OPENID_CONNECT_CLIENT_SECRET & OPENID_CONNECT_REDIRECT_URI need to be provided
app/controllers/users/omniauth_callbacks_controller.rb handles data returned by the OIDC service

hpi-swt2/compass-portal-red