{"id":20038713,"url":"https://github.com/defra/forms-runner","last_synced_at":"2025-10-10T09:52:40.159Z","repository":{"id":206231310,"uuid":"716151348","full_name":"DEFRA/forms-runner","owner":"DEFRA","description":"Git repository for service forms-runner","archived":false,"fork":false,"pushed_at":"2024-10-29T09:16:18.000Z","size":84917,"stargazers_count":2,"open_issues_count":11,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-10-29T09:58:15.938Z","etag":null,"topics":["cdp","frontend","service"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DEFRA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-08T14:45:21.000Z","updated_at":"2024-10-28T15:33:13.000Z","dependencies_parsed_at":"2023-11-28T18:29:04.042Z","dependency_job_id":"3410d4a1-2bbe-4447-9507-a18d84ecde76","html_url":"https://github.com/DEFRA/forms-runner","commit_stats":null,"previous_names":["defra/forms-runner"],"tags_count":335,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Fforms-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Fforms-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Fforms-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Fforms-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DEFRA","download_url":"https://codeload.github.com/DEFRA/forms-runner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224431708,"owners_count":17310184,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cdp","frontend","service"],"created_at":"2024-11-13T10:32:08.673Z","updated_at":"2025-10-10T09:52:40.149Z","avatar_url":"https://github.com/DEFRA.png","language":"TypeScript","readme":"# forms-runner\n\nCitizen-facing forms using a config driven Node application.\n\nThis repository is forked from [the old Defra digital form builder](https://github.com/DEFRA/digital-form-builder).\nThese projects has been adapted to run several configurations on a single instance.\n\n\u003e DEFRA's digital form builder is a metadata-driven framework that builds on our robust,\n\u003e enterprise backend tech stack and the new gov.uk frontend Design System and allows form based gov.uk sites to be easily\n\u003e built using a graphical design tool.\n\nThe designer is no longer a plugin and is responsible for running itself on default port 3000.\n\n- [forms-runner](#forms-runner)\n  - [Requirements](#requirements)\n    - [Node.js](#nodejs)\n  - [Local development](#local-development)\n    - [Setup](#setup)\n    - [Development](#development)\n    - [Production](#production)\n    - [npm scripts](#npm-scripts)\n    - [File Uploads with Local Development](#file-uploads-with-local-development)\n    - [Setting up the CDP Uploader Service](#setting-up-the-cdp-uploader-service)\n    - [Configuring the Uploader URL](#configuring-the-uploader-url)\n    - [How it Works](#how-it-works)\n    - [Troubleshooting](#troubleshooting)\n  - [Docker](#docker)\n    - [Development image](#development-image)\n    - [Production image](#production-image)\n- [Environment variables](#environment-variables)\n  - [⚠️ See config for default values for each environment](#️-see-config-for-default-values-for-each-environment)\n- [Testing](#testing)\n- [Outputs](#outputs)\n  - [Licence](#licence)\n    - [About the licence](#about-the-licence)\n\n## Requirements\n\n### Node.js\n\nPlease install [Node.js](http://nodejs.org/) `\u003e= v20`. You will find it\neasier to use the Node Version Manager [nvm](https://github.com/creationix/nvm)\n\nTo use the correct version of Node.js for this application, via nvm:\n\n```bash\n$ cd forms-runner\n$ nvm use\n```\n\n## Local development\n\nfor local developers\n\n### Setup\n\nInstall application dependencies:\n\n```bash\n$ npm ci\n```\n\n### Development\n\nTo run the application in `development` mode run:\n\n```bash\n$ npm run dev\n```\n\n### Production\n\nTo mimic the application running in `production` mode locally run:\n\n```bash\n$ npm run start\n```\n\n### npm scripts\n\nAll available npm scripts can be seen in [package.json](./package.json)\nTo view them in your command line run:\n\n```bash\n$ npm run\n```\n\n### File Uploads with Local Development\n\nWhen developing locally with file upload functionality, there are specific configuration requirements to handle CORS (Cross-Origin Resource Sharing) and CSP (Content Security Policy) restrictions.\n\n### Setting up the CDP Uploader Service\n\nThe forms-runner application needs to use the CDP uploader service which is available in the docker-compose setup from the forms-api-submissions repository:\n\n1. Clone the forms-api-submissions repository\n2. Start the required services with docker-compose:\n\n```bash\n$ cd forms-api-submissions\n$ docker-compose up -d\n```\n\nThis will start:\n\n- The CDP uploader service on port 7337\n- A Nginx reverse proxy on port 7300\n- Supporting services (localstack, Redis) needed by the uploader\n\n### Configuring the Uploader URL\n\nFor file uploads to work properly in local development, you need to use the sslip.io domain that maps to the proxy:\n\n1. Set the UPLOADER_URL in your .env file:\n\n```\nUPLOADER_URL=http://uploader.127.0.0.1.sslip.io:7300\n```\n\n2. Make sure \"host.docker.internal\" is enabled in your Docker Desktop settings\n\n### How it Works\n\n- 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\n- When developing locally, JavaScript CORS restrictions would normally block direct requests to localhost:7337\n- The sslip.io domain (a special DNS service that maps IPs to domains) allows your browser to make cross-origin requests\n- The application automatically detects local development URLs with localhost:7337 and rewrites them to use the proxy\n\n### Troubleshooting\n\n- If file uploads fail, ensure all the required docker services are running\n- Verify the proxy is working by testing: http://uploader.127.0.0.1.sslip.io:7300\n- Check Docker logs for the cdp-uploader and proxy containers if issues persist\n\n## Docker\n\n### Development image\n\nBuild:\n\n```bash\n$ docker build --target development --no-cache --tag forms-runner:development .\n```\n\nRun:\n\n```bash\n$ docker run -p 3000:3000 forms-runner:development\n```\n\n### Production image\n\nBuild:\n\n```bash\ndocker build --no-cache --tag forms-runner .\n```\n\nRun:\n\n```bash\n$ docker run -p 3000:3000 forms-runner\n```\n\n# Environment variables\n\nIf there is a .env file present, these will be loaded in.\n\nAn example is shown at the bottom of this section.\n\n### ⚠️ See [config](./src/config/index.ts) for default values for each environment\n\nPlease use a config file instead. This will give you more control over each environment.\nThe defaults can be found in [config](./src/config/index.ts). Place your config files in `runner/config`\nSee [https://github.com/node-config/node-config#readme](https://github.com/node-config/node-config#readme) for more info.\n\n| name                  | description                                                                      | required | default |            valid            |                                                            notes                                                            |\n| --------------------- | -------------------------------------------------------------------------------- | :------: | ------- | :-------------------------: | :-------------------------------------------------------------------------------------------------------------------------: |\n| NODE_ENV              | Node environment                                                                 |    no    |         | development,test,production |                                                                                                                             |\n| PORT                  | Port number                                                                      |    no    | 3009    |                             |                                                                                                                             |\n| NOTIFY_TEMPLATE_ID    | Notify api key                                                                   |   yes    |         |                             |   Template ID required to send form payloads via [GOV.UK Notify](https://www.notifications.service.gov.uk) email service.   |\n| NOTIFY_API_KEY        | Notify api key                                                                   |   yes    |         |                             |     API KEY required to send form payloads via [GOV.UK Notify](https://www.notifications.service.gov.uk) email service.     |\n| LOG_LEVEL             | Log level                                                                        |    no    | debug   |   trace,debug,info,error    |                                                                                                                             |\n| PHASE_TAG             | Tag to use for phase banner                                                      |    no    | beta    |  alpha, beta, empty string  |                                                                                                                             |\n| FEEDBACK_LINK         | Link to display in the phase banner when asking for feedback.                    |    no    |         |                             | Used for an anchor tag's href. To display an email link, use a 'mailto:dest@domain.com' value. Else use a standard website. |\n| HTTP_PROXY            | HTTP proxy to use, e.g. the one from CDP. Currently used for Hapi Wreck.         |    no    |         |                             |                                                                                                                             |\n| HTTPS_PROXY           | HTTPS proxy to use, e.g. the one from CDP. Currently used for Hapi Wreck.        |    no    |         |                             |                                                                                                                             |\n| NO_PROXY              | HTTP proxy to use, e.g. the one from CDP. Currently used for Hapi Wreck.         |    no    |         |                             |                                                                                                                             |\n| AWS_ACCESS_KEY_ID     | AWS key id                                                                       |   yes    | dummy   |                             |                                                                                                                             |\n| AWS_SECRET_ACCESS_KEY | AWS access key                                                                   |   yes    | dummy   |                             |                                                                                                                             |\n| SNS_ENDPOINT          | Endpoint for SNS messaging                                                       |   yes    |         |                             |                                                                                                                             |\n| SNS_ADAPTER_TOPIC_ARN | The SNS topic for the submission adapter - in Amazon Resource Name (ARN) format. |   yes    |         |                             |                                                                                                                             |\n| SNS_SAVE_TOPIC_ARN    | The SNS topic for the save-and-exit - in Amazon Resource Name (ARN) format.      |   yes    |         |                             |                                                                                                                             |\n\nFor 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.\n\nExample .env contents:\n\n```\nSESSION_COOKIE_PASSWORD=\"\u003ccookie-password\u003e\"\nSESSION_COOKIE_TTL=2419200000\nREDIS_PASSWORD=my-password\nREDIS_USERNAME=default\nREDIS_HOST=localhost\nREDIS_KEY_PREFIX=forms-runner\nMANAGER_URL=http://localhost:3001\nBASE_URL=http://localhost:3009\nNOTIFY_TEMPLATE_ID=\u003cnotify-template-id\u003e\nNOTIFY_API_KEY=\u003cnotify-api-key\u003e\nFEEDBACK_LINK=http://test.com\nDESIGNER_URL=http://localhost:3000\nSUBMISSION_URL=http://localhost:3002\nUPLOADER_BUCKET_NAME=my-bucket\nUPLOADER_URL=http://uploader.127.0.0.1.sslip.io:7300\nGOOGLE_ANALYTICS_TRACKING_ID='12345'\nGOOGLE_ANALYTICS_CONTAINER_ID='abcd'\nUSE_SINGLE_INSTANCE_CACHE=true\nSNS_ENDPOINT=\"http://localhost:4566\"\nSNS_ADAPTER_TOPIC_ARN=\"arn:aws:sns:eu-west-2:000000000000:forms_runner_submission_events\"\nSNS_SAVE_TOPIC_ARN=\"arn:aws:sns:eu-west-2:000000000000:forms_runner_events\"\n```\n\n# Testing\n\nTests are found inside `test/cases`. For test scripts, name them `${NAME}.test.js`.\n\n# Outputs\n\nAt the end of a form, there are multiple output types. The schemas for the right json format can be found in the engine repo.\nAdditional steps are required for the different output types.\n\n- Notify\n  - A GOV.UK [notify](https://www.notifications.service.gov.uk) is required\n  - For each notification you wish to send, a template must be set up. If there are 'personalisations' they must match the configuration\n\n## Licence\n\nTHIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:\n\n\u003chttp://www.nationalarchives.gov.uk/doc/open-government-licence/version/3\u003e\n\nThe following attribution statement MUST be cited in your products and applications when using this information.\n\n\u003e Contains public sector information licensed under the Open Government license v3\n\n### About the licence\n\nThe Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable\ninformation providers in the public sector to license the use and re-use of their information under a common open\nlicence.\n\nIt is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefra%2Fforms-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdefra%2Fforms-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefra%2Fforms-runner/lists"}