Installation — vue d'ensemble

Liberty Next est distribué sous forme d'une image OCI publique (ghcr.io/fblettner/liberty-next) accompagnée d'un répertoire release/ qui rassemble trois fichiers compose + deux surcouches TLS + une surcouche d'applications + quatre scripts d'aide qui les articulent. Choisir une variante, lancer une commande, et le tour est joué.

Variante	Runtime	Services	Cas d'usage
Légère	Docker Compose	liberty-next + SQLite (sur un volume)	Essai local, démo mono-utilisateur, évaluation rapide.
Complète	Docker Compose	liberty-next + PostgreSQL 16 + Traefik + pgAdmin + Portainer	Production / staging sur un hôte unique.
Swarm	Docker Swarm	les mêmes cinq services, avec des contraintes `deploy.*` et un réseau overlay	Swarm mono ou multi-nœud.
pipx	Python natif	liberty-next seul (SQLite par défaut, pointable vers toute base)	Hôtes sans Docker, environnements purement Python.

Les variantes Légère et Complète peuvent être combinées avec une surcouche TLS (Let's Encrypt ou certificats fournis par l'opérateur) et avec la surcouche d'applications sous licence (plugins Nomasx-1 / Nomajde / Nomaflow). Les quatre surcouches sont articulées automatiquement par les options de ./install.sh ; il n'y a jamais à manipuler d'option -f à la main.

L'installation en 60 secondes

git clone https://github.com/fblettner/liberty-next.git
cd liberty-next/release

./install.sh                                  # interactif — demande légère ou complète
# OU — non interactif
./install.sh light                            # un seul conteneur, SQLite
./install.sh full                             # pile de production à 5 services (tag latest)
./install.sh full --tag 7.0.2                 # pile complète, épinglée à une version précise

Ce que fait install.sh au premier lancement :

Étape	Détail
1. Détecte les volumes Docker résiduels d'une installation précédente.	Si `pg-data` / `pgadmin-data` / `liberty-data` existent mais que `.env` est absent, le script REFUSE de démarrer et invite l'opérateur à relancer avec `--reset` (purge + redémarrage à neuf) ou à restaurer le `.env` précédent (les secrets gravés dans les volumes doivent correspondre).
2. Génère un `.env` avec des secrets cryptographiquement aléatoires (aucun caractère `$` — la substitution Compose ne peut pas les absorber).	Au premier lancement uniquement — les exécutions suivantes préservent un `.env` existant.
3. Écrit `COMPOSE_FILE=docker-compose.<variante>.yml[:surcouches...]` dans `.env`.	Chaque `docker compose <cmd>` ultérieur (sans `-f`) fusionne automatiquement les bons fichiers. Critique — l'opérateur ne doit PAS passer `-f` à la main après l'installation.
4. Récupère les images via `docker compose pull` et lance `docker compose up -d`.	Ré-exécutable sans risque — relancer sur une pile déjà active ne fait que ré-appliquer le fichier compose.
5. Attend jusqu'à 120 s que le healthcheck du conteneur passe (`GET /info`).	Annonce `healthy` quand la SPA et l'API sont prêtes.
6. Affiche l'URL de la SPA, le mot de passe `admin` généré et les URL des tableaux de bord pgAdmin / Portainer / Traefik.	Le mot de passe est également conservé dans `.env` (mode `0600`).

Pour Docker Swarm, l'équivalent est ./deploy-swarm.sh (détaillé dans Docker → Swarm).

Les options d'install.sh à connaître

