Documentation en ligne

Installation d'un environnement de développement local

Ce document explique le fonctionnement d'un ensemble de playbooks Ansible qui installe les sources et configure, pour le développement local, l'ensemble des briques de Publik. Pour mieux comprendre le rôle de toutes ces briques, lisez le document présentation générale.

Pré-requis système

  • Debian 10 buster (stable) ou Debian bullseye (testing) : l'environnement de développement Publik fonctionne sous Debian. Si vous utilisez un autre système nous conseillons vivement d'installer une machine virtuelle ou un conteneur Linux sous Debian
  • l'utilisateur linux utilisé doit être sudoer mais doit ne pas être l'utilisateur root

Installer les logiciels suivant :

  • Ansible (une version supérieure ou égale à 2.5 est nécessaire)
  • Git

Via la commande :

    sudo apt install git ansible

Installer Publik

Ne pas lancer les commandes en tant qu'utilisateur root

  • Clonez le dépôt git publik-devinst :
    git clone https://git.entrouvert.org/publik-devinst.git && cd publik-devinst
  • lancer la playbook d'installation de Publik
  ansible-playbook -K -i inventory.yml install.yml

Votre mot de passe sudo vous sera demandé, voir ici si vous voulez savoir pourquoi.

  • lancer le déploiement d'un tenant
  ansible-playbook -i inventory.yml deploy-tenants.yml

Vous avez maintenant une instance de Publik fonctionnelle qui tourne sur votre machine, accessible à cette adresse : https://combo.dev.publik.love/.

Utilisateur : admin@localhost
Mot de passe : admin

  1. Après votre première authentification, si vous ne voyez pas d'entrée "Fabrique de formulaires" et/ou "Fabrique de workflows" dans le menu, une visite sur la page suivante devrait résoudre le problème : https://wcs.dev.publik.love/login .
  2. Sur les pages "Fabrique de formulaires" vous sera indiqué la nécessité de "définir des rôles", rendez vous sur https://authentic.dev.publik.love/manage/roles/ pour créer un rôle.

Administration système

  • Le code source des briques de publik sont disponibles dans dépôts git dans /home/utilisateur/src
  • Les briques sont installés dans un virtualenv python qui se trouve ici /home/utilisateur/envs/publik-env

Services

Les services qui constituent votre instance de Publik sont les suivants :

  • authentic-multitenant
  • bijoe
  • chrono
  • combo
  • fargo
  • hobo
  • hobo-agent
  • passerelle
  • wcs
  • welco

Les services sont démarrés automatiquement et sont gérés par supervisord.
Pour faire des opérations sur un service :

sudo supervisorctl {start|status|stop} nomduservice

Par exemple :

sudo supervisorctl {start|status|stop} passerelle

Les logs des service sont disponibles dans /var/log/nomduservice/stderr.log et /var/log/nomduservice/stdout.log

Pour faire tourner un service dans une console :

sudo supervisorctl stop nomduservice
/home/utilisateur/envs/publik-env/bin/nomduservice-server

Par exemple :

sudo supervisorctl stop passerelle
/home/utilisateur/envs/publik-env/bin/passerelle-server

Attention certains services tournent en python3 (combo, chrono), ce qui donne un chemin différent :

/home/utilisateur/envs/publik-env-py3/bin/chrono-server
/home/utilisateur/envs/publik-env-py3/bin/combo-server

Des directives de configuration django peuvent être ajoutés dans un ou plusieurs fichiers python, à placer dans /home/utilisateur/.config/publik/settings/nomduservice/settings.d/.
En revanche ne pas modifier /home/utilisateur/.config/publik/settings/nomduservice/settings.py, fichier de configuration principal d'un service, qui sera écrasé lors d'une mise à jour de votre installation.

Commandes d'administration

Les commandes d'administration de chaque service sont disponibles dans /home/utilisateur/envs/publik-env/bin/nomduservice-manage, par exemple :

/home/utilisateur/envs/publik-env/bin/passerelle-manage

Attention certains services tournent en python3 (combo, chrono), ce qui donne un chemin différent :

/home/utilisateur/envs/publik-env-py3/bin/chrono-manage
/home/utilisateur/envs/publik-env-py3/bin/combo-manage

Utilisation avancée des playbook

Personnalisation de l'installation

Toutes les variables déclarées dans inventory.yml et group_vars/all permettent de personnaliser l'installation et peuvent être surchargées dynamiquement à l'invocation de la commande ansible-playbook en utilisant la syntaxe ci-dessous.

  -e "{var_name: var_value}" 

Voici quelques exemples :

  • Ne pas compiler les thèmes
