Skip to content

README.md

Latest commit

 

History

History
142 lines (97 loc) · 4.57 KB

README.md

File metadata and controls

142 lines (97 loc) · 4.57 KB

Overview

This is a Ruby on Rails application. It includes:

  • U.S. Web Design System (USWDS) for themeable styling and a set of common components
    • Custom USWDS form builder
  • Integration with AWS services, including
    • Database integration with AWS RDS Postgresql using UUIDs
    • Active Storage configuration with AWS S3
    • Action Mailer configuration with AWS SES
    • Authentication with devise and AWS Cognito
  • Internationalization (i18n)
  • Authorization using pundit
  • Linting and code formatting using rubocop
  • Testing using rspec

📂 Directory structure

As a Rails app, much of the directory structure is driven by Rails conventions. We've also included directories for common patterns, such as adapters, form objects and services.

Refer to the Software Architecture doc for more detail.

Below are the primary directories to be aware of when working on the app:

├── app
│   ├── adapters         # External services
│   │   └── *_adapter.rb
│   ├── controllers
│   ├── forms            # Form objects
│   │   └── *_form.rb
│   ├── mailers
│   ├── models
│   │   └── concerns
│   ├── services         # Shared cross-model business logic
│   │   └── *_service.rb
│   └── views
├── db
│   ├── migrate
│   └── schema.rb
├── config
│   ├── locales          # i18n
│   └── routes.rb
├── spec                 # Tests

💻 Getting started with local development

Prerequisites

  • A container runtime (e.g. Docker or Finch)
    • By default, docker is used. To change this, set the CONTAINER_CMD variable to finch (or whatever your container runtime is) in the shell.
  • An AWS account with a Cognito User Pool and App Client configured
    • By default, the application configures authentication using AWS Cognito

💾 Setup

You can run the app within a container or natively. Each requires slightly different setup steps.

Environment variables

In either case, first generate a .env file:

  1. Run make .env to create a .env file based on shared template.
  2. Variables marked with <FILL ME IN> need to be manually set, and otherwise edit to your needs.

Running in a container

  1. make init-container

Running natively

Prerequisites:

Steps:

  1. make init-native

🛠️ Development

Running the app

Once you've completed the setup steps above, you can run the site natively or within a container runtime.

To run within a container:

  1. make start-container
  2. Then visit http://localhost:3100

To run natively:

  1. make start-native
  2. Then visit http://localhost:3100

Enabling Local Login for Development

For local development (without AWS Cognito credentials), you can use local login via Devise. To enable local login:

  1. Set Rails environment to development:

    RAILS_ENV=development

  2. Enable Devise in development by setting the environment variable::

    USE_DEVISE=true

  3. Set up the database (run migrations)::

    rails db:migrate

  4. Follow the instructions for starting a container then start it::

    make start-container

  5. Visit the sign-up page: Go to http://localhost:3100/users/sign_up and register with any email and password.::

IDE tips

VS Code
Recommended extensions

📇 Additional reading

Beyond this README, you should also refer to the docs/app-rails directory for more detailed info. Some highlights: