ovdashboard/api/README.md

# OVDashboard API

This API enables the OVDashboard UI to run.


## Quick Start

If you only want a working installation, it is highly recommended to use the `docker` image on [`code.yavook.de`](https://code.yavook.de/OEKZident.de/-/packages/container/ovdashboard).
The image contains both the API and UI.
Refer to the [main README](../README.md) for an in-depth how-to.


## Setup for development and contribution

No need to fiddle around with specific python versions or even `virtualenv`s.
You only need a "general purpose" development setup to get this project up and running for debug and contribution purposes:

- [Docker Engine](https://docs.docker.com/engine/install/)
- [Visual Studio Code](https://code.visualstudio.com/)
- [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) (VSCode extension)

Once you open this directory in VSCode, you should be prompted to reopen it in a development container.
If not, hit `Ctrl+Alt+P` and search for "reopen in container".


## Running the API without the `docker` image

> You probably don't need this! Usually the image is good enough!

However, if you want to deploy the API on a cluster or with custom ASGI workers and/or process managers, go ahead.
First, [install the `ovdashboard_api` python package](#installing-the-ovdashboard_api-python-package).
Then you can:

- use `uvicorn` or another ASGI runner to start the app object `ovdashboard_api.app:app` <br />
Example: `uvicorn 'ovdashboard_api.app:app'`
- run the provided `ovdashboard-api` script &ndash; this is basically a shorthand for `uvicorn`
- use `gunicorn` or another application server with ASGI workers <br />
Example (ASGI workers provided by `uvicorn`): `gunicorn 'ovdashboard_api.app:app' --worker-class 'uvicorn.workers.UvicornWorker'`


## Configuration

The OVDashboard API is configured using environment variables or an `.env` file in the directory which it is run from.
Refer to the [main README](../README.md) for the list of variables.


## Installing the `ovdashboard_api` python package

If `git` is installed, install `ovdashboard_api` directly using this command:

    python3 -m pip install 'git+https://code.yavook.de/OEKZident.de/ovdashboard.git#egg=ovdashboard_api&subdirectory=api'

If installing `git` is not an option, just [download and extract this repository's archive](https://code.yavook.de/OEKZident.de/ovdashboard/archive/master.zip), then use `python3 -m pip install <LOCAL_PATH>`.


## Installation Dependencies

Refer to your distribution's manual for how to install these dependencies:

- Python 3.12 with pip <br />
If `python3 --version` shows "Python 3.12" or later, and `python3 -m pip` does execute, your setup is working.
- git (recommended)
- libmagic