GOV.UK Forms Admin

GOV.UK Forms is a service for creating forms. GOV.UK Forms Admin is a an application to handle the administration, design and publishing of those forms. It's a Ruby on Rails application built on a PostgreSQL database.

Before you start

To run the project you will need to install:

• Ruby - we use version 3 of Ruby. Before running the project, double check the [.ruby-version] file to see the exact version.
• Node.js - the frontend build requires Node.js. We use Node 16 LTS versions.
• a running PostgreSQL database

We recommend using a version manager to install and manage these, such as:

• RVM or rbenv for Ruby
• nvm for Node.js
• asdf for both

Getting started

Installing for the first time

# 1. Clone the git repository and change directory to the new folder
git clone git@github.com:alphagov/forms-admin.git
cd forms-admin

# 2. Run the setup script
make setup

make setup runs bin/setup which is idempotent, so you can also run it whenever you pull new changes.

Secrets vs Settings

Refer to the the config gem to understand the file based settings loading order.

To override file based via Machine based env variables settings

cat config/settings.yml
file
  based
    settings
      env1: 'foo'

export SETTINGS__FILE__BASED__SETTINGS__ENV1="bar"

puts Settings.file.based.setting.env1
bar

Refer to the settings file for all the settings required to run this app

Environment variables

Name	Purpose
DATABASE_URL	The URL to the postgres instance (without the database at the end)

Feature flags

This repo supports the ability to set up feature flags. To do this, add your feature flag in the settings file under the features property. eg:

features:
  some_feature: true

You can then use the feature service to check whether the feature is enabled or not. Eg. FeatureService.enabled?(:some_feature).

You can also nest features:

features:
  some:
    nested_feature: true

And check with FeatureService.enabled?("some.nested_feature").

Testing with features

Rspec tests can also be tagged with feature_{name}: true. This will turn that feature on just for the duration of that test.

Running the app

You can run this using the make command:

make serve

Without make, you can either run the development task:

# Run the foreman dev server. This will also start the frontend dev task
bin/dev

or run the rails server:

# Run a local Rails server
bin/rails server

# When running the server, you can use any of the frontend tasks, e.g.:
npm run dev

Running the tests

The tests run with Rspec and can be run via make:

make test

To run specific tests, you can also call rspec directly with

bundle exec rspec

Linting

To run linting with fixes you can use

make lint-fix

Configuration and deployment

The forms-admin app is containerised (see Dockerfile) and can be deployed however you would normally deploy a containerised app.

If you are planning to deploy to GOV.UK PaaS without using the container, you can see how this runs in our Deployment CI action.

Explain how to test the project

# Run the Ruby test suite
bin/rake
# To run the Javascript test suite, run
npm run test

Explain how to add a user to the database

In order to run this project, your database will need to have a user in it. To add one, run the follwing commands:

bin/rails db:seed

Explain how to use GOV.UK Notify

If you want to test the notify function, you will need to get a test API key from the notify service Add it as an environment variable under SETTINGS__GOVUK_NOTIFY__API_KEY= or creating/edit a config/settings/development.local.yml and adding the following to it.

# Settings for GOV.UK Notify api & email templates
govuk_notify:
  api_key: KEY_FROM_NOTIFY_SERVICE

Example emails can be seen locally by visiting http://localhost:3000/rails/mailers

Explain how to use Sentry

We currently have a very basic setup for Sentry in this repo for testing, which we will continue to build upon.

In order to use this:

• first sign up to Sentry and create a new project
• create a file called .env in the root of this repo
• add the Sentry DNS to local settings config file eg. config/settings.local.yml ((more details)[https://github.com/alphagov/forms-admin/blob/fbefdea6de9dbbee75b0f67e4bc9f4e1080acffd/README.md])
• uncomment out the exception triggers in this file
• Build the project and watch the errors come through on Sentry

Support

Raise a Github issue if you need support.

Explain how users can contribute

We welcome contributions - please read CONTRIBUTING.md and the alphagov Code of Conduct before contributing.

License

We use the MIT License.

軟體中文化

本專案為數位部開放原始碼軟體中文化專案項目之一，其中文化與專案應用可參考 Wiki。