98 lines
3.4 KiB
Markdown
98 lines
3.4 KiB
Markdown
# Flaschengeist
|
|
|
|
|
|
This is the backend of the Flaschengeist.
|
|
|
|
# Installation
|
|
## Main package
|
|
### System dependencies
|
|
- **python 3.7+**
|
|
- Database (MySQL / mariadb by default)
|
|
|
|
By default Flaschengeist uses mysql as database backend,
|
|
if you are on Windows Flaschengeist uses `PyMySQL`, which does not require any other system packages.
|
|
|
|
But on Linux / Mac / *nix 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, 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.
|
|
*Hint:* The same command can be later used to upgrade the database after plugins or core are updated.
|
|
|
|
$ 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 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).
|