Skip to content

Latest commit

 

History

History
300 lines (184 loc) · 14.7 KB

local-development.md

File metadata and controls

300 lines (184 loc) · 14.7 KB

Local Development

Installing on your local machine

This installation method is meant for those who are familiar with setting up local development environments on their machines. If you encounter errors, see Troubleshooting.

We recommend using Homebrew, rbenv, nvm or other version management tooling to install the below dependencies; while we don't anticipate changing these frequently, this will ensure that you will be able to easily switch to different versions as needed.

Dependencies

Installing the packages differs slightly if you're on a macOS or a different OS.

If using macOS:

  1. Install rbenv (lets you install and switch between different versions of Ruby)
  2. Install Ruby. Choose the version in the .ruby-version file
  3. Skip to the set up local environment section. Your other dependencies will be installed in that step.

If not using macOS:

  1. To start, make sure you have the following dependencies installed and a working development environment:

  2. You will need to install openssl version 1.1:

    • Run brew install openssl@1.1

  3. Test that you have Postgres and Redis running.

  4. Continue to the set up local environment section.

If using Devenv.sh:

  1. Install nix. We recommend using the Experimental Nix installer, as it works well across multiple operating systems:

    curl -L https://github.com/NixOS/experimental-nix-installer/releases/download/0.27.0/nix-installer.sh | sh -s -- install --ssl-cert-file /etc/ssl/certs/ca-certificates.crt --no-add-channel
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgs
nix-channel --update --verbose
echo "trusted-users = root $(whoami)" | sudo tee /etc/nix/nix.conf
sudo launchctl kickstart -k system/org.nixos.nix-daemon

  2. If using macOS, install a newer version of bash:

    nix-env --install --attr bashInteractive -f https://github.com/NixOS/nixpkgs/tarball/nixpkgs-unstable

  3. Install devenv:

    nix-env --install --attr devenv -f https://github.com/NixOS/nixpkgs/tarball/nixpkgs-unstable

  4. Activate your development environment, and launch Postgres and Redis:

    devenv shell
devenv up -d

Set up local environment

  1. Run the following command to set up your local environment:

    make setup

    This command copies sample configuration files, installs required gems and brew packages (if using macOS), and sets up the database. Check out our Makefile commands to learn more about what this command does.

  2. Now that you have you have everything installed, you can run the following command to start your local server:

    make run

    You should now be able to go to open up your favorite browser, go to localhost:3000 and see your local development environment running.

Simulating a partner authentication request

Typically, a person who uses Login.gov will arrive from a partner application, and their experience on Login.gov will be customized to incorporate the name and logo of the partner. They will also be asked to consent to share their information with the partner before being sent back.

To simulate a true end-to-end user experience, you can either...

Running the sample application requires a few additional steps, but can be useful if you want to test the experience of a user being redirected to an external site, or if you want to configure different options of the authentication request, such as AAL or IAL.

PIV/CAC authentication using PKI service

The IdP's PIV/CAC features are not maintained as part of this codebase, and are instead managed in a separate application whose code can be found in the 18F/identity-pki GitHub repository.

