From e13bd36d624aaf402f4f37269aaf65b0e4db866f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rn-Michael=20Miehe?= <40151420+ldericher@users.noreply.github.com> Date: Wed, 21 Sep 2022 22:34:31 +0000 Subject: [PATCH] API readme --- api/README.md | 56 ++++++++++++++++++++++++++++++++++----------------- 1 file changed, 38 insertions(+), 18 deletions(-) diff --git a/api/README.md b/api/README.md index 88e7aa8..303f4ea 100644 --- a/api/README.md +++ b/api/README.md @@ -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`
Example: `uvicorn 'ovdashboard_api:app'` - run the provided `ovdashboard-api` script – this is basically a shorthand for `uvicorn` -- use `gunicorn` or another application server with ASGI workers (can be provided by `uvicorn`)
-Example: `gunicorn 'ovdashboard_api:app' --worker-class uvicorn.workers.UvicornWorker` +- use `gunicorn` or another application server with ASGI workers
+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
-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
+If `python3 --version` shows "Python 3.9" or later, and `python3 -m pip` does execute, your setup is working. +- git (recommended) +- libmagic