flaschengeist (2.0.0)
Installation
pip install --index-url About this package
Modular student club administration system
Flaschengeist
This is the backend of the Flaschengeist.
Installation
Requirements
mysqlormariadb- maybe
libmariadbdevelopment files[1]
- maybe
- python 3.9+
- pip 21.0+
[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
It is recommended to upgrade pip to the latest version before installing:
python -m pip install --upgrade pip
Default installation with mariadb/mysql support:
pip3 install --user ".[mysql]"
or with ldap support
pip3 install --user ".[ldap]"
or if you want to also run the tests:
pip3 install --user ".[ldap,tests]"
You will also need a MySQL driver, by default one of this is installed:
mysqlclient(non Windows)PyMySQL(on Windows)
Hint on MySQL driver on Windows:
If you want to use mysqlclient instead of PyMySQL (performance?) you have to follow this guide
Install database
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, this will update all tables from core + all enabled plugins.
And also install all enabled plugins:
$ flaschengeist install
Hint: To only install the database tables, or upgrade the database after plugins or core are updated later
you can use this command:
$ flaschengeist db upgrade heads
Plugins
To only upgrade one plugin (for example the events plugin):
$ flaschengeist db upgrade events@head
Configuration
Configuration is done within the a flaschengeist.tomlfile, you can copy the one located inside the module path
(where flaschegeist is installed) or create an empty one and place it inside either:
~/.config/- 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:
- 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
- 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
Run
Flaschengeist provides a CLI, based on the flask CLI, respectivly called flaschengeist.
⚠️ When using the CLI for running Flaschengeist, please note that logging will happen as configured,
with the difference of the main logger will be forced to output to stderr and the logging level
of the CLI will override the logging level you have configured for the main logger.
$ flaschengeist run
or with debug messages:
$ 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.