{"id":26817895,"url":"https://github.com/landregistry/govuk-frontend-flask","last_synced_at":"2025-04-23T22:45:58.945Z","repository":{"id":38311529,"uuid":"478951001","full_name":"LandRegistry/govuk-frontend-flask","owner":"LandRegistry","description":"GOV.UK Frontend Flask App Template","archived":false,"fork":false,"pushed_at":"2025-04-12T13:28:04.000Z","size":994,"stargazers_count":16,"open_issues_count":6,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-23T22:45:38.724Z","etag":null,"topics":["flask","flask-wtf","govuk","govuk-frontend","jinja","template","wtforms"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LandRegistry.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2022-04-07T11:18:11.000Z","updated_at":"2025-04-09T10:21:15.000Z","dependencies_parsed_at":"2023-02-12T22:16:14.264Z","dependency_job_id":"aa5bd5a7-4fa8-4d45-96a1-4139ce30467e","html_url":"https://github.com/LandRegistry/govuk-frontend-flask","commit_stats":null,"previous_names":[],"tags_count":9,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LandRegistry%2Fgovuk-frontend-flask","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LandRegistry%2Fgovuk-frontend-flask/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LandRegistry%2Fgovuk-frontend-flask/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LandRegistry%2Fgovuk-frontend-flask/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LandRegistry","download_url":"https://codeload.github.com/LandRegistry/govuk-frontend-flask/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250528694,"owners_count":21445511,"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":["flask","flask-wtf","govuk","govuk-frontend","jinja","template","wtforms"],"created_at":"2025-03-30T04:18:20.502Z","updated_at":"2025-04-23T22:45:58.901Z","avatar_url":"https://github.com/LandRegistry.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GOV.UK Frontend Flask\n\n![govuk-frontend 5.7.1](https://img.shields.io/badge/govuk--frontend%20version-5.7.1-005EA5?logo=gov.uk\u0026style=flat)\n\n**GOV.UK Frontend Flask is a [community tool](https://design-system.service.gov.uk/community/resources-and-tools/) of the [GOV.UK Design System](https://design-system.service.gov.uk/). The Design System team is not responsible for it and cannot support you with using it. Contact the [maintainers](#contributors) directly if you need [help](#support) or you want to request a feature.**\n\nThis is a template [Flask](https://flask.palletsprojects.com) app using the [GOV.UK Frontend](https://frontend.design-system.service.gov.uk/) and [GOV.UK Design System](https://design-system.service.gov.uk/) which is designed to get a new project started quicker. It is also a reference implementation of two core packages:\n\n- [GOV.UK Frontend Jinja](https://github.com/LandRegistry/govuk-frontend-jinja) which provides Jinja macros of GOV.UK components\n- [GOV.UK Frontend WTForms](https://github.com/LandRegistry/govuk-frontend-wtf) which provides WTForms widgets to integrate the above Jinja macros into form generation and validation\n\nThe app is provided intentionally bare, with just the essential parts that all services need, such as error pages, accessibility statement, cookie banner, cookie page and privacy notice. It uses a number of other packages to provide the [features](#features) described below with sensible and best-practice defaults. Please read the [next steps](#next-steps) section for guidance on how to start building out your app on top of this template.\n\n## Prerequisites\n\n### Required\n\n- Docker\n\n## Getting started\n\n### Create a new repository\n\n[Create a new repository](https://github.com/LandRegistry/govuk-frontend-flask/generate) using this template, with the same directory structure and files. Then clone a local copy of your newly created repository.\n\n### Set local environment variables\n\nIn the `compose.yml` file you will find a number of environment variables. These are injected as global variables into the app and pre-populated into page templates as appropriate. Enter your specific service information for the following:\n\n- CONTACT_EMAIL\n- CONTACT_PHONE\n- DEPARTMENT_NAME\n- DEPARTMENT_URL\n- SERVICE_NAME\n- SERVICE_PHASE\n- SERVICE_URL\n\nYou must also set a new unique `SECRET_KEY`, which is used to securely sign the session cookie and CSRF tokens. It should be a long random `bytes` or `str`. You can use the output of this Python command to generate a new key:\n\n```shell\npython -c 'import secrets; print(secrets.token_hex())'\n```\n\n### Get the latest GOV.UK Frontend assets\n\n```shell\n./build.sh\n```\n\n### Run containers\n\n```shell\ndocker compose up --build\n```\n\nYou should now have the app running on \u003chttps://localhost/\u003e. Accept the browsers security warning due to the self-signed HTTPS certificate to continue.\n\n## Demos\n\nThere are some helpful demos included by default that show all of the components available from GOV.UK Frontend Jinja and a selection of forms and validation patterns from GOV.UK Frontend WTForms. These are located in the `app/demos` and `app/templates/demos` directories, along with the `demos` blueprint. Use them for reference whilst building your service, but make sure to delete them, along with the relevant section in `build.sh`, before deploying the app.\n\n## Testing\n\nTo run the tests:\n\n```shell\npython -m pytest --cov=app --cov-report=term-missing --cov-branch\n```\n\n## Environment\n\n```mermaid\nflowchart TB\n    cache1(Redis):::CACHE\n    Client\n    prox1(NGINX):::PROXY\n    web1(Flask app):::WEB\n    web2[/Static files/]:::WEB\n\n    Client \u003c-- https:443 --\u003e prox1 \u003c-- http:5000 --\u003e web1\n    prox1 -- Read only --\u003e web2\n    web1 -- Write --\u003e web2\n    web1 \u003c-- redis:6379 --\u003e cache1\n\n    subgraph Proxy container\n        prox1\n    end\n\n    subgraph Web container\n        web1\n        web2\n    end\n\n    subgraph Cache container\n        cache1\n    end\n\n    classDef CACHE fill:#F8CECC,stroke:#B85450,stroke-width:2px\n    classDef PROXY fill:#D5E8D4,stroke:#82B366,stroke-width:2px\n    classDef WEB fill:#FFF2CC,stroke:#D6B656,stroke-width:2px\n```\n\n## Features\n\nPlease refer to the specific packages documentation for more details.\n\n### Asset management\n\nCustom CSS and JavaScript files are merged and minified using [Flask Assets](https://flask-assets.readthedocs.io/en/latest/) and [Webassets](https://webassets.readthedocs.io/en/latest/). This takes all `*.css` files in `app/static/src/css` and all `*.js` files in `app/static/src/js` and outputs a single minified file to both `app/static/dist/css` and `app/static/dist/js` respectively.\n\nCSS is [minified](\u003chttps://en.wikipedia.org/wiki/Minification_(programming)\u003e) using [CSSMin](https://github.com/zacharyvoase/cssmin) and JavaScript is minified using [JSMin](https://github.com/tikitu/jsmin/). This removes all whitespace characters, comments and line breaks to reduce the size of the source code, making its transmission over a network more efficient.\n\n### Cache busting\n\nMerged and minified assets are browser cache busted on update by modifying the filename with their MD5 hash using [Flask Assets](https://flask-assets.readthedocs.io/en/latest/) and [Webassets](https://webassets.readthedocs.io/en/latest/). The MD5 hash is appended to the file name, for example `custom-d41d8cd9.css` instead of a query string, to support certain older browsers and proxies that ignore the querystring in their caching behaviour.\n\n### Forms generation and validation\n\nUses [Flask WTF](https://flask-wtf.readthedocs.io/en/stable/) and [WTForms](https://wtforms.readthedocs.io) to define and validate forms. Forms are rendered in your template using regular Jinja syntax.\n\n### Form error handling\n\nIf a submitted form has any validation errors, an [error summary component](https://design-system.service.gov.uk/components/error-summary/) is shown at the top of the page, along with individual field [error messages](https://design-system.service.gov.uk/components/error-message/). This follows the GOV.UK Design System [validation pattern](https://design-system.service.gov.uk/patterns/validation/) and is built into the base page template.\n\n### Flash messages\n\nMessages created with Flask's `flash` function will be rendered using the GOV.UK Design System [notification banner component](https://design-system.service.gov.uk/components/notification-banner/). By default the blue \"important\" banner style will be used, unless a category of \"success\" is passed to use the green version.\n\n### CSRF protection\n\nUses [Flask WTF](https://flask-wtf.readthedocs.io/en/stable/) to enable [Cross Site Request Forgery](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection per form and for the whole app.\n\nCSRF errors are handled by creating a [flash message](#flash-messages) notification banner to inform the user that the form they submitted has expired.\n\n### HTTP security headers\n\n- Forces all connections to `https`.\n- Enables [HTTP Strict Transport Security](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security).\n- Sets Flask's session cookie to `secure`, so it will never be set if your application is somehow accessed via a non-secure connection.\n- Sets Flask's session cookie to `httponly`, preventing JavaScript from being able to access its content.\n- Sets [X-Frame-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) to `SAMEORIGIN` to avoid [clickjacking](https://en.wikipedia.org/wiki/Clickjacking).\n- Sets [X-Content-Type-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options) to prevent content type sniffing.\n- Sets a strict [Referrer-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy) of `strict-origin-when-cross-origin` that governs which referrer information should be included with requests made.\n\n### Content Security Policy\n\nA strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) (CSP) is set to mitigate [Cross Site Scripting](https://developer.mozilla.org/en-US/docs/Web/Security/Types_of_attacks#cross-site_scripting_xss) (XSS) and packet sniffing attacks. This prevents loading any resources that are not in the same domain as the application by default.\n\n### Permissions Policy\n\nA strict [Permissions Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy) is set to deny the use of browser features by default.\n\n### Response compression\n\nUses [Flask Compress](https://github.com/colour-science/flask-compress) to compress response data. This inspects the `Accept-Encoding` request header, compresses using either gzip, deflate or brotli algorithms and sets the `Content-Encoding` response header. HTML, CSS, XML, JSON and JavaScript MIME types will all be compressed.\n\n### Rate limiting\n\nUses [Flask Limiter](https://flask-limiter.readthedocs.io/en/stable/) to set request rate limits on routes. The default rate limit is 2 requests per second _and_ 60 requests per minute (whichever is hit first) based on the client's remote IP address. Every time a request exceeds the rate limit, the view function will not get called and instead a [HTTP 429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) status will be returned.\n\nRate limit storage can be backed by [Redis](https://redis.io/) using the `RATELIMIT_STORAGE_URL` config value in `config.py`, or fall back to in-memory if not present. Rate limit information will also be added to various [response headers](https://flask-limiter.readthedocs.io/en/stable/#rate-limiting-headers).\n\n## Contributors\n\n- [Matt Shaw](https://github.com/matthew-shaw) (Primary maintainer)\n\n## Support\n\nThis software is provided _\"as-is\"_ without warranty. Support is provided on a _\"best endeavours\"_ basis by the maintainers and open source community.\n\nIf you are a civil servant you can sign up to the [UK Government Digital Slack](https://ukgovernmentdigital.slack.com/signup) workspace to contact the maintainers listed [above](#contributors) and the community of people using this project in the [#govuk-design-system](https://ukgovernmentdigital.slack.com/archives/C6DMEH5R6) channel.\n\nOtherwise, please see the [contribution guidelines](CONTRIBUTING.md) for how to raise a bug report or feature request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flandregistry%2Fgovuk-frontend-flask","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flandregistry%2Fgovuk-frontend-flask","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flandregistry%2Fgovuk-frontend-flask/lists"}