117 lines
4.1 KiB
Markdown
117 lines
4.1 KiB
Markdown
# Flaschengeist
|
|
|
|
|
|
This is the backend of the Flaschengeist.
|
|
|
|
## Installation
|
|
### Requirements
|
|
- `mysql` or `mariadb`
|
|
- maybe `libmariadb` development files[1]
|
|
- 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](https://www.radishlogic.com/coding/python-3/installing-mysqldb-for-python-3-in-windows/)
|
|
|
|
### 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.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
|
|
|
|
### 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](https://flaschengeist.dev/Flaschengeist/flaschengeist/wiki/Development).
|