Option	Rôle
`--tag <version>`	Épingle `LIBERTY_IMAGE_TAG` au moment de l'installation (par exemple `--tag 7.0.2`). Valeur par défaut `latest` (chaque merge sur main → nouvelle release ; `latest` reflète toujours l'état courant de main). Ignorée si `.env` existe déjà — modifier la variable directement à cet endroit.
`--reset`	`docker compose down -v` + suppression de `.env` au préalable. À utiliser quand une installation précédente a laissé un `pg-data` résiduel avec l'ancien mot de passe (l'initialisation Postgres ne s'exécute que sur un volume vierge — secrets neufs + volume résiduel = échec d'authentification permanent).
`--apps <wheel-ou-URL>`	Après avoir monté la pile de base, enchaîne avec `install-apps.sh` sur le wheel indiqué — les applications sous licence (Nomasx-1 / Nomajde / Nomaflow) sont déployées dans la même commande. La clé de licence se définit ensuite via Settings → App → License dans l'interface (chiffrée au repos dans `app.toml`).
`--ssl letsencrypt --domain --email` (variante complète uniquement)	Branche Let's Encrypt automatiquement. L'hôte doit être joignable depuis l'Internet public sur `:80`/`:443` pour le challenge TLS-ALPN.
`--ssl provided --cert-dir --cert-file --key-file` (variante complète uniquement)	Branche des certificats fournis par l'opérateur (CA d'entreprise, PKI interne, installation en air-gap). `install.sh` vérifie l'existence des fichiers, monte le répertoire de certificats en bind, génère `traefik/dynamic/tls.yml`.

Les quatre options se combinent — ./install.sh full --tag 7.0.2 --ssl letsencrypt --domain liberty.example.com --email ops@example.com --apps ./liberty_apps-7.0.1-py3-none-any.whl réalise en une seule commande une installation de production avec TLS et le bundle sous licence. Une fois l'interface en service, coller la clé de licence dans Settings → App → License. (--license-key a été retiré de install.sh — la clé se trouve désormais dans app.toml, chiffrée au repos, et non plus dans .env.)

Une option de purge complète mérite également d'être connue :

Option Rôle