In local development, you have two choices for working with PIV/CAC:

  • Follow the setup instructions for identity-pki and run the application in parallel to the IdP. The IdP is configured by default to connect to the default port of a locally-running identity-pki instance (http://localhost:8443)
  • Override application configuration to set identity_pki_disabled: true in your local config/application.yml. This will allow you to simulate PKI results without having an instance running, and can be useful for testing different error scenarios or distinct PIV/CAC subject identifiers.

Running tests locally

Login.gov uses the following tools for our testing:

To run our full test suite locally, use the following command:

make test

Running the full test suite takes a very long time, so usually you'll want to run the individual test files or folders you're interested in:

bundle exec rspec spec/i18n_spec.rb

Check out our Makefile commands and learn more about how you can customize this command to run specific tests using rspec: https://github.com/18F/identity-idp/blob/main/Makefile#L41

To test a specific spec file with rspec, you may need to add the following configuration to /config/application.yml so the tests do not crash:

test:
  rack_timeout_service_timeout_seconds: 9_999_999_999

Showing the Browser

By default, the acceptance specs use a headless browser for speed. If you want to see the browser, run the specs with SHOW_BROWSER=true environment variable:

SHOW_BROWSER=true bundle exec rspec spec/features/

[!TIP] Only JavaScript-enabled tests are configured to run using a real browser, since browser tests are slow to run. If you have a feature test you want to run in a real browser, you can add the js metadata to your test to mark it as requiring JavaScript:

it 'does something', :js do … end

Skipping asset compilation in feature tests

To ensure that tests are run using the latest source code, JavaScript-enabled feature specs will compile all JavaScript and stylesheets in local development. This can be time-consuming if you're repeatedly running the same tests, so you can choose to skip the build by passing the SKIP_BUILD=true environment variable:

SKIP_BUILD=true bundle exec rspec spec/features

Since the automatic build is meant to act as a safeguard to prevent stale assets from being used, disabling it will mean you're responsible for running the build any time JavaScript or Sass source files are changed. You can do this by running npm run build:js for JavaScript, or npm run build:css for stylesheets.

Viewing email messages

In local development, the application does not deliver real email messages. Instead, we use a tool called letter_opener to display messages.

Disabling letter opener new window behavior

Letter opener will open each outgoing email in a new browser window or tab. In cases where this will be annoying the application also supports writing outgoing emails to a file. To write emails to a file add the following config to the development group in config/application.yml:

development:
  development_mailer_deliver_method: file

After restarting the app emails will be written to the tmp/mails folder.

Email template previews

To view email templates with placeholder values, visit http://localhost:3000/rails/mailers/ to see a list of template previews.

SMS text previews

SMS texts for QA are live in actionmailer, just like the email template previews. To go directly to the list of texts, visit http://localhost:3000/rails/mailers/user_sms_text_mailer. From here, you will see a list of text messages available for preview. All text messages are available in all languages that we support (French, Spanish, and Mandarin Chinese.)

Adding SMS texts for preview

To add text messages for SMS preview:

  • In app/mailers/user_sms_text_mailer.rb, create a method that describes the purpose of the text. Add the mail_to method for each sample text. This is important because this is where the text populates on the SmsTextPreview list. If you do not add mail_to in the method, the sample text will not be displayed.
  • In the app/views/user_sms_text_mailer folder, create a view file for the text message as a \*.text.erb file. Add the text that you want to see in the SMS message.
  • In spec/mailers/previews/user_sms_test_mailer_preview.rb, create a method that calls the method that you created in app/mailers. You will need these methods to create tests in the /spec file.
  • In spec/mailers/user_sms_text_mailer_spec.rb, add a test for the method that you have added in the preview spec. Test to make sure that the content is rendered as expected, especially for the text that has dynamic values.

Translations

Login.gov translates the IdP into English, French and Spanish. To help us handle extra newlines and make sure we wrap lines consistently, we have a script that helps format YAML consistently. After importing translations (or making changes to the *.yml files with strings), run this for the IdP app:

make normalize_yaml

If you would like to preview the translations on a particular page, use the Language dropdown in the footer of the website. To manually override a locale, add the locale as the first segment of the URL:

Viewing outbound SMS messages and phone calls

To see outbound SMS messages and phone calls, visit http://localhost:3000/test/telephony.

Viewing RISC push notifications

To view RISC Security Events push notifications delivered by the application, visit http://localhost:3000/test/push_notification.

Setting up Geolocation

Login.gov uses MaxMind Geolite2 for geolocation. To test geolocation locally, you will need to add a copy of the Geolite2-City database to the IdP.

The Geolite2-City database can be downloaded from MaxMind's site at https://dev.maxmind.com/geoip/geoip2/geolite2/.

Download the GeoIP2 Binary and save it at geo_data/GeoLite2-City.mmdb. The app will start using that Geolite2 file for geolocation after restart.

Testing in a virtual machine

By default, the application binds to localhost. To test on a local network device or within a virtual machine, you can bind to 0.0.0.0. Before development, use the following instructions based on your machine's operating system.

  1. From the "Network" tab on:

  • Monterey and below

    Once on "Network" system settings, your IP address is shown under "Status: Connected" label.

  • Ventura

    Select "Wi-Fi" or "Ethernet". This option will change based on how you are connected to the internet. From there, click "Details".

    IP addresses often take the format of 192.168.1.x or 10.0.0.x.

  1. In config/application.yml, add domain_name and mailer_domain_name keys under development, like so:

    development:
  domain_name: <your-local-ip>:3000
  mailer_domain_name: <your-local-ip>:3000

    replacing <your-local-ip> with the address you found in Step 1

  2. Start the server using the command HOST=0.0.0.0 make run

  3. From on the same network, visit the application using the domain name configured in the second step (for example, http://192.168.1.131:3000).

Testing on a mobile device

Moble device instructions are here

Testing the application over HTTPS

make run-https

Or, to run on a different host:

HOST=0.0.0.0 make run-https

The run-https Makefile target will automatically provision a self-signed certificate and start the built-in Rails server.

You can now navigate to https://localhost:3000/ .

It's likely that you'll be prompted with a screen with warnings about an unsafe connection. This is normal. Find the option on the screen to bypass the warning. It may be hidden under an "Advanced" toggle button. In Chrome, you may not see an option to bypass this screen. In these situations, type the letters thisisunsafe while the screen is active, and you will be redirected automatically.

Installing with Docker

There was an initial attempt to dockerize the IDP but it is currently deprecated, mostly non-functional, and not maintained. There is ongoing work to make the IDP more 12 Factor compliant which will eventually lead to better support for containerization.

Linting

Run make lint to look for errors; make lintfix can repair some linting errors.

Configuration variables

Default configuration values — like feature flags, timeout settings, and third-party connection details — are found in config/application.yml.default. From these defaults the file config/application.yml is created during make setup for use during local development. See the handbook.

In deployed environments, configuration values are managed with the app-s3-secret script. See the handbook.

Running jobs

We run background jobs / workers with ActiveJob and GoodJob. You shouldn't normally have to start it manually because make run runs the Procfile, which handles it. The manual command is: bundle exec good_job start

Processes can be configured to run via async jobs or synchronously using flags such as deliver_mail_async in application.yml