Developer Guide

Overview

Touchpoints is a Ruby on Rails app that is deployed on Cloud.gov.

This page provides instructions for a variety of developer tasks. Note that all the instructions assume that the developer is on MacOS.

Running Touchpoints in a local development environment

The minimal runnable instance of Touchpoints requires 3 components - Postgres, Redis and the Touchpoints app itself. The docker-compose file that comes with this repo runs this minimal instance. However, the following instructions assume that the developer is only using Docker for the dependent services (Postgres, Redis) while the app itself (the component under active development) runs locally.

Prerequisites

• Docker Desktop
• Ruby 3.1.4
• Homebrew is also helpful

Preliminary setup

1. Clone the repo.
2. Copy .env.sample to .env.development.
3. Run bundle install to install Ruby gems.

When you run bundle install, you may see an error like Gem::Ext::BuildError: ERROR: Failed to build gem native extension. that complains about a missing PostgreSQL client library. If you have Postgres installed locally, you should not see this error, but we're assuming you're running Postgres in Docker. The Ruby pg gem doesn't require a complete Postgres installation, so you can get away with just installing the client library libpq. Follow the instructions printed in the bundler output to do so and then run bundle install again.

Set up authentication

In production, Touchpoints uses Login.gov for authentication. In development, you can either use a sandbox version of Login.gov or you can integrate with Github authentication. You can also set up both methods but note that a given email address (i.e., user) can only be associated with one or the other methods.

Which to use?

GitHub authentication is easier to set up. Login.gov sandbox is closer to the production set-up.

Authenticate with Login.gov sandbox

Follow these instructions to create an account for yourself in the Login.gov sandbox. Continue following the instructions to create a team (containing just yourself) and an app. Use these settings:

• Authentication Protocol: OpenID Connect Private Key JWT
• Attribute Bundle: Check 'email'
• Redirect URIs: http://localhost:3000/users/auth/login_dot_gov/callback
• Certificate: Follow the instructions to create and upload a certificate.

Once the app has been created, update .env.development:

• LOGIN_GOV_CLIENT_ID=the issuer field listed for your app
• LOGIN_GOV_PRIVATE_KEY=the private key for the cert you generated

Authenticate with Github

Follow these instructions to create an OAuth app in GitHub. Use these settings:

• Authorization callback URL: http://localhost:3000/users/auth/github/callback
• Enable Device Flow: False

Once the app has been created, copy the client ID and client secret to the matching variables in .env.development.

Configure your authenticated users

For either of the authentication methods, you will be asked to log in with an email address. For whatever email you plan to use, set that email address as DEVELOPER_EMAIL_ADDRESS in .env.development. When you seed the database in a later step, this email address will be added to the users table as an admin.

Initialize the database

Start the database containers:

docker compose up -d db redis

Initialize Postgres - create all databases, load all schemas, and initialize with the seed data:

rails db:setup

# equivalent to rails db:create & rails db:schema:load & rails db:seed

Run the Touchpoints application

rails server

Touchpoints should now be running at http://localhost:3000.

Other developer tasks

Running the tests

Touchpoints uses RSpec as its testing framework. Our testing strategy is described here.

To run the tests locally, check that the Postgres and Redis containers are running in Docker and then execute:

# Initialize the test database
RAILS_ENV=test rails db:setup

# Run the tests
rspec

Linting the code

• Run the script ./rubocop_autocorrect.sh to fix standardize layout, style, and code using Rubocop.
• Copy the file ./pre-commit to your .git/hooks/ folder within the project to ensure changed files adhere to project standards, prior to commit.
• To get a commit through without running that pre-commit hook, use the --no-verify option.

Updating USWDS

Touchpoints employs a customized version of USWDS for styling. Upgrading to a new version of USWDS requires the following steps:

1. Run yarn upgrade @uswds/uswds --latest --exact to get the latest version of USWDS.
2. Run npx gulp updateUswds to update all assets for the Touchpoints app to the new version of USWDS. This update includes a step that generates CSS from the USWDS SASS files along with our project customizations. See uswds-compiler documentation for more details.
3. Run npx gulp buildWidgetAssets to update all assets for the Touchpoints widget to the new version of USWDS.

These commands can be run together using npm run updateUswds.