flaschengeist/readme.md

# Flaschengeist
![status-badge](https://ci.os-sc.org/api/badges/Flaschengeist/flaschengeist/status.svg)

This is the backend of the Flaschengeist.

## Installation
### Requirements
- `mysql` or `mariadb`
    - maybe `libmariadb` development files[1]
- python 3.7+

[1] By default Flaschengeist uses mysql as database backend, if you are on Windows Flaschengeist uses `PyMySQL`, but on
Linux / Mac the faster `mysqlclient` is used, if it is not already installed installing from pypi requires the
development files for `libmariadb` to be present on your system.

### Install python files
    pip3 install --user .
or with ldap support

    pip3 install --user ".[ldap]"
or if you want to also run the tests:

    pip3 install --user ".[ldap,test]"

You will also need a MySQL driver, recommended drivers are
- `mysqlclient`
- `PyMySQL`

`setup.py` will try to install a matching driver.

#### Windows
Same as above, but if you want to use `mysqlclient` instead of `PyMySQL` (performance?) you have to follow this guide:

https://www.radishlogic.com/coding/python-3/installing-mysqldb-for-python-3-in-windows/

### Configuration
Configuration is done within the a `flaschengeist.toml`file, you can copy the one located inside the module path
(where flaschegeist is installed) or create an empty one and place it inside either:
1. `~/.config/`
2. A custom path and set environment variable `FLASCHENGEIST_CONF`

Uncomment and change at least all the database parameters!

#### CRON
Some functionality used by some plugins rely on regular updates,
but as flaschengeists works as an WSGI app it can not controll when it gets called.

So you have to configure one of the following options to call flaschengeists CRON tasks:

1. Passive Web-CRON: Every time an users calls flaschengeist a task is scheduled (**NOT RECOMMENDED**)
  - Pros: No external configuration needed
  - Cons: Slower user experience, no guaranteed execution time of tasks
2. Active Web-CRON: You configure a webworker to call `<flaschengeist>/cron`
  - Pros: Guaranteed execution interval, no impact on user experience (at least if you do not limit wsgi worker threads)
  - Cons: Uses one of the webserver threads while executing

### Database installation
The user needs to have full permissions to the database.
If not you need to create user and database manually do (or similar on Windows):

    (
        echo "CREATE DATABASE flaschengeist;"
        echo "CREATE USER 'flaschengeist'@'localhost' IDENTIFIED BY 'flaschengeist';"
        echo "GRANT ALL PRIVILEGES ON flaschengeist.* TO 'flaschengeist'@'localhost';"
        echo "FLUSH PRIVILEGES;"
    ) | sudo mysql

Then you can install the database tables and initial entries:

    run_flaschengeist install

### Run
    run_flaschengeist run
or with debug messages:

    run_flaschengeist run --debug

This will run the backend on http://localhost:5000

## Tests
    $ pip install '.[test]'
    $ pytest
Run with coverage report:

    $ coverage run -m pytest
    $ coverage report
Or with html output (open `htmlcov/index.html` in a browser):

    $ coverage html

## Development
Please refer to our [development wiki](https://flaschengeist.dev/Flaschengeist/flaschengeist/wiki/Development).