Déploiement

Prérequis

Comme tout service autohébergé et déployé en ligne, hiboo nécessite un minimum de connaissances en administration système qui ne sont pas couvertes par cette documentation (reverse proxy, base de donnée, etc).

Les instructions qui suivent supposent que vous disposez d'une base de donnée PostgreSQL, MariaDB ou SQLite.

Installation

Utiliser l'image Docker

# avec Docker
docker pull docker.tedomum.net/acides/hiboo:main
docker run --name hiboo hiboo:dev
docker exec -it hiboo sh -c "flask db upgrade"

# avec Podman
podman pull docker.tedomum.net/acides/hiboo:main
podman run --name hiboo hiboo:dev
podman exec -it hiboo sh -c "flask db upgrade"

Installation manuelle sur Debian avec Poetry

Note : Pour le moment Hiboo ne propose pas de paquet prêt à l'exécution, il faut donc build les assets et la documentation. À terme un paquet complet sera distribué.

Installation des dépendances et de Poetry

apt install python3 python3-dev pkg-config nodejs npm curl xmlsec1
curl -sSL https://install.python-poetry.org | python3 -

Installation de Hiboo

Télécharger le code source depuis la dernière version publiée sur la forge de Hiboo, la décompresser puis installer les dépendances :

cd hiboo-{x.x.x}
poetry install --with prod

Compilation des assets

npm ci
./node_modules/.bin/webpack-cli

Compilation de la documentation intégrée

export FLASK_APP=hiboo
poetry run mkdocs build -f docs/config/en.yml
poetry run mkdocs build -f docs/config/fr.yml

Initialisation de la base de données

export FLASK_APP=hiboo
poetry run flask db upgrade

Lancement du serveur web

poetry run gunicorn --workers 4 \
  --bind '[::]:8080' \
  --access-logfile - --error-logfile - \
  --preload 'hiboo:create_app()'

Attention : Pour ne pas exposer directement Gunicorn sur internet, utilisez un reverse-proxy.

Lancement des tâches de fond

poetry run flask tasks loop

Services Systemd

Il est recommandé de créer un service pour faciliter le lancement et le redémarrage de Hiboo, et un autre pour les tâches de fond. Par exemple :

[Unit]
Description=Gunicorn instance to serve Hiboo
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/hiboo
EnvironmentFile=/var/www/hiboo/.env
ExecStart=poetry run gunicorn --workers 4 \
  --bind '[::]:8080' --log-level warning \
  --access-logfile - --error-logfile - \
  --preload 'hiboo:create_app()'

[Install]
WantedBy=multi-user.target

[Unit]
Description=Run Hiboo tasks loop
After=hiboo.service

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/hiboo
EnvironmentFile=/var/www/hiboo/.env
ExecStart=poetry run flask tasks loop

[Install]
WantedBy=multi-user.target

Configuration

Hiboo peut être configuré par des variables d'environnement. Voici la liste des paramètres importants et de leurs valeurs par défaut :

nom	valeur par défaut
`WEBSITE_NAME`	`Hiboo`
`SQLALCHEMY_DATABASE_URI`	`sqlite:////tmp/hiboo.db`
`SECRET_KEY`	`changeMe`
`API_TOKEN`	`changeMe`
`OPEN_SIGNUP`	`True`
`CACHE_TYPE`	`SimpleCache`
`RATELIMIT_STORAGE_URI`	`None`
`MAIL_DOMAIN`	`domain.tld`
`USER_TIMEOUT`	`2592000`
`USERNAME_BLOCKLIST`	`username_blocklist()`
`DEBUG`	`False`
`BABEL_DEFAULT_LOCALE`	`en`

`WEBSITE_NAME`

Le nom du site web sur lequel est installée l'instance Hiboo.

`SQLALCHEMY_DATABASE_URI`

URI tel que défini dans Flask-SQLAlchemy.

Pour PostgreSQL :

postgresql://user:password@localhost:port/mydatabase

Pour MariaDB :

mysql://user:password@localhost:port/mydatabase

`SECRET_KEY`

Cette clé est nécessaire notamment pour générer les différents jetons utilisés par Hiboo. Il est possible de générer une telle clé avec openssl :

openssl rand -base64 32

`API_TOKEN`

Le jeton de connexion nécessaire pour s'authentifier auprès de l'API de Hiboo. Voir SECRET_KEY pour le générer.

`OPEN_SIGNUP`

Si False, un lien d'invitation généré par l'admin sera nécessaire pour accéder au formulaire d'inscription. Si True, le formulaire d'inscription sera accessible publiquement.

`CACHE_TYPE`

Hiboo utilise Flask-Caching pour gérer le cache de l'application. Vous trouverez tous les types de cache supportés et toutes leurs options sur sa documentation officielle.

Note : en production, il est recommandé d'utiliser un cache de type Redis.

CACHE_TYPE = RedisCache
CACHE_REDIS_URL = redis://redis:6379/0

`RATELIMIT_STORAGE_URI`

Par défaut, Flask-Limiter conserve les données dans la RAM. Il est recommandé d'utiliser un backend persistant tel que Redis. Voir à ce sujet la documentation officielle

`MAIL_DOMAIN`

Ce paramètre est utilisé uniquement pour générer des emails aux profils inscrits sur des services qui n'ont pas accès aux emails des utilisateurices. Veillez à utiliser un domaine lié à un serveur mail que vous pouvez maitriser.

Voir la description détaillée dans la documentation des services

`USER_TIMEOUT`

Durée en secondes avant qu'un compte soit supprimé s'il ne possède aucun profil ou si tous ses profils sont purgés. Par défaut, ce paramètre est réglé sur 30 jours.

`USERNAME_BLOCKLIST`

Set Python contenant des noms jugés dangereux à utiliser pour des noms d'utilisateurices et des noms de profils. Contient par défaut :

les noms d'utilisateurices et de groupes communs dans Linux
les UUID réservés au système dans Linux
les nom communs dans les services web
les nom communs spécifiques à Hiboo

La liste complète est visible dans le code. Voir aussi la documentation sur les profils.

Il est possible d'écraser cette variable en passant une chaine de caractère interprétable par Python comme un set, par exemple :

USERNAME_BLOCKLIST=("alice", "bob", "mallory")

`DEBUG`

True : mode debug de Flask permet d'afficher le détail des requêtes et les exceptions dans l'interface web.

Attention : ne pas activer en production !

`BABEL_DEFAULT_LOCALE`

Langue utilisée par défaut si aucune langue préférée par le navigateur et supportée par Hiboo n'est trouvée. Pour l'instant, les langues supportées sont en et fr.