ansible-playbook -K -i inventory.yml -e "{compile_theme: False}" install.yml
  • Cloner les dépôts git en utilisant le protocole ssh
ansible-playbook -K -i inventory.yml -e "{git_ssh: True}" install.yml
  • Ne pas cloner les dépôts git (ce qui nécessite d'indiquer où se trouve les sources)
ansible-playbook -K -i inventory.yml -e "{clone_repo: False, src_dir: /path/to/source/directory}" install.yml

Alternativement, pour ne pas passer une myriade de paramètres sur la ligne de commande, vous pouvez les inscrire dans votre propre inventaire (en se basant sur inventory.yml),
et invoquer comme suit :

ansible-playbook -K -i my-inventory.yml install.yml

Suppression de l'installation

ansible-playbook -K -i inventory.yml clean.yml

Déploiement d'un nouveau tenant

D'abord, notez que chaque brique de Publik tourne dans un serveur web sécurisé indépendant et fonctionne selon une architecture multi-tenants.
Chaque tenant (une instance locale d'une brique Publik) est identifié par son URL.
Vous pouvez déployer de nouveaux tenants en plus de ceux déployés par défaut.
Pour ce faire, renommer fichier tenants-inventory.yml.example en tenants-inventory.yml, l'éditer et remplacer customname par un nom de votre choix,
puis invoquer le playbook de déploiement de tenant.

ansible-playbook -i tenants-inventory.yml deploy-tenants.yml

(qu'il faut parfois lancer plusieurs fois et être patient en raison des messages RabbitMQ qu ne sont pas consommés ni ackés à cette date)

Pendant l’exécution, vous pouvez lire les logs de votre "agent" hobo qui configure vos tenants :

sudo tail -f /var/log/hobo-agent/stderr.log

Suppression d'un tenant

ansible-playbook -i tenants-inventory.yml delete-tenants.yml

Certificat TLS

Nous proposons un certificat wildcard qui couvre tous les noms *.dev.publik.love, ce certificat est téléchargé à l'installation.
Notez qu'il s'agit d'un certificat LetsEncrypt, donc sa durée de vie n'est pas longue, trois mois au mieux. Si la version que vous aviez téléchargé a expiré,
vous pouvez télécharger un certificat valide avec la commande :

  ansible-playbook -i inventory.yml --tags "tls" install.yml

DNS

La zone dev.publik.love est configurée pour que tous les noms foobar.dev.publik.love aient comme adresse 127.0.0.1, c'est-à-dire votre machine.

Pour vérifier que la résolution DNS fonctionne :

$ host foobar.dev.publik.love
foobar.dev.publik.love has address 127.0.0.1

Si le serveur DNS de votre fournisseur d'accès est menteur (par exemple chez l'opérateur Free) alors ça ne marchera pas. Utilisez plutôt un service de DNS correct tel que Quad9 (9.9.9.9) ou installez un résolveur chez vous.

Si vous travaillez sans connexion Internet, ou si vous utilisez un autre nom de domaine, vous pouvez éditer votre fichier /etc/hosts, par exemple :

# à poser à la fin de /etc/hosts, à adapter selon les noms des sites que vous avez choisi de déployer
127.0.0.1  agent-combo.dev.publik.love authentic.dev.publik.love bijoe.dev.publik.love chrono.dev.publik.love combo.dev.publik.love fargo.dev.publik.love hobo.dev.publik.love  passerelle.dev.publik.love wcs.dev.publik.love

Mot de passe sudo

Une série de fichiers à l'extérieur du répertoire personnel doivent être modifiés, c'est la raison pour laquelle l'accès "sudo" est demandé lors de l'installation.
Voici le liste des actions effectuées par le playbook qui nécessitent les droits administrateurs :

  • installation de paquets systèmes (la liste est disponible au début du fichier roles/base/tasks/main.yml)
  • création d'un rôle et de bases de données postgres
  • création de fichiers de configuration supervisord dans /etc/supervisor/conf.d
  • création de fichiers de configuration nginx dans /etc/nginx/sites-enabled et /etc/nginx/sites-available
  • création d'une clé secrète pour chaque service de publik (/etc/nomduservice/secret)
  • création d'un répertoire dans /var/lib/nomduservice pour chaque application
  • création d'un répertoire de log dans /var/log/nomduservice pour chaque application

Obtenir de l'aide

En cas de problème à l'installation vous pouvez obtenir de l'aide en créant une demande de support ici : https://dev.entrouvert.org/projects/publik-devinst/issues.
Merci de décrire aussi précisément que possible le problème rencontré, de l'illustrer avec des captures d'écran, etc.

Dernière mise à jour le 16 décembre 2019 03:25 — Éditer