ESS Notify Server

Python web server to send notifications.

ess-notify is built with FastAPI.

Configuration

All variables defined in app/settings.py can be overridden by exporting environment variables. This can be achieved by setting the variables in a .env file:

$ cat .env
APNS_KEY_ID=my-key
TEAM_ID=my-team
ADMIN_USERS=username
FIREBASE_PROJECT_ID=my-project
GOOGLE_APPLICATION_CREDENTIALS=my-project.json

Note that as APNS_AUTH_KEY shall contain a private key (on multiple lines) it's not easy to define it in the .env file. The dummy default key can be overridden by creating a file and exporting its content:

export APNS_AUTH_KEY="$(cat .apns_auth_key)"

To be able to login, at least the following variables shall be overwritten:

• LDAP_HOST
• LDAP_USER_DN

Refer to the default values defined in the Ansible role and in the ess_notify_servers group in CSEntry.

Development

Virtual environment

Python >= 3.6 is required. Create a virtual environment and install the requirements:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .[tests]

When using sqlite, it's not possible to run alembic for database migration (sqlite doesn't support to drop a column in a table). Create the database from scratch using:

notify-server create-db

This is for development only. In production, use postgres and alembic.

Run the application:

uvicorn --reload app.main:app

Go to http://127.0.0.1:8000/api/v1/docs and http://127.0.0.1:8000/api/v2/docs to browse the API depending on the version.

Using uvicorn with the --reload parameter will automatically restart the application when a file changes. Note that the logging configuration assumes that the application is run with gunicorn. To do so, run:

gunicorn -w 2 -k uvicorn.workers.UvicornWorker --log-level info app.main:app

This will run the application using SQLite. The application uses PostgreSQL in production. This can be done by updating the SQLALCHEMY_DATABASE_URL variable to point to a postgres database. Using docker, as detailed below, is recommended.

Docker

The provided docker-compose.yml file allows you to easily start the application with PostgreSQL.

First time:

• Build the docker image: docker-compose build
• Start postgres: docker-compose up -d postgres
• Run alembic to create the database: docker-compose run --rm web alembic upgrade head
• Start the application: docker-compose up web

Those commands only need to be run the first time. The docker image shall be rebuilt only if requirements change. After that, start the application by running:

docker-compose up -d postgres
docker-compose up web

Testing

pytest is used for testing. Create and activate a virtual environment as detailed above.

pytest -v tests

Deployment

Deployment is performed with Ansible and Docker. When pushing to the master branch, the application is automatically deployed to the test server https://notify-test.esss.lu.se.

To deploy to production, tag the branch (git tag -a <version>) and push that tag. At the end of the gitlab-ci pipeline, a manual job is created and shall be triggered manually.

Maintenance

To remove old notifications, you can run the notify-server delete-notifications command. You can run it inside the ess_notify_web container using the crontab:

/usr/bin/docker exec ess_notify_web notify-server delete-notifications

By default, only the last 30 days are kept. You can change that value with the --daysoption.