Skip to content

Latest commit

 

History

History
269 lines (173 loc) · 12.5 KB

local-development.md

File metadata and controls

269 lines (173 loc) · 12.5 KB
Raw

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:

  3. Test that you have Postgres and Redis running.

  4. Continue to the set up local environment section.

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 yarn build:js for JavaScript, or yarn 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.

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.

If you'd like to work with the previous implementation see the Docker documentation to install the IdP as a container.

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