Update your capital schemes

Digital service for local authorities to provide updates about capital schemes to Active Travel England.

Prerequisites

1. Install Python 3.12
2. Install Node 20
3. Install Docker and Compose plugin
4. Install Google Cloud CLI and authenticate using ADCs:

   gcloud auth application-default login

5. Install Terraform 1.9
6. Install Bitwarden CLI

Configure the app

Configure the application's environment variables with the localhost secrets:

bw get notes "UYCS Secrets (Localhost)" > .env

The application can also be configured with the following environment variables:

Name	Value
FLASK_ENV	Application environment name (dev, test or prod)
FLASK_SQLALCHEMY_DATABASE_URI	SQLAlchemy database URI
FLASK_CAPITAL_SCHEMES_DATABASE_URI	SQLAlchemy database URI for capital schemes (unset to use primary database URI)
FLASK_SECRET_KEY	Flask session secret key
FLASK_BASIC_AUTH_USERNAME	HTTP Basic Auth username (unset to disable)
FLASK_BASIC_AUTH_PASSWORD	HTTP Basic Auth password
FLASK_API_KEY	API key (unset to disable)
FLASK_GOVUK_CLIENT_ID	OIDC client id
FLASK_GOVUK_CLIENT_SECRET	OIDC client secret
FLASK_GOVUK_SERVER_METADATA_URL	OIDC discovery endpoint
FLASK_GOVUK_TOKEN_ENDPOINT	OIDC token endpoint
FLASK_GOVUK_PROFILE_URL	OIDC profile URL
FLASK_GOVUK_END_SESSION_ENDPOINT	OIDC end session endpoint

Running locally

1. Create a virtual environment:

   python3.12 -m venv --prompt . --upgrade-deps .venv

2. Activate the virtual environment:

   source .venv/bin/activate

3. Build the web assets:

   npm install && npm run build

4. Install the dependencies:

   pip install -e .[dev]

5. Run the server:

   make run

6. Open http://127.0.0.1:5000

Running locally using Docker

To run the server as a container using an in-memory SQLite database:

1. Build the web assets:

   npm install && npm run build

2. Build the Docker image:

   docker build -t schemes .

3. Run the Docker image:

   docker run --rm -it -p 5000:5000 --env-file ./.env schemes

4. Open http://127.0.0.1:5000

The server can also be run on a different port by specifying the PORT environment variable:

docker run --rm -it -e PORT=8000 -p 8000:8000 --env-file ./.env schemes

Running locally using Compose

To run the server as a container using a PostgreSQL database:

1. Build the web assets:

   npm install && npm run build

2. Run the services:

   docker compose up

3. Open http://127.0.0.1:5000

Running formatters and linters

1. Install the dependencies:

   pip install -e .[dev]

2. Run the formatters:

   make format

3. Run the linters:

   make lint

Running tests

1. Install the dependencies:

   pip install -e .[dev]

2. Install the browsers and their dependencies:

   playwright install --with-deps chromium

3. Run the tests:

   make test

Provisioning infrastructure

Provision the Terraform backend

1. Change directory:

   cd cloud/tf-backend

2. Initialise Terraform:

   terraform init

3. Apply the changes:

   terraform apply

Provision the Docker repository

1. Change directory:

   cd cloud/docker-repository

2. Initialise Terraform:

   terraform init

3. Apply the changes:

   terraform apply

4. Obtain the Docker repository service account private key:

   terraform output -raw github_action_push_private_key

5. Set the GitHub Actions repository secret GCP_CREDENTIALS_PUSH to the private key

Provision the application

For each environment required (dev, test, prod):

1. Change directory:

   cd cloud/schemes

2. Initialise Terraform:

   terraform init

3. Create a Terraform workspace for the environment:

   terraform workspace new $ENVIRONMENT

4. Apply the changes:

   terraform apply

5. This will fail due to missing secrets. Now that the Secret Manager service has been enabled, create the secrets then repeat the previous step:

   bw get notes "UYCS Secrets ($ENVIRONMENT)" | sh

6. Obtain the Cloud Run service account private key:

   terraform output -raw github_action_deploy_private_key

7. Set the GitHub Actions environment secret GCP_CREDENTIALS_DEPLOY to the private key

8. Open the output url

Redeploying the service

To manually redeploy the Cloud Run service using the latest image in the Docker repository:

gcloud run deploy schemes \
    --project dft-schemes-$ENVIRONMENT \
    --region europe-west1 \
    --image europe-west1-docker.pkg.dev/dft-schemes-common/docker/schemes

Authentication

We have registered the following services with GOV.UK One Login:

Dev

• Service name: ATE Schemes (Dev)
• Service redirect URLs: https://dev.update-your-capital-schemes.activetravelengland.gov.uk/auth, http://127.0.0.1:5000/auth
• Service contact email address: [email protected]
• Scopes: openid email
• Public key: (see "UYCS GOV.UK One Login Public Key (Dev)" in Bitwarden)
• Logout URLs: https://dev.update-your-capital-schemes.activetravelengland.gov.uk/, http://127.0.0.1:5000/
• Sector identifier URI: https://dev.update-your-capital-schemes.activetravelengland.gov.uk

Test

• Service name: ATE Schemes (Test)
• Service redirect URLs: https://test.update-your-capital-schemes.activetravelengland.gov.uk/auth
• Service contact email address: [email protected]
• Scopes: openid email
• Public key: (see "UYCS GOV.UK One Login Public Key (Test)" in Bitwarden)
• Logout URLs: https://test.update-your-capital-schemes.activetravelengland.gov.uk/
• Sector identifier URI: https://test.update-your-capital-schemes.activetravelengland.gov.uk

Prod

• Service name: Update your capital schemes
• Service redirect URLs: https://update-your-capital-schemes.activetravelengland.gov.uk/auth
• Service contact email address: [email protected]
• Scopes: openid email
• Public key: (see "UYCS GOV.UK One Login Public Key (Prod)" in Bitwarden)
• Logout URLs: https://update-your-capital-schemes.activetravelengland.gov.uk/
• Sector identifier URI: https://update-your-capital-schemes.activetravelengland.gov.uk

See also

• Database
• Maintenance
• Releasing

Licence

MIT License