Overview

VA Enterprise Notification Platform API

Project Overview

This API provides a structured way for the VA to handle notifications. It's designed for scalability and reliability, ensuring that notifications are handled securely and efficiently.

Installation

Prerequisites

• Python ^3.12
• Poetry 1.8.4 (for dependency management)
• Pre-commit (for automatic code quality checks)

Steps

1. Clone the repository locally using ssh,

   git clone [email protected]:department-of-veterans-affairs/va-enp-api.git

   or https

   git clone https://github.com/department-of-veterans-affairs/va-enp-api.git

2. Navigate to the project directory:

   cd va-enp-api

3. Using Poetry 1.8.4, install dependencies:

   poetry install --with static_tools,test,mkdocs

Setting Up Pre-commit Hooks

This project uses pre-commit hooks to enforce coding standards and run automatic checks on your code before committing.

To install the pre-commit hooks, run the following command:

poetry run pre-commit install

This will set up the hooks listed in the .pre-commit-config.yaml file to run automatically whenever you attempt to make a commit.

You can manually run the hooks on all files at any time with:

poetry run pre-commit run --all-files

Usage

Warning

The app now attempts to connect to a database when starting up. You can run the database container standalone if you want to run the app outside of a container, or run the app and database together with docker compose (see below).

Running App outside Container, DB in Container

To run the API locally (outside of container) and reload real-time changes, first bring up the database container:

docker compose -f ci/docker-compose-local.yml up enp-db

Then use the following command to run the app with Uvicorn:

watchfiles "poetry run uvicorn app.main:app"

Note

Exiting via Ctrl-C will cause an asyncio.CancelledError but this is expected and normal behavior as the pending tasks are cancelled.

This will start the API on http://127.0.0.1:8000. (localhost:8000)

The application can also be ran with Gunicorn, using the following command:

gunicorn app.main:app -b 0.0.0.0:8000 -k uvicorn_worker.UvicornWorker -w 4

Running App and DB in Containers

There is a docker compose file (ci/docker-compose-local.yml) that can be used to run the app and a local PostgreSQL database together. From the base directory for the project va-enp-api, use the following command to build and run the two containers together:

docker compose -f ci/docker-compose-local.yml build api && docker compose -f ci/docker-compose-local.yml up

You can edit the entry point in the compose file to be either of the commands listed above depending on if you'd like to run with gunicorn or uvicorn.

Note

Watchfiles only works when running with uvicorn. It still works when running in a container because it maps a volume back to the local files to detect changes.

To access psql in the container, run

docker exec -it enp-db psql -U postgres -d va-enp-api-db

Endpoints

The API exposes several endpoints for managing notifications. Check the API documentation by visiting http://127.0.0.1:8000/docs or http://127.0.0.1:8000/redoc

Testing

The project uses pytest for testing. To run the tests:

poetry run pytest

Make sure all tests pass before submitting any changes.

Linter Scripts

Linter script are located in the file scripts/run_checks.py

To run all linters locally, install Poetry packages with the static_tools group.

poetry install --with static_tools

Then, run linter scripts with the following command:

poetry run ./scripts/run_checks.sh

How to Access MkDocs Locally

You have multiple options for accessing the MkDocs documentation when running your local application, depending on whether you're using Docker or not:

1. Access MkDocs via Docker (Automated Process)

If you're using Docker, MkDocs generation and building have been automated to keep the documentation up to date.

• Simply run the Docker container as instructed in the project's Docker setup. The process will automatically:
  • Generate the MkDocs Markdown files.
  • Build the MkDocs site.

With Docker, there's no need for manual intervention, and the documentation is always current whenever you build the container.

2. Access MkDocs via Local Application without Docker

If you're not using Docker, you'll need to manually generate the MkDocs Markdown files and build the MkDocs site before running the application.

1. Install Dependencies:

   • Install all necessary dependencies, including the MkDocs group:

     poetry install --with static_tools,test,mkdocs

2. Run the Custom Script to Generate Markdown Files:

   • The custom script create_mkdoc_files.py should be run to create or update the Markdown files from your source code.

     poetry run python scripts/create_mkdoc_files.py

     Note: This script should be run whenever a new module is added to app/.

3. Build the MkDocs Site:

   • After generating the Markdown files, you need to build the MkDocs site:

     mkdocs build

4. Run the Application and Access MkDocs:

   • Run your application locally, then visit /mkdocs in your browser to view the documentation.

3. Run MkDocs locally on Its Own Port without Docker

If you prefer to run MkDocs separately, you can do so by starting the MkDocs server on its own port.

1. Install Dependencies:

   • As above, install dependencies including MkDocs:

     poetry install --with static_tools,test,mkdocs

2. Run the Custom Script to Generate Markdown Files:

   • Run the create_mkdoc_files.py script to generate the Markdown files:

     poetry run python scripts/create_mkdoc_files.py

3. Run the MkDocs Server:

   • Start the MkDocs server:

     poetry run mkdocs serve

   • Visit the documentation at http://127.0.0.1:8000/.

Configuration

The project uses a pyproject.toml file for managing dependencies and configuration settings. Please use poetry commands to add, update, or remove any packages.