Process Optimizer REST API

This project expose a REST based API for ProcessOptimizer

How do I get started

If you have Docker installed the API can be started locally, in development mode, by running the script build-and-run.sh

Alternatively the project can be built and run locally.

The toolchain (Python 3.13 + uv) is pinned in mise.toml. With mise installed (see the getting started guide), cd into the repo provisions Python, uv, and a .venv automatically — just run mise install once. Without mise, install Python 3.13 and uv yourself (brew install uv or pip install uv) and create the venv manually:

python3 -m venv .venv
source .venv/bin/activate

uv pip install -e .
python -m optimizerapi.server

Now open http://localhost:9090/v1.0/ui/ in a browser to explore the API through Swagger UI

Running tests

Unit tetsts are located in the "tests" folder and can be run witht the following command

python -m pytest

or use pytest-watch for continuously running tests

ptw

Building docker container

docker build -t process-optimizer-api --build-arg GITHUB_REF_NAME=$(git describe --always) .

Obtain encryption key

Run server once and extract a fresh encryption key from the logs.

python -m optimizerapi.server

or using docker

docker run --rm -it process-optimizer-api

Running in production

Running using python

FLASK_ENV=production PICKLE_KEY=<key from previous step> python -m optimizerapi.server

or use docker

docker run -d --name process-optimizer-api --env PICKLE_KEY=<key from previous step> -p 9090:9090 process-optimizer-api:latest

Use job queue

The API server supports distributing the calculation tasks using a Redis backed job queue. To start the API server in "job queue mode" set the environment variable USE_WORKER=true and start the server and any number of worker threads using the following commands:

USE_WORKER=true python -m optimizerapi.server
python -m optimizerapi.worker

The Redis server can be controlled through the environment variable REDIS_URL which defaults to redis://localhost:6379

Time to live and timeout of the workers can be controlled with the following environment variables

Name	Description
REDIS_TTL	Time to keep results in redis (default=500)
WORKER_TIMEOUT	Timeout in seconds (default=180)

Use CORS

The API server supports exposing its functionality to other origins than its own. To start the API server in "CORS mode" set the environment variable CORS_ORIGIN=.* and start the server. This opens up the API server to any origin that might want to request it.

CORS_ORIGIN=.* python -m optimizerapi.server

You might want to lock the origin down a little tighter. The CORS_ORIGIN variable is a regular expression and can be used to lock the server to a single host or multiple.

A single specific origin:

CORS_ORIGIN="https://prod.brownie.projects.alexandra.dk" python -m optimizerapi.server

All subdomains hosted by alexandra.dk:

CORS_ORIGIN="https://.*.alexandra.dk" python -m optimizerapi.server

Two specific origins:

CORS_ORIGIN="(https://prod.brownie.projects.alexandra.dk|https://prod.cake.projects.alexandra.dk)" python -m optimizerapi.server

Using authentication

API endpoints can be protected by either a static API key or using a Keycloak OIDC server.
The static API key is configured by the environment variable AUTH_API_KEY

Keycloak is configured using the following environement variables

Name	Description
AUTH_SERVER	Base url of your Keycloak server
AUTH_REALM_NAME	OAuth realm name
AUTH_CLIENT_ID	Client ID
AUTH_CLIENT_SECRET	Client secret

Adding or updating dependencies

This project uses pyproject.toml for dependency management following PEP 621 standards.

When adding a new dependency:

1. Add it to the dependencies array in pyproject.toml with a version constraint

2. For development dependencies, add to [project.optional-dependencies] under dev

3. Install the updated dependencies:

   uv pip install -e .
   

   Or for development dependencies:

   uv pip install -e ".[dev]"
   

4. Commit the changed pyproject.toml file

Updating the change log

In order to keep the overhead of maintaining the change log as low as possible this project use a tool to automatically generate as much of the change log as possible.

Before creating a new release please run the following command inside a clean working directory

docker run -it --rm -v "$(pwd)":/usr/local/src/your-app githubchangeloggenerator/github-changelog-generator --user BoostV --project process-optimizer-api