Home

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.3 (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.3, install dependencies:

   poetry install --with static_tools,test

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:

poetry run uvicorn app.main:app --reload

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

The --reload option 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

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

Mkdoc Overview and Instructions

What is Mkdoc?

Mkdoc is a documentation generator tool for creating reference documentation for Python projects. It extracts documentation from source code, including docstrings and other annotated information, and formats it into a user-friendly static site.

How to Access Mkdoc Locally

To view the Mkdoc documentation locally, you will need to serve the documentation site using the Mkdoc tool. Here’s how you can do it:

1. Serve Documentation Locally: To serve the documentation locally and view it in your browser, use the following command:

   poetry run mkdocs serve

   This command will build the documentation and serve it on a local server (typically at http://localhost:8000). You can open this URL in your browser to view the docs.

2. Clean Serve: If you need to clean the build and serve fresh documentation, use the --clean flag:

   poetry run mkdocs serve --clean

How to Run the Custom Script to Generate Markdown Files

A custom script named create_mkdoc_files.py can be used to automatically generate new Markdown files for the documentation from the source code.

This script should be ran when a new module is added to app/

Here’s how to run it:

1. Navigate to the Project Directory: First, make sure you're in the root directory of the project.

2. Run the Script: Execute the following command to run the script and generate new Markdown files:

   poetry run python scripts/create_mkdoc_files.py

   This will create or update the relevant Markdown files in the docs directory based on the content of your codebase.

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.