{"id":20038697,"url":"https://github.com/defra/forms-manager","last_synced_at":"2026-02-04T17:31:44.277Z","repository":{"id":225834380,"uuid":"766989659","full_name":"DEFRA/forms-manager","owner":"DEFRA","description":"Git repository for service forms-manager","archived":false,"fork":false,"pushed_at":"2026-02-02T11:51:21.000Z","size":4163,"stargazers_count":0,"open_issues_count":16,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-03T01:23:37.548Z","etag":null,"topics":["backend","cdp","node","service"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-03-04T14:03:32.000Z","updated_at":"2026-01-27T17:04:18.000Z","dependencies_parsed_at":"2024-03-04T15:59:26.646Z","dependency_job_id":"b3a71df9-cd6b-4660-95c3-4bf5c5b41e89","html_url":"https://github.com/DEFRA/forms-manager","commit_stats":null,"previous_names":["defra/forms-manager"],"tags_count":324,"template":false,"template_full_name":null,"purl":"pkg:github/DEFRA/forms-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Fforms-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Fforms-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Fforms-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Fforms-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DEFRA","download_url":"https://codeload.github.com/DEFRA/forms-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Fforms-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29091824,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-04T03:31:03.593Z","status":"ssl_error","status_checked_at":"2026-02-04T03:29:50.742Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["backend","cdp","node","service"],"created_at":"2024-11-13T10:32:03.648Z","updated_at":"2026-02-04T17:31:44.250Z","avatar_url":"https://github.com/DEFRA.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# forms-manager\n\nCore delivery platform Node.js Backend Template.\n\n- [forms-manager](#forms-manager)\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    - [Database Migrations](#database-migrations)\n      - [Production](#production-1)\n      - [Local Development](#local-development-1)\n        - [Option 1: Using Docker (Recommended)](#option-1-using-docker-recommended)\n        - [Option 2: Manual Migration Commands](#option-2-manual-migration-commands)\n  - [API endpoints](#api-endpoints)\n  - [Calling API endpoints](#calling-api-endpoints)\n    - [Postman](#postman)\n  - [Docker](#docker)\n    - [Development image](#development-image)\n    - [Production image](#production-image)\n  - [Integration testing](#integration-testing)\n    - [Local development with the integration test environment](#local-development-with-the-integration-test-environment)\n    - [Running Postman tests locally](#running-postman-tests-locally)\n    - [Adding new API tests](#adding-new-api-tests)\n  - [Licence](#licence)\n    - [About the licence](#about-the-licence)\n\n## Requirements\n\n### Node.js\n\nPlease install the Node.js version in [.nvmrc](.nvmrc) using [Node Version Manager `nvm`](https://github.com/creationix/nvm) via:\n\n```bash\ncd forms-manager\nnvm use\n```\n\n## Local development\n\n### Setup\n\n1. Install Docker\n\n2. Bring up runtime dependencies\n\n```bash\ndocker compose up\n```\n\n3. Create a `.env` file with the following mandatory environment variables populated at root level:\n\n```text\nMONGO_URI=\"\"\nMONGO_DATABASE=\"\"\nOIDC_JWKS_URI=\"\"\nOIDC_VERIFY_AUD=\"\"\nOIDC_VERIFY_ISS=\"\"\nROLE_EDITOR_GROUP_ID=\"\"\nHTTP_PROXY=\nHTTPS_PROXY=\nNO_PROXY=\nSNS_TOPIC_ARN=\nSNS_ENDPOINT=\nAWS_ACCESS_KEY_ID=\nAWS_SECRET_ACCESS_KEY=\n```\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. It's currently supports Hapi Wreck only, e.g. in the JWKS lookup.\n\n### Development\n\nTo run the application in `development` mode run:\n\n```bash\nnpm run dev\n```\n\n### Production\n\nTo mimic the application running in `production` mode locally run:\n\n```bash\nnpm 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\nnpm run\n```\n\n### Database Migrations\n\nThis project uses [migrate-mongo](https://www.npmjs.com/package/migrate-mongo) to manage database migrations.\n\n#### Production\n\nIn production, migrations run automatically when the Docker container starts via the `scripts/run-migrations-and-start.sh` shell script. This script:\n\n1. Runs all pending migrations (`migrate-mongo up`)\n2. Starts the application server\n3. Logs migration progress to the container output\n\n**No manual intervention is required** - migrations execute automatically on container startup.\n\n#### Local Development\n\nFor local development, you have two options:\n\n##### Option 1: Using Docker (Recommended)\n\nMigrations run automatically when using Docker:\n\n```bash\ndocker compose up --build forms-manager\n```\n\nThis mimics the production environment and runs migrations via the same shell script.\n\n##### Option 2: Manual Migration Commands\n\nTo work with migrations manually, you can install migrate-mongo globally:\n\n```bash\nnpm install -g migrate-mongo\n```\n\nAvailable migration commands:\n\n```bash\n# Check migration status\nnpm run migrate:status\n\n# Run all pending migrations\nnpm run migrate:up\n\n# Rollback the last migration\nnpm run migrate:down\n\n# Create a new migration\nnpx migrate-mongo create \u003cmigration-name\u003e -f migrate-mongo-config.js\n```\n\n**Important**: When running migrations manually, ensure your `.env` file contains the correct `MONGO_URI` and `MONGO_DATABASE` values that match your local MongoDB instance.\n\n## API endpoints\n\n| Endpoint                       | Description       |\n| :----------------------------- | :---------------- |\n| `GET: /health`                 | Health            |\n| `GET: /v1/entities`            | Entities          |\n| `GET: /v1/entities/\u003centityId\u003e` | Entity by ID      |\n| `PATCH: /forms/\u003cid\u003e`           | Update Form by ID |\n\n## Calling API endpoints\n\n### Postman\n\nA [Postman](https://www.postman.com/) collection and environment are available for making calls to the Teams and\nRepositories API. Simply import the collection and environment into Postman.\n\n- [CDP Node Backend Template Postman Collection](postman/forms-manager.postman_collection.json)\n- [CDP Node Backend Template Postman Environment](postman/forms-manager.postman_environment.json)\n\n## Docker\n\n### Development image\n\nBuild:\n\n```bash\ndocker build --target development --no-cache --tag forms-manager:development .\n```\n\nRun:\n\n```bash\ndocker run -e GITHUB_API_TOKEN -p 3008:3008 forms-manager:development\n```\n\n### Production image\n\nBuild:\n\n```bash\ndocker build --no-cache --tag forms-manager .\n```\n\nRun:\n\n```bash\ndocker run -e GITHUB_API_TOKEN -p 3001:3001 forms-manager\n```\n\n## Integration testing\n\n### Local development with the integration test environment\n\nIf you want to run the API with the integration test environment (which includes mock OIDC and test MongoDB):\n\n1. Set up the integration test environment:\n\n```bash\nnpm run test:integration:setup    # Start OIDC mock server and MongoDB\nnpm run test:integration:start    # Start the API service\nnpm run test:integration:wait     # Wait for the app to be ready\n```\n\n2. The API will be available at http://localhost:3001\n\n3. When finished, clean up the environment:\n\n```bash\nnpm run test:integration:stop\n```\n\n### Running Postman tests locally\n\nTo run the integration tests manually in Postman:\n\n1. Set up the integration test environment as described above\n2. Import the test collection and environment into Postman:\n\n- Collection: `test/integration/postman/forms-manager-ci-mock.postman_collection.json`\n- Environment: `test/integration/postman/forms-manager-ci-mock.postman_environment.json`\n\n3. Ensure the environment variable `root` is set to `http://localhost:3001`\n4. Run the collection or individual requests through the Postman GUI\n5. Clean up the environment when done with `npm run test:integration:stop`\n\n### Adding new API tests\n\nTo extend the integration test suite with new test cases:\n\n1. **Open the collection in Postman**:\n\n- Import the collection if you haven't already: `test/integration/postman/forms-manager-ci-mock.postman_collection.json`\n- Import the environment: `test/integration/postman/forms-manager-ci-mock.postman_environment.json`\n\n2. **Create a new request**:\n\n- Right-click on the appropriate folder in the collection and select \"Add Request\"\n- Name it clearly, describing what it tests (e.g., \"Create Form - Valid Input\")\n- Set the HTTP method (GET, POST, PUT, etc.) and URL using environment variables: `{{root}}/forms`\n\n3. **Configure authentication**:\n\n- In the Authorization tab, select \"Bearer Token\"\n- Use `{{accessToken}}` as the token value (the collection's pre-request scripts will handle token acquisition)\n\n4. **Add request body or parameters** if needed:\n\n- For POST/PUT requests, add your JSON body in the Body tab\n- Use the \"raw\" format and select JSON\n\n5. **Add pre-request scripts** if required:\n\n- Use the Pre-request Script tab for setup logic\n- Create test data or variables needed for this specific test\n\n6. **Add test assertions**:\n\n- In the Tests tab, write assertions to verify the response\n- Example:\n\n  ```javascript\n  pm.test('Status code is 200', function () {\n    pm.response.to.have.status(200)\n  })\n\n  pm.test('Response has expected data', function () {\n    const responseData = pm.response.json()\n    pm.expect(responseData).to.have.property('id')\n    pm.expect(responseData.name).to.eql('Expected Name')\n  })\n  ```\n\n7. **Test locally**:\n\n- Start the integration environment with `npm run test:integration:setup \u0026\u0026 npm run test:integration:start \u0026\u0026 npm run test:integration:wait`\n- Run your new request and verify it passes\n- Make adjustments as needed\n\n8. **Export and commit**:\n\n- Export the updated collection: File → Export → Collection\n- Save it to `test/integration/postman/forms-manager-ci-mock.postman_collection.json`, overwriting the existing file\n- Commit the updated collection file to the repository\n\n9. **Update documentation** if needed:\n\nIf you're adding endpoints for new features, update the API endpoints section in this README\n\nThe CI pipeline will automatically run your new test along with the existing ones on PRs and merges to main.\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefra%2Fforms-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdefra%2Fforms-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefra%2Fforms-manager/lists"}