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 18 LTS versions.
- a running PostgreSQL database
We recommend using a version manager to install and manage these, such as:
Getting started
Installing for the first time
# 1. Clone the git repository and change directory to the new folder
git clone [email protected]:alphagov/forms-admin.git
cd forms-admin
# 2. Run the setup script
./bin/setupRunning the app
You can either run the development task:
# Run the foreman dev server. This will also start the frontend dev task
bin/devor 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 devDevelopment tools
Running the tests
The app tests are written with rspec-rails and can be run with:
bundle exec rspecThere are also unit tests for JavaScript code (look for files named *.test.js), written with Jest. These can be run with:
npm run testLinting
We use RuboCop GOV.UK for linting code, to autocorrect issues run:
bundle exec rubocop -AWe also use the i18n-tasks tool to keep our locales files in a consistent order. When the tests run they will check if the locale files are normalised, and fail if they are not. To fix the locale files automatically you can run:
bundle exec i18n-tasks normalizeOn GitHub pull requests we also check our dependencies for security issues using [bundler-audit], you can run this locally with:
bundle auditRunning tasks with rake
We have a Rakefile that is setup to follow the GOV.UK conventions for Rails applications.
To lint your changes and run tests with one command you can run
bundle exec rakeSetting up the database
In order to run this project, your database will need to have a user in it. The bin/setup script will normally take care of this for you, but if you need to quickly add some users you can do so by loading the database seed:
bin/rails db:seedChanging configuration
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
barRefer 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: trueYou 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: trueAnd 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.
Configuring GOV.UK Notify
We use GOV.UK Notify to send emails from our apps.
If you want to test the Notify functionality locally, 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 add it to a local config file:
# config/settings.local.yml
# Settings for GOV.UK Notify api & email templates
govuk_notify:
api_key: <API key from Notify>
Example emails can be seen locally by visiting http://localhost:3000/rails/mailers
Configuring Sentry
We use Sentry to catch exceptions in production apps and alert us.
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 locally you will need to sign up to Sentry and create a new project. Then add the Sentry DSN to your environment as SETTINGS__SENTRY__DSN, or add it to a local config file:
# config/settings.local.yml
sentry:
DSN: <DSN from Sentry>
If you want to deliberately raise an exception to test, uncomment out the triggers in the Sentry initializer script. Whenever you run the app errors will be raised and should also come through on Sentry.
Deployment
The forms-admin app is containerised (see Dockerfile) and can be deployed however you would normally deploy a containerised app.
We host our apps using Amazon Web Services, you can read about how deployments happen on our team wiki, if you have access.
Logging
- HTTP access logs are managed using Lograge and configured within the application config
- The output format is JSON using the JsonLogFormatter to enable simpler searching and visbility especially in Splunk.
- DO NOT use log_tags since it breaks the JSON formatting produced by Lograge.
Updating Docker files
To update the version of Alpine Linux and Ruby used in the Dockerfile, use the update_app_versions.sh script in forms-deploy
Support
Raise a Github issue if you need support.
How to contribute
We welcome contributions - please read CONTRIBUTING.md and the alphagov Code of Conduct before contributing.
License
We use the MIT License.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent