API readme

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` <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 />
+- use `gunicorn` or another application server with ASGI workers <br />
-Example: `gunicorn 'ovdashboard_api:app' --worker-class uvicorn.workers.UvicornWorker` 
+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
+## Installing the `ovdashboard_api` python package
-
-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
 
 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