forms-runner

Citizen-facing forms using a config driven Node application.

This repository is forked from the old Defra digital form builder. These projects has been adapted to run several configurations on a single instance.

DEFRA's digital form builder is a metadata-driven framework that builds on our robust, enterprise backend tech stack and the new gov.uk frontend Design System and allows form based gov.uk sites to be easily built using a graphical design tool.

The designer is no longer a plugin and is responsible for running itself on default port 3000.

• forms-runner
  • Requirements
    • Node.js
  • Local development
    • Setup
    • Development
    • Production
    • npm scripts
    • File Uploads with Local Development
    • Setting up the CDP Uploader Service
    • Configuring the Uploader URL
    • How it Works
    • Troubleshooting
  • Docker
    • Development image
    • Production image
• Environment variables
  • ⚠️ See config for default values for each environment
• Testing
• Outputs
  • Licence
    • About the licence

Requirements

Node.js

Please install Node.js >= v20. You will find it easier to use the Node Version Manager nvm

To use the correct version of Node.js for this application, via nvm:

$ cd forms-runner
$ nvm use

Local development

for local developers

Setup

Install application dependencies:

$ npm ci

Development

To run the application in development mode run:

$ npm run dev

Production

To mimic the application running in production mode locally run:

$ npm run start

npm scripts

All available npm scripts can be seen in package.json To view them in your command line run:

$ npm run

File Uploads with Local Development

When developing locally with file upload functionality, there are specific configuration requirements to handle CORS (Cross-Origin Resource Sharing) and CSP (Content Security Policy) restrictions.

Setting up the CDP Uploader Service

The forms-runner application needs to use the CDP uploader service which is available in the docker-compose setup from the forms-api-submissions repository:

1. Clone the forms-api-submissions repository
2. Start the required services with docker-compose:

$ cd forms-api-submissions
$ docker-compose up -d

This will start:

• The CDP uploader service on port 7337
• A Nginx reverse proxy on port 7300
• Supporting services (localstack, Redis) needed by the uploader

Configuring the Uploader URL

For file uploads to work properly in local development, you need to use the sslip.io domain that maps to the proxy:

1. Set the UPLOADER_URL in your .env file:

UPLOADER_URL=http://uploader.127.0.0.1.sslip.io:7300

2. Make sure "host.docker.internal" is enabled in your Docker Desktop settings

How it Works

• The docker-compose setup includes an Nginx reverse proxy that routes requests from uploader.127.0.0.1.sslip.io:7300 to the CDP uploader service
• When developing locally, JavaScript CORS restrictions would normally block direct requests to localhost:7337
• The sslip.io domain (a special DNS service that maps IPs to domains) allows your browser to make cross-origin requests
• The application automatically detects local development URLs with localhost:7337 and rewrites them to use the proxy

Troubleshooting

• If file uploads fail, ensure all the required docker services are running
• Verify the proxy is working by testing: http://uploader.127.0.0.1.sslip.io:7300
• Check Docker logs for the cdp-uploader and proxy containers if issues persist

Docker

Development image

Build:

$ docker build --target development --no-cache --tag forms-runner:development .

Run:

$ docker run -p 3000:3000 forms-runner:development

Production image

Build:

docker build --no-cache --tag forms-runner .

Run:

$ docker run -p 3000:3000 forms-runner

Environment variables

If there is a .env file present, these will be loaded in.

An example is shown at the bottom of this section.

⚠️ See config for default values for each environment

Please use a config file instead. This will give you more control over each environment. The defaults can be found in config. Place your config files in runner/config See https://github.com/node-config/node-config#readme for more info.

name	description	required	default	valid	notes
NODE_ENV	Node environment	no		development,test,production
PORT	Port number	no	3009
NOTIFY_TEMPLATE_ID	Notify api key	yes			Template ID required to send form payloads via GOV.UK Notify email service.
NOTIFY_API_KEY	Notify api key	yes			API KEY required to send form payloads via GOV.UK Notify email service.
LOG_LEVEL	Log level	no	debug	trace,debug,info,error
PHASE_TAG	Tag to use for phase banner	no	beta	alpha, beta, empty string
HTTP_PROXY	HTTP proxy to use, e.g. the one from CDP. Currently used for Hapi Wreck.	no
HTTPS_PROXY	HTTPS proxy to use, e.g. the one from CDP. Currently used for Hapi Wreck.	no
NO_PROXY	HTTP proxy to use, e.g. the one from CDP. Currently used for Hapi Wreck.	no
AWS_ACCESS_KEY_ID	AWS key id	yes	dummy
AWS_SECRET_ACCESS_KEY	AWS access key	yes	dummy
SNS_ENDPOINT	Endpoint for SNS messaging	yes
SNS_ADAPTER_TOPIC_ARN	The SNS topic for the submission adapter - in Amazon Resource Name (ARN) format.	yes
SNS_SAVE_TOPIC_ARN	The SNS topic for the save-and-exit - in Amazon Resource Name (ARN) format.	yes

For proxy options, see https://www.npmjs.com/package/proxy-from-env which is used by https://github.com/TooTallNate/proxy-agents/tree/main/packages/proxy-agent.

Example .env contents:

SESSION_COOKIE_PASSWORD="<cookie-password>"
SESSION_COOKIE_TTL=2419200000
REDIS_PASSWORD=my-password
REDIS_USERNAME=default
REDIS_HOST=localhost
REDIS_KEY_PREFIX=forms-runner
MANAGER_URL=http://localhost:3001
BASE_URL=http://localhost:3009
NOTIFY_TEMPLATE_ID=<notify-template-id>
NOTIFY_API_KEY=<notify-api-key>
DESIGNER_URL=http://localhost:3000
SUBMISSION_URL=http://localhost:3002
UPLOADER_BUCKET_NAME=my-bucket
UPLOADER_URL=http://uploader.127.0.0.1.sslip.io:7300
GOOGLE_ANALYTICS_TRACKING_ID='12345'
GOOGLE_ANALYTICS_CONTAINER_ID='abcd'
USE_SINGLE_INSTANCE_CACHE=true
SNS_ENDPOINT="http://localhost:4566"
SNS_ADAPTER_TOPIC_ARN="arn:aws:sns:eu-west-2:000000000000:forms_runner_submission_events"
SNS_SAVE_TOPIC_ARN="arn:aws:sns:eu-west-2:000000000000:forms_runner_events"

Testing

Tests are found inside test/cases. For test scripts, name them ${NAME}.test.js.

Outputs

At the end of a form, there are multiple output types. The schemas for the right json format can be found in the engine repo. Additional steps are required for the different output types.

• Notify
  • A GOV.UK notify is required
  • For each notification you wish to send, a template must be set up. If there are 'personalisations' they must match the configuration

Licence

THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3

The following attribution statement MUST be cited in your products and applications when using this information.

Contains public sector information licensed under the Open Government license v3

About the licence

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.