From 906b8705b981eb0f27e947e68c79c163a4ad2258 Mon Sep 17 00:00:00 2001 From: linuskmr Date: Tue, 21 Dec 2021 22:45:28 +0100 Subject: [PATCH] Add documentation --- backend/.dockerignore | 138 +++++++++++++++++++++++++++++++++++ backend/Dockerfile | 12 +++ backend/README.md | 32 ++------ backend/docker-compose.yml | 7 ++ backend/docs/guidelines.md | 11 +++ backend/docs/installation.md | 92 +++++++++++++++++++++++ backend/src/main.py | 13 +++- 7 files changed, 276 insertions(+), 29 deletions(-) create mode 100644 backend/.dockerignore create mode 100644 backend/Dockerfile create mode 100644 backend/docker-compose.yml create mode 100644 backend/docs/guidelines.md create mode 100644 backend/docs/installation.md diff --git a/backend/.dockerignore b/backend/.dockerignore new file mode 100644 index 0000000..a81c8ee --- /dev/null +++ b/backend/.dockerignore @@ -0,0 +1,138 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ diff --git a/backend/Dockerfile b/backend/Dockerfile new file mode 100644 index 0000000..5f6f856 --- /dev/null +++ b/backend/Dockerfile @@ -0,0 +1,12 @@ +FROM python:3.10 + +WORKDIR /usr/src/app + +# Install requirements before copying the rest of data to make use of docker's cache layers +COPY requirements.txt ./ +RUN pip install --no-cache-dir -r requirements.txt + +# Copy files from host to workdir in container +COPY . . + +CMD ["python", "src/main.py"] \ No newline at end of file diff --git a/backend/README.md b/backend/README.md index bafdeb9..ed9628e 100644 --- a/backend/README.md +++ b/backend/README.md @@ -1,32 +1,10 @@ # Juggl API -## Installation +This is the new Juggl API created with FastAPI as http framework and SQLModel as ORM. -Minimum Python version: 3.10 +The documentation is split in several files for better structure. -Create virtual environment: +Table of Contents: -``` -$ python3.10 -m venv/ ./venv/ -``` - -Activate virtual environment (Linux): - -``` -$ source venv/bin/activate -``` - - -Activate virtual environment (Windows): - -``` -$ .venv\Scripts\activate -``` - -## Guidelines - -All routes and should be async for maximum performance - -Always specify the `response_model` in the route decorator and use the same type as type hint for the function return -type. FastAPI is unfortunately not yet smart enough to determine the `response_model` from the return type hint. -Maybe we should consider making a pull request... \ No newline at end of file +- [Installation](docs/installation.md) +- [Guidelines](docs/guidelines.md) \ No newline at end of file diff --git a/backend/docker-compose.yml b/backend/docker-compose.yml new file mode 100644 index 0000000..f109b47 --- /dev/null +++ b/backend/docker-compose.yml @@ -0,0 +1,7 @@ +version: "3.9" +services: + api: + build: . + restart: always + ports: + - "8192:8192" diff --git a/backend/docs/guidelines.md b/backend/docs/guidelines.md new file mode 100644 index 0000000..1317b18 --- /dev/null +++ b/backend/docs/guidelines.md @@ -0,0 +1,11 @@ +# Guidelines + +Guidelines we want and should follow for Juggl API. + +--- + +- All routes and should be `async` for maximum performance + +- All routes should specify a `response_model` in the route decorator if they return anything. The same type should + be used as type hint for the function return type. FastAPI is unfortunately not yet smart enough to determine the + `response_model` from the return type hint. Maybe we should consider making a pull request... \ No newline at end of file diff --git a/backend/docs/installation.md b/backend/docs/installation.md new file mode 100644 index 0000000..f3606fc --- /dev/null +++ b/backend/docs/installation.md @@ -0,0 +1,92 @@ +# Installation + +First, install Python in version ≥ 3.9 + +There are several ways to run Juggl api. + +- [Directly via virtual environment](#virtual-environment) +- [In an automatically managed docker container](#docker-compose) +- [In a manually created docker container](#manual-container) + +## Virtual Environment + +Go to the backend directory. + +```bash +$ cd backend +``` + +Create virtual environment: + +```bash +$ python -m venv/ ./venv/ +``` + +Activate virtual environment (Linux): + +```bash +$ source venv/bin/activate +``` + +Activate virtual environment (Windows): + +```bash +$ .venv\Scripts\activate +``` + +Run `src/main.py`: + +> Note: When executing, you must be in the `backend/` directory! Executing the program from another directory will +> fail, because Python then can not resolve imports correctly. Why? Don't know. + +```bash +$ python src/main.py +``` + +## Docker + +Install [Docker](https://docs.docker.com/get-docker/) and [Docker-Compose](https://docs.docker.com/compose/install/). + +### Docker-compose + +Automatically set up all dependencies, export ports and start container(s) with docker-compose. + +Build composed container setup: +```bash +$ docker-compose build +``` + +Start and block terminal with output +```bash +$ docker-compose up +``` + +Start in background (as deamon) +```bash +$ docker-compose up -d +``` + +Stop all containers +```bash +$ docker-compose down +``` + +### Manual container + +Build and execute the docker container manually. + +#### Build container + +```bash +docker build -t juggl-api . +``` + +#### Start container + +Execute the previously bild container. + +Don't forget to export the port from the container to your host system with `-p HOST_PORT:CONTAINER_PORT`. + +```bash +docker run -p 8192:8192 juggl-api +``` \ No newline at end of file diff --git a/backend/src/main.py b/backend/src/main.py index e69872b..36803bb 100644 --- a/backend/src/main.py +++ b/backend/src/main.py @@ -1,3 +1,10 @@ + +# Modify python's import path to include the current directory so that the imports get resolved correctly +import os +import sys +sys.path.extend([os.getcwd()]) + + import argparse import uvicorn @@ -69,13 +76,15 @@ def parse_args() -> argparse.Namespace: def start_dev_server(port: int): """Starts a development server with auto-reloading on port.""" - uvicorn.run("main:app", reload=True, port=port) + # Host="0.0.0.0" makes the application accessible from other IPs. Necessary when running inside docker + uvicorn.run("main:app", reload=True, port=port, host="0.0.0.0") def start_production_server(port: int): """Starts a production, i.e. performance-optimized server on port.""" - uvicorn.run("main:app", port=port) + # Host="0.0.0.0" makes the application accessible from other IPs. Necessary when running inside docker + uvicorn.run("main:app", port=port, host="0.0.0.0") if __name__ == "__main__":