- Node (version defined in
.nvmrc). We recommend using nvm to manage node versions. - uv installed globally
- Copy .env.example to fresh .env file and leave values as is, or use direnv/.envrc for these variables.
nvm usemake bootstrapmake up
If you see permission errors around certs (eg. ERROR: failed to read the CA key: open certs/rootCA-key.pem: permission denied) follow these instructions instead of step 2. above.
Assumes your are on an MHCLG-managed macbook and you have 2 accounts. Your ADMIN_USER is the account with full admin permissions, and your STANDARD_USER is the normal account you use for day to day work.
su <ADMIN_USER>sudo make certsRead the output - should be no apparent errors.chown -R <STANDARD_USER>:staff certsexitto return to your standard user shell.make pre-commitmake vitemake clean-build- Continue with step 3. above
- If you hit the error
SecTrustSettingsSetTrustSettings: The authorization was denied since no user interaction was possible.when doing the abovesu -steps, then you may need to actually logout and login as your admin user instead of usingsu - If you subsequently hit git errors that mention
dubious ownership in repositorythis is to do with changing the directory permissions above. A terminal restart should fix this.
We use uv for managing the local Python environment. Install this tool globally and then run uv sync in this repository to install the correct python version and python dependencies.
Developers are expected to run the app locally using docker-compose. There are some helper commands in a Makefile to help bring up the service.
make bootstrapwill create a local self-signed certificate for HTTPS during development, and set up flask-vite/vite to compile GOV.UK Frontend/our frontend assets.make up/docker compose upwill start the Funding Service app and expose it on https://funding.communities.gov.localhost:8080make down/docker compose downwill stop the Funding Service.make build/docker compose buildwill rebuild the Funding Service image.make clean-build/docker compose build --no-cachewill rebuild the Funding Service image, bypassing caching. This should rarely be needed.make check-html/make format-htmlwill check or format Jinja HTML templates with Prettier. This is also run as part of the pre-commit checks.
By default, local development and locally-run end to end tests use a stub server to implement the same interface as Microsoft SSO flow. This is so we can reliably run e2e tests locally without hitting the real SSO endpoints, and so devs don't need test Azure AD credentials to be able to use the app, making initial setup easier.
If you need to allow real SSO login locally, update the environment variables for AZURE_AD_CLIENT_ID, AZURE_AD_CLIENT_SECRET and AZURE_AD_TENANT_ID to those used by the test Azure AD and add an environment variable of AZURE_AD_BASE_URL=https://login.microsoftonline.com/ in your .env file, or comment out the LocalConfig version of this variable in the config so it falls back to the BaseConfig default. Be aware that the SSO e2e test will fail while this is enabled - don't forget to switch back to check this passes.
All E2E (browser) tests should live inside /tests/e2e.
As a one-off setup step, run uv run playwright install to download and configure the browsers needed for these tests.
To run any E2E tests include the e2e option in the pytest command:
uv run pytest --e2eThis will, by default, run the browser tests headless - i.e. you won't see a browser appear.
To display the browser so you can visually inspect the test journey, add the --headed flag.
To slow the test down, add --slowmo 1000 to have Playwright insert 1 second pauses between each step so that you can follow what the test is doing more easily.
This function skips e2e or non-e2e tests depending on if they are in the e2e module under tests, so no individual tests need to be marked with the e2e marker.
Additional flags must be passed to the pytest command:
- dev:
--e2e-env dev --e2e-aws-vault-profile <your_dev_aws_profile_name> - test:
--e2e-env test --e2e-aws-vault-profile <your_test_aws_profile_name>
By default the e2e test config assumes that locally you are running with the stub SSO server, and this is the default for docker compose.
However, if you have enabled SSO locally as per the instructions above, you can still run the e2e tests against your local environment as follows:
- PreRequisites:
- Login locally using the SSO stub server with the email address
svc-Preaward-Funds@test.communities.gov.uk, and tick the "Platform admin type login" option.
- Login locally using the SSO stub server with the email address
- Update your local
.envfile with the UUID that matches the usersvc-Preaward-Funds@test.communities.gov.ukin your local database:SELECT id from "user" where email='svc-Preaward-Funds@test.communities.gov.uk'; - Edit authenticated_browser_sso() to use 'login_with_session_cookie()' for the local env.
We have some sample grant configuration exported at app/developers/data/grants.json. This data will be loaded automatically into your developer environment during docker-compose startup.
To run a manual load:
uv run flask developers seed-grantsIf you make an update to the grant that you want to be persisted and synced for all other developers, run:
uv run flask developers export-grantsThen commit the change, create a PR and get it merged. Developer environments will sync the changes automatically when their app starts up again.