You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
See `README.specification.md` for details of the API specification's development.
4
4
5
-
## Directories
6
-
7
-
```
8
-
backend - The API code.
9
-
terraform - Infrastructure.
10
-
tests - Integration tests.
11
-
devtools - Helper project for development.
12
-
```
13
-
14
-
See any readmes in those directories for more details.
15
-
16
5
## Spelling
17
6
18
7
Refer to the FHIR Immunization resource capitalised and with a "z" as FHIR is U.S. English.
@@ -21,58 +10,155 @@ All other uses are as British English i.e. "immunisation".
21
10
22
11
See https://nhsd-confluence.digital.nhs.uk/display/APM/Glossary.
23
12
24
-
## Setup for local dev
13
+
## Directories
14
+
**Note:** Each Lambda has its own `README.md` file for detailed documentation. For non-Lambda-specific folders, refer to `README.specification.md`.
15
+
16
+
### Lambdas
17
+
18
+
| Folder | Description |
19
+
|---------------------|-------------|
20
+
|`backend`|**Imms API** – Handles CRUD operations for the Immunisation API. |
21
+
|`delta_backend`|**Imms Sync** – Lambda function that reacts to events in the Immunisation database. |
22
+
|`ack_backend`|**Imms Batch** – Generates the final Business Acknowledgment (BUSACK) file from processed messages and writes it to the designated S3 location. |
|`devtools`| Helper tools and utilities for local development |
63
+
|`scripts`| Standalone or reusable scripts for development and automation |
64
+
|`specification`| Specification files to document API and related definitions |
65
+
|`sandbox`| Simple sandbox API |
33
66
34
-
These tools automate the Python version and environment creation and use, and selects them automatically when entering a
35
-
directory.
36
-
`pyenv` separates Python versions and `direnv` handles the environment.
37
-
`direnv` uses `pyenv` to select the version and creates an environment under `.direnv/`.
67
+
---
38
68
39
-
At this point you'll get a warning when you enter this directory, telling you to run `direnv allow`. This is fine and
40
-
the next step will resolve it.
69
+
## Background: Python Package Management and Virtual Environments
70
+
-`pyenv` manages multiple Python versions at the system level, allowing you to install and switch between different Python versions for different projects.
71
+
-`direnv` automates the loading of environment variables and can auto-activate virtual environments (.venv) when entering a project directory, making workflows smoother.
72
+
-`.venv` (created via python -m venv or poetry) is Python’s built-in tool for isolating dependencies per project, ensuring that packages don’t interfere with global Python packages.
73
+
-`Poetry` is an all-in-one dependency and virtual environment manager that automatically creates a virtual environment (.venv), manages package installations, and locks dependencies (poetry.lock) for reproducibility, making it superior to using pip manually and it is used in all the lambda projects.
41
74
42
-
### Install Python versions and environments
75
+
## Project structure
76
+
To support a modular and maintainable architecture, each Lambda function in this project is structured as a self-contained folder with its own dependencies, configuration, and environment.
43
77
44
-
This will set up for both the root and `backend`.
78
+
We use Poetry to manage dependencies and virtual environments, with the virtualenvs.in-project setting enabled to ensure each Lambda has an isolated `.venv` created within its folder.
45
79
46
-
Copy `.env.default` to `.env` or merge it with your existing file.
47
-
Copy `.envrc.default` to `.envrc` or merge it with your existing file.
80
+
Additionally, direnv is used alongside `.envrc` and `.env` files to automatically activate the appropriate virtual environment and load environment-specific variables when entering a folder.
48
81
49
-
These are kept separate so other tools can use `.env`if wanted.
82
+
Each Lambda folder includes its own `.env` file for Lambda-specific settings, while the project root contains a separate `.env`and `.venv` for managing shared tooling, scripts, or infrastructure-related configurations. This setup promotes clear separation of concerns, reproducibility across environments, and simplifies local development, testing, and packaging for deployment.
50
83
51
-
Edit `.env` with your details.
84
+
## Environment setup
85
+
These dependencies are required for running and debugging the Lambda functions and end-to-end (E2E) tests.
86
+
87
+
### Install dependencies
88
+
Steps:
89
+
1. Install [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) if running on Windows and install [Docker](https://docs.docker.com/engine/install/).
90
+
2. Install the following tools inside WSL. These will be used by the lambda and infrastructure code:
The `backend` tests are in a separate module so in order for them to see each other we need to let the IDE know
61
-
about the relationship.
113
+
6. Install poetry
114
+
```
115
+
pip install poetry
116
+
```
62
117
63
-
#### IntelliJ
118
+
### Setting up a virtual environment with poetry
119
+
The steps below must be performed in each Lambda function folder and e2e folder to ensure the environment is correctly configured.
64
120
65
-
- Open the root repo directory in IntelliJ.
66
-
- In Project Structure add an existing virtualenv SDK for `.direnv/python-x.x.x/bin/python`.
67
-
- Set the project SDK and the default root module SDK to the one created above.
68
-
- Add `tests` as sources.
69
-
- Add `.direnv`, `terraform/.terraform`, and `terraform/build` as exclusions if they're not already.
70
-
- Add another existing virtualenv SDK for `backend/.direnv/python-x.x.x/bin/python`.
71
-
- Import a module pointed at the `backend` directory, set the SDK created above.
72
-
- Add the `src` and `tests` directories as sources.
73
-
- Add `.direnv` as an exclusion if it's not already.
121
+
For detailed instructions on running individual Lambdas, refer to the README.md files located inside each respective Lambda folder.
122
+
123
+
Steps:
124
+
1. Set the python version in the `./backend` folder
125
+
```
126
+
pyenv local 3.10.16 # Set version in backend (this creates a .python-version file)
127
+
```
128
+
129
+
2. Configure poetry
130
+
```
131
+
### Point poetry virtual enviornment to .venv
132
+
poetry config virtualenvs.in-project true
133
+
poetry env use $(pyenv which python)
134
+
poetry env info
135
+
```
136
+
137
+
3. Create an .env file and add environment variables
138
+
```
139
+
AWS_PROFILE={your_profile}
140
+
IMMUNIZATION_ENV=local
141
+
```
142
+
143
+
4. Configure `direnv` by creating a `.envrc` file in the backend folder. This points direnv to the `.venv` created by poetry and loads env variables specified in the `.env` file
144
+
```
145
+
export VIRTUAL_ENV=".venv"
146
+
PATH_add "$VIRTUAL_ENV/bin"
147
+
148
+
dotenv
149
+
```
150
+
151
+
5. Restart bash and run `direnv allow`. You should see something similar like:
Test if environment variables have been loaded into shell: `echo $IMMUNIZATION_ENV`.
74
157
75
-
#### VS Code
158
+
## IDE setup
159
+
The current team uses VS Code mainly. So this setup is targeted towards VS code. If you use another IDE please add the documentation to set up workspaces here.
160
+
161
+
### VS Code
76
162
77
163
The project must be opened as a multi-root workspace for VS Code to know that `backend` has its own environment.
78
164
@@ -85,7 +171,24 @@ VS Code will automatically use the `backend` environment when you're editing a f
85
171
Depending on your existing setup VS Code might automatically choose the wrong virtualenvs. Change it
86
172
with `Python: Select Interpreter`.
87
173
88
-
The root (immunisation-fhir-api) should be pointing at `.direnv/python-x.x.x/bin/python.`
174
+
The root (`immunisation-fhir-api`) should point to `/mnt/d/Source/immunisation-fhir-api/.venv/bin/python`.
175
+
176
+
`backend` should be pointing at `/mnt/d/Source/immunisation-fhir-api/backend/.venv/bin/python`
177
+
178
+
### IntelliJ
179
+
180
+
- Open the root repo directory in IntelliJ.
181
+
- In Project Structure add an existing virtualenv SDK for `.direnv/python-x.x.x/bin/python`.
182
+
- Set the project SDK and the default root module SDK to the one created above.
183
+
- Add `tests` as sources.
184
+
- Add `.direnv`, `terraform/.terraform`, and `terraform/build` as exclusions if they're not already.
185
+
- Add another existing virtualenv SDK for `backend/.direnv/python-x.x.x/bin/python`.
186
+
- Import a module pointed at the `backend` directory, set the SDK created above.
187
+
- Add the `src` and `tests` directories as sources.
188
+
- Add `.direnv` as an exclusion if it's not already.
89
189
90
-
`backend` should be pointing at `backend/.direnv/python-x.x.x/bin/python.`
91
190
191
+
## Verified commits
192
+
Please note that this project requires that all commits are verified using a GPG key.
193
+
To set up a GPG key please follow the instructions specified here:
This document describes the environment setup for the backend API Lambda.
4
+
This Lambda handles incoming CRUD operation requests from APIGEE and interacts with the immunisation events database to store immunisation records. All commands listed below are run in the `./backend` folder.
4
5
5
-
## Install dependencies
6
+
## Setting up the backend lambda
7
+
Note: Paths are relative to this directory, `backend`.
6
8
7
-
```shell
8
-
pip install poetry
9
-
poetry install
10
-
pip install terraform-local
11
-
```
12
-
13
-
14
-
## Run locally
15
-
16
-
### Start LocalStack
9
+
1. Follow the instructions in the root level README.md to setup the [dependencies](../README.md#environment-setup) and create a [virtual environment](../README.md#) for this folder.
17
10
18
-
```shell
19
-
cd ../devtools
20
-
docker compose -f localstack-compose.yml up
11
+
2. Replace the `.env` file in the backend folder. Note the variables might change in the future. These environment variables will be loaded automatically when using `direnv`.
0 commit comments