--reset docker compose down + docker volume rm de chaque volume de données Liberty (pg-data, pgadmin-data, portainer-data, liberty-data, liberty-config) + suppression de .env, puis sortie immédiate. Le volume traefik-acme est délibérément préservé (Let's Encrypt limite à 5 certificats par 7 jours et par ensemble de domaines — le purger à chaque cycle de réinitialisation épuiserait ce quota presque immédiatement). Combiner --reset avec --apps ou --ssl provoque une erreur — relancer install.sh avec les options souhaitées une fois la réinitialisation terminée. À utiliser quand une installation précédente a laissé des volumes résiduels dont les identifiants ne correspondent plus à un .env régénéré.

Option	Rôle
`--reset`	`docker compose down` + `docker volume rm` de chaque volume de données Liberty (`pg-data`, `pgadmin-data`, `portainer-data`, `liberty-data`, `liberty-config`) + suppression de `.env`, puis sortie immédiate. Le volume `traefik-acme` est délibérément préservé (Let's Encrypt limite à 5 certificats par 7 jours et par ensemble de domaines — le purger à chaque cycle de réinitialisation épuiserait ce quota presque immédiatement). Combiner `--reset` avec `--apps` ou `--ssl` provoque une erreur — relancer `install.sh` avec les options souhaitées une fois la réinitialisation terminée. À utiliser quand une installation précédente a laissé des volumes résiduels dont les identifiants ne correspondent plus à un `.env` régénéré.

Le modèle mental de COMPOSE_FILE

Après ./install.sh full --ssl letsencrypt --apps <wheel>, .env contient :

.env (extrait)
COMPOSE_FILE=docker-compose.full.yml:docker-compose.tls-letsencrypt.yml:docker-compose.apps.yml

Docker Compose lit COMPOSE_FILE à chaque commande — docker compose ps / pull / up -d / down / logs / restart fusionnent automatiquement toutes les surcouches listées. L'opérateur ne tape jamais -f.

À faire	À éviter
`docker compose pull && docker compose up -d` (prend en compte chaque surcouche)	`docker compose -f docker-compose.full.yml up -d` (perd les surcouches apps + TLS)
`docker compose logs -f liberty-next` (contexte fusionné)	`docker compose -f docker-compose.full.yml logs -f` (aucune surcouche)

install-apps.sh et l'option --ssl ajoutent tous deux à COMPOSE_FILE — relancer install.sh avec un nouveau mode --ssl (ou enchaîner install-apps.sh) met la valeur à jour proprement. Une édition manuelle de .env est également possible ; la chaîne est séparée par des deux-points, et l'ordre compte (les surcouches s'appliquent de droite à gauche).

Les trois variantes Docker

Légère — un seul conteneur, SQLite

Contenu :

Un conteneur (liberty-next) sur le port 8000.
Base SQLite du framework (authentification + historique d'exécution Nomaflow) enregistrée sur un volume Docker.
Fichiers TOML édités par l'opérateur enregistrés sur un second volume — sauvegardés depuis Settings → … dans la SPA ; aucun bind-mount hôte n'est nécessaire.
Pas de Postgres, pas de Traefik, pas de TLS — le framework est mis à disposition directement sur :8000.

À retenir pour les essais, les démos, l'évaluation, les installations mono-utilisateur. Les applications sous licence (Nomasx-1 / Nomajde) fonctionnent aussi sur la variante Légère quand un Postgres multi-utilisateur n'est pas requis — ./install.sh light --apps <wheel> est pris en charge.

Volumes :

Volume	Contenu
`liberty-data`	Base SQLite + `auth.toml` (empreintes Argon2 des mots de passe).
`liberty-config`	Tous les fichiers TOML édités par l'opérateur (connecteurs / dictionnaire / menus / écrans / graphiques / tableaux de bord).

Complète — pile de production derrière Traefik

Cinq services, tous sur le port 80 de l'hôte (ou 443 une fois le TLS branché) :

Service	Chemin	Détail
Traefik	`/traefik`	Reverse proxy + tableau de bord. Authentification basique (par défaut `admin/admin` — à changer dans `traefik/dynamic/dynamic.yml`).
liberty-next	`/` (catchall)	SPA + API + administration. Se connecte au Postgres embarqué pour la base du framework.
Postgres 16	(interne `:5432`, exposé par défaut)	Base du framework (authentification, historique Nomaflow) et emplacement pour héberger les pools client (données Nomasx-1 / Nomajde).
pgAdmin	`/pgadmin`	Interface graphique Postgres.
Portainer	`/portainer`	Interface Docker.

Volumes :

Volume	Contenu
`liberty-config`	TOML édités par l'opérateur.
`pg-data`	Fichiers de la base Postgres.
`pgadmin-data`	Enregistrements et préférences pgAdmin.
`portainer-data`	État Portainer.
`traefik-acme`	Stockage des certificats Let's Encrypt (quand TLS Let's Encrypt est actif).

C'est la variante visée par les bundles sous licence (Nomasx-1, Nomajde) — le Postgres embarqué héberge leur pool par défaut. Voir Déployer les applications préassemblées.

Swarm — Docker Swarm, mono ou multi-nœud

Les mêmes cinq services, mais avec des clés deploy.*, un réseau overlay, le mode --providers.swarm de Traefik et les services à état épinglés à un unique manager. Déploiement / mise à jour / état avec ./deploy-swarm.sh — docker stack deploy ne prend pas d'option --env-file, donc le script charge d'abord .env dans le shell.

Note : les options --apps et --ssl de install.sh sont réservées à Compose — sur Swarm, les opérateurs appliquent les surcouches en éditant le fichier de stack ou en enchaînant un docker stack deploy séparé avec la surcouche fusionnée.

La surcouche d'applications sous licence

Nomasx-1, Nomajde et les jobs Nomaflow embarqués sont livrés sous la forme d'un unique wheel liberty_apps-<version>-py3-none-any.whl. Deux chemins d'installation :

En une seule commande (hôte vierge)

./install.sh full --apps ./liberty_apps-7.0.1-py3-none-any.whl

L'ensemble est traité en une fois — pile de base + applications sous licence. Une fois la SPA en service, coller le JWT de licence signé par l'éditeur dans Settings → App → License (chiffré au repos avec la clé maître d'installation, prise en compte à la sauvegarde — les connecteurs sont reconstruits sans redémarrage). Voir Paramètres de l'application.

Ou en deux temps : base d'abord, applications ensuite

./install.sh full                                              # pile de base
./install-apps.sh ./liberty_apps-7.0.1-py3-none-any.whl        # ajout des applications

Ce que fait install-apps.sh :

Matérialise le wheel dans ./apps/ via un conteneur python:3.12-slim jetable — l'hôte n'a besoin d'aucune installation locale de pip ou de Python. Le wheel embarque une CLI liberty-apps install --target DIR qui copie config/ et plugins/ vers la destination, en préservant les TOML édités par l'opérateur.
Met à jour .env — ajoute docker-compose.apps.yml à COMPOSE_FILE et définit APPS_HOST_PATH=<chemin absolu>. La clé de licence n'est pas écrite dans .env — la définir via l'interface une fois les applications visibles.
Redémarre la pile — docker compose up -d prend en compte la surcouche d'applications automatiquement via COMPOSE_FILE (sans manipulation de -f).

Détail complet : Déployer les applications préassemblées.

La voie pipx — sans aucun Docker

Pour qui ne veut pas de conteneurs (petite installation sur un seul hôte, environnement contraint à Python) :

pipx install liberty-next
liberty-next             # → API + SPA sur http://localhost:8000

pipx place Liberty Next dans son propre venv isolé, ce qui empêche ses dépendances d'entrer en conflit avec le Python système. Les quatre commandes CLI (liberty-next, liberty-admin, liberty-license, liberty-crypto) atterrissent dans le PATH. Mises à jour : pipx upgrade liberty-next. Voir Serveur Python.

Il convient de faire pointer LIBERTY_DB_URL vers un Postgres existant (ou de rester sur la SQLite par défaut — ./liberty.db dans le répertoire de travail). Les TOML de configuration sont lus depuis ./config/<name>.toml ; définir LIBERTY_APPS_DIR=/etc/liberty-next/ permet de les conserver à un emplacement stable.

En un coup d'œil

Variables d'environnement requises

Deux valeurs sont obligatoires quelle que soit la variante — install.sh les génère toutes deux avec openssl rand. Avec pipx ou un compose maison, il revient à l'opérateur de les générer.

Variable	Rôle	Comment la générer
`LIBERTY_JWT_SECRET`	Signe chaque jeton d'accès et de rafraîchissement. Doit rester stable entre les redémarrages — une clé rotée invalide tous les jetons en cours (oblige chaque utilisateur à se reconnecter).	`python -c "import secrets;print(secrets.token_urlsafe(48))"`
`LIBERTY_MASTER_KEY`	Clé de chiffrement au niveau du champ — chiffre les secrets (mots de passe de pool, jetons d'API) au repos dans les TOML. Doit rester identique, sans quoi les valeurs `ENC:` deviennent illisibles.	`python -c "import secrets;print(secrets.token_urlsafe(32))"`

Variables optionnelles courantes (la liste complète se trouve dans release/.env.example) :

Variable	Valeur par défaut	Détail
`LIBERTY_IMAGE_TAG`	`latest`	Épingler à un tag de version précis pour la stabilité (`7.0.1`, `7.0.2`, etc.). Utiliser `./install.sh --tag <ver>` pour la définir à l'installation.
`LIBERTY_ADMIN_PASSWORD`	(généré, affiché une seule fois dans le récapitulatif d'installation)	Mot de passe d'amorçage pour l'utilisateur `admin` au premier démarrage. `install.sh` génère une valeur aléatoire, l'exporte dans le shell pour le boot, puis l'abandonne — non écrite dans `.env`. Aux exécutions suivantes, l'administrateur existant conserve son mot de passe ; réinitialisation via `docker exec liberty-next liberty-admin reset-admin-password`.
`POSTGRES_PASSWORD`	(généré)	Variante complète uniquement — mot de passe du Postgres embarqué.
`PGADMIN_PASSWORD`	(généré)	Variante complète uniquement — mot de passe administrateur pgAdmin. L'adresse e-mail par défaut est `admin@liberty.fr` (à remplacer via `PGADMIN_EMAIL`).
`APPS_HOST_PATH`	(défini par `install-apps.sh`)	Chemin absolu vers le répertoire `./apps/` matérialisé. La surcouche d'applications le monte en bind à `/apps:ro`.
`COMPOSE_FILE`	(défini par `install.sh` + `install-apps.sh`)	Chaîne de fichiers compose, séparés par des deux-points, que Docker Compose fusionne automatiquement.
`LIBERTY_DOMAIN`, `ACME_EMAIL`	(définis par `--ssl letsencrypt`)	Nom d'hôte TLS et contact ACME.
`CERT_HOST_PATH`	(défini par `--ssl provided`)	Répertoire hôte monté en bind à `/etc/certs:ro` pour les certificats de l'opérateur.

La clé de licence, la clé d'API Anthropic et le secret client OIDC étaient auparavant des variables d'environnement (LIBERTY_LICENSE_KEY, ANTHROPIC_API_KEY, LIBERTY_OIDC_CLIENT_SECRET). Ces valeurs se trouvent désormais dans app.toml, chiffrées au repos avec la clé maître d'installation — à modifier via Settings → App dans la SPA une fois la pile en service. La voie par variable d'environnement reste disponible en repli (définir la variable et la référencer depuis app.toml sous la forme ${VAR}). Voir Paramètres de l'application.

À propos du $ dans les mots de passe

Docker Compose applique aussi la substitution ${VAR} à chaque valeur de .env — un $ littéral dans un mot de passe est absorbé (par exemple POSTGRES_PASSWORD=foo$bar devient foo, Compose cherchant à étendre $bar). Il est recommandé de générer des mots de passe sans $ (ce que fait install.sh), ou bien d'échapper chaque $ en $$.

Étape	Page
0	Cette vue d'ensemble.
1	Choisir un chemin : Docker (couvre les trois variantes Docker) ou Serveur Python (pipx).
2	Brancher le TLS — Traefik détaille les deux modes `--ssl` (Let's Encrypt et certificats fournis par l'opérateur).
3	Utiliser les outils visuels embarqués — Portainer + pgAdmin.
4	Durcissement production — OIDC, rotation JWT, sauvegardes, précautions multi-réplique : Production.
5	Déployer NomaUBL / Nomasx-1 / Nomajde par-dessus : Déployer les applications préassemblées.
6	Quand une nouvelle version sort : Mise à niveau.

Vérification rapide — à quoi ressemble une installation réussie

Après le chemin retenu :

curl http://<host>:<port>/info renvoie une charge JSON avec version, frontend_built et le décompte des écrans / menus / connecteurs chargés.
La SPA s'affiche sur http://<host>:<port>/.
Connexion en tant qu'admin avec le mot de passe affiché par install.sh (montré une seule fois pendant l'installation ; non conservé dans .env).
Le conteneur liberty-next apparaît sain dans docker ps (le healthcheck embarqué interroge /info toutes les 30 s).

Si l'une de ces vérifications échoue, se rendre à la section de dépannage du chemin choisi.

La suite

Docker — les trois variantes Docker en détail, avec le pas-à-pas des scripts d'aide et la discipline COMPOSE_FILE.
Serveur Python — installation via pipx pour les hôtes sans Docker.
Production — TLS, sauvegardes, durcissement.

L'installation en 60 secondes​

Les options d'install.sh à connaître​

Le modèle mental de COMPOSE_FILE​

Les trois variantes Docker​

Légère — un seul conteneur, SQLite​

Complète — pile de production derrière Traefik​

Swarm — Docker Swarm, mono ou multi-nœud​

La surcouche d'applications sous licence​

En une seule commande (hôte vierge)​

Ou en deux temps : base d'abord, applications ensuite​

La voie pipx — sans aucun Docker​

En un coup d'œil​

Variables d'environnement requises​

À lire dans l'ordre​

Vérification rapide — à quoi ressemble une installation réussie​

La suite​