OEKZident.de/ovdashboard
2
0
Fork 0
Code Releases 1 Packages Activity

API readme

Browse source
This commit is contained in:
Jörn-Michael Miehe 2022-09-21 22:34:31 +00:00
parent 11522ac19b
commit e13bd36d62
1 changed files with 38 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

56
api/README.md
View file

@ -5,39 +5,59 @@ This API enables the OVDashboard UI to run.
## Quick Start
Preferably, use the `docker` image at `TODO` to run this API and its UI simultaneously. Refer to the [main README](../README.md) for how to do that.
If you only want a working installation, it is highly recommended to use the `docker` image at [`TODO`](TODO).
The image contains both the API and UI.
Refer to the [main README](../README.md) for an in-depth how-to.
## Running the API without a container
## Setup for development and contribution
Install the `ovdashboard_api` python package, you can:
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/)
- [Remote - 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.
Then you can:
- use `uvicorn` or another ASGI runner to start the app object `ovdashboard_api:app` <br />
Example: `uvicorn 'ovdashboard_api:app'`
- run the provided `ovdashboard-api` script &ndash; this is basically a shorthand for `uvicorn`
- use `gunicorn` or another application server with ASGI workers (can be provided by `uvicorn`) <br />
Example: `gunicorn 'ovdashboard_api:app' --worker-class uvicorn.workers.UvicornWorker`
- use `gunicorn` or another application server with ASGI workers <br />
Example (ASGI workers provided by `uvicorn`): `gunicorn 'ovdashboard_api:app' --worker-class 'uvicorn.workers.UvicornWorker'`
## Configuration
The OVDashboard API is fully configured by environment variables or an `.env` file in the current working directory. Refer to the [main README](../README.md) for the list of variables.
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.
## Dependencies
Refer to your distribution's manual for how to install these dependencies.
- Python 3.9 with pip <br />
If `python3 --version` shows "Python 3.9" or later, and `python3 -m pip` does execute, you're good to go
- git (recommended)
- libmagic
## Installation
## Installing the `ovdashboard_api` python package
If `git` is installed, install `ovdashboard_api` directly using this command:
python3 -m pip install 'git+https://TODO#egg=ovdashboard_api&subdirectory=api'
If installing `git` is not an option, just [download and extract this repository's archive](TODO), then use the local path instead of the `git+https` URL for `pip install`.
If installing `git` is not an option, just [download and extract this repository's archive](TODO), then use your local path instead of the `git+https://` URL for `pip install`.
## Installation Dependencies
Refer to your distribution's manual for how to install these dependencies:
- Python 3.9 with pip <br />
If `python3 --version` shows "Python 3.9" or later, and `python3 -m pip` does execute, your setup is working.
- git (recommended)
- libmagic