Installer Libris avec Docker

Ce guide s’adresse à quiconque veut faire fonctionner Libris Translate (Libris en abrégé) sur sa propre machine ou son propre serveur. Inutile de connaître Python ou Node.js : Docker fait le travail. À la fin, Libris tournera, vous serez connecté, il sera relié à un modèle de langage et traduira un premier livre. Les sections suivantes traitent de l’accès réseau, du HTTPS, des mises à jour, de la désinstallation et des problèmes courants.

Ce qu’il vous faut

• Une machine Linux (x86-64 / AMD64) disposant d’au moins 2 Go de mémoire libre, et de l’espace disque pour vos livres, leurs traductions, les exports et les sauvegardes.
• Docker Engine 26 ou plus récent avec le plugin Compose v2. Suivez le guide d’installation de Docker pour votre distribution.
• Un modèle de langage que Libris peut joindre par le réseau : un service hébergé avec une clé d’API (OpenAI, Anthropic ou tout provider compatible OpenAI) ou votre propre serveur d’inférence. Libris lui-même n’a besoin d’aucun GPU.

Vérifiez Docker avant de continuer :

docker version
docker compose version

La bibliothèque et son historique sont stockés sur votre serveur. Les providers de modèles configurés reçoivent les passages et leur contexte de traduction ; les intégrations facultatives de mémoire externe, de courriel, de webhooks et de livraison reçoivent les données nécessaires aux fonctions que vous activez. Les vérifications de licence envoient l’identité de l’installation et l’usage, pas le texte des livres. Passez ces destinations en revue avant d’importer des contenus confidentiels.

Installer

Une licence — achetée, ou un essai demandé sur le site — arrive par courriel avec deux choses : la clé que vous saisirez dans Paramètres › Licence, et les identifiants en lecture seule du registre d’images qui vous est attribué. Ni archive ni clone Git ne sont nécessaires. Lancez cette seule commande :

curl --fail --location --silent --show-error https://libris-translate.com/install.sh | sudo bash

Le bootstrap essaie d’abord les identifiants déjà enregistrés par Docker. Si aucune connexion valide n’existe, il demande le nom et le jeton de lecture dans le terminal (jamais sur l’entrée standard occupée par le script téléchargé). Il télécharge ensuite registry.libris-translate.com/libris/libris:latest, résout cette étiquette vers un digest immuable, puis :

1. prend le fichier Compose dans cette image précise, afin que la pile ne dérive jamais du code qu’elle exécute ;
2. crée /opt/libris/.env avec des secrets aléatoires et le mot de passe administrateur initial ;
3. télécharge PostgreSQL, migre la base puis démarre l’application web, le worker et le pont Codex ;
4. attend que l’API soit saine, puis affiche l’adresse locale et la commande qui montre le mot de passe.

La première fois, cela prend quelques minutes. Une nouvelle exécution ou une mise à jour conserve la configuration, les secrets et les volumes Docker ; elle ne supprime aucune donnée. latest est la dernière version stable publiée par Libris. Pour installer explicitement la version publique actuelle plutôt que de suivre les prochaines versions stables :

curl --fail --location --silent --show-error https://libris-translate.com/install.sh | sudo env LIBRIS_TAG=0.28.0 bash

À partir de la 0.15, l’installateur voyage lui-même dans chaque image, à côté du fichier Compose et du modèle de configuration (/app/deploy/install.sh, /app/deploy/docker-compose.yml, /app/deploy/env.example). Quelle que soit la copie lancée, il résout l’étiquette demandée en digest puis passe la main à l’installateur de cette image précise : l’installateur, le Compose et le modèle installés sont toujours ceux de la version qui tourne. Sans accès au site, la même installation part du seul registre :

sudo docker pull registry.libris-translate.com/libris/libris:<version>
sudo docker run --rm --entrypoint cat registry.libris-translate.com/libris/libris:<version> /app/deploy/install.sh > install-libris.sh
sudo env LIBRIS_TAG=<version> bash install-libris.sh

Le nouveau .env est écrit en mode 0600 dans un répertoire de préparation voisin de /opt/libris, puis renommé en place d’un seul coup : une première exécution interrompue ne laisse rien, et une exécution interrompue ensuite (téléchargement, migration, démarrage) garde la configuration et reprend quand on relance la même commande. LIBRIS_REGISTRY_USERNAME et LIBRIS_REGISTRY_TOKEN connectent sans question (le jeton ne passe à docker login que par son entrée standard).

Toutes les commandes Compose qui suivent supposent cd /opt/libris. Le scripts/install-docker.sh de l’archive reste un outil pour les contributeurs qui disposent des sources ; il n’est pas requis pour une installation cliente.

Pour restaurer sur une nouvelle machine, posez d’abord le .env sauvegardé, lancez l’installateur avec --no-start (ou LIBRIS_NO_START=1), démarrez seulement database, restaurez la base et les livres, puis démarrez les autres services ; voir sauvegarde et restauration.

Ce qui tourne

Vos données résident dans deux volumes Docker, libris_database et libris_books (un troisième, libris_codex-state, conserve les connexions du pont Codex facultatif). Ils survivent aux mises à jour et aux redémarrages des conteneurs. Le projet Compose s’appelle libris (LIBRIS_PROJECT dans .env) ; gardez ce nom, car un autre nom démarrerait avec des volumes vides.

Une installation faite par une version antérieure tournait sous le nom epub-translator, avec des volumes epub-translator_*. La mise à jour suivante par l’installateur la renomme une fois pour toutes : Libris s’arrête le temps de copier les volumes dans leurs jumeaux libris_*, chaque copie est vérifiée, puis Libris redémarre sous son nouveau nom et .env enregistre LIBRIS_PROJECT=libris. Les volumes epub-translator_* restent intacts ; l’installateur affiche la commande docker volume rm qui les supprime une fois que tout vous convient. S’il manque la place pour une copie, il garde l’ancien nom (LIBRIS_PROJECT=epub-translator) et indique comment réessayer.

Les conteneurs s’exécutent avec un système de fichiers en lecture seule et sans privilèges supplémentaires. Les seuls emplacements accessibles en écriture sont les volumes et une petite zone temporaire.

L’API, le worker et les migrations tiennent aussi un journal dans le volume libris_logs : un fichier par service, lu comme une seule chronologie avec docker compose exec api python -m app.journal (derniers événements, follow, export --since 2h). Les secrets y sont masqués. Voir l’exploitation.

Se connecter

Ouvrez http://localhost:8088 sur la machine où tourne Libris. L’identifiant est admin ; le mot de passe a été généré pour vous. Affichez les deux avec :

grep '^BOOTSTRAP_' .env

Traitez cette sortie comme un mot de passe : ne la collez ni dans des tickets, ni dans des discussions, ni dans des captures d’écran. Changez le mot de passe depuis la page de votre compte après votre première connexion.

L’interface est en français ou en anglais ; changez de langue avec le bouton de langue de la barre supérieure.

Activer la licence

Ouvrez Paramètres › Licence, saisissez la clé reçue par courriel et cliquez sur Activer. L’installation renouvelle ensuite son certificat d’elle-même, toutes les heures ; un certificat vaut 72 heures, si bien qu’une panne du serveur de licences n’interrompt pas votre travail. Tant qu’aucune licence n’est active, Libris importe et affiche les livres mais ne lance ni analyse ni traduction. L’écran indique la formule, les mots du cycle de quota en cours et la date à laquelle le quota repart, et si l’API d’automatisation et le partage des livres sont compris. Ce que permet chaque formule, et les règles du quota, sont dans la référence de configuration.

Changer de serveur : cliquez d’abord sur Libérer cette machine sur l’ancien, puis activez la même clé sur le nouveau.

Relier un modèle de langage

1. Ouvrez Paramètres › Providers LLM et cliquez sur Nouveau provider.
2. Choisissez la Connexion / protocole : OpenAI-compatible · Chat Completions pour la plupart des services et des serveurs locaux, Anthropic · Claude (clé API), OpenAI · Chat Completions (clé API), Codex / OpenAI · clé API (Responses) ou Codex · compte ChatGPT (nécessite le pont facultatif, voir Codex).
3. Saisissez la Base URL (par exemple https://api.example.com/v1), la Clé API et le Modèle.
4. Réglez la Fenêtre de contexte et les Tokens de sortie maximum sur les limites réelles de votre modèle, et Livres simultanés sur le nombre de livres que ce provider peut traiter en même temps.
5. Cliquez sur Enregistrer, puis sur Tester / détecter les modèles.

L’adresse doit être joignable depuis les conteneurs. Dans un conteneur, localhost désigne le conteneur lui-même, pas votre machine. Pour un serveur de modèles sur le même hôte Linux, utilisez l’adresse réseau de l’hôte, ou ajoutez extra_hosts: ["host.docker.internal:host-gateway"] à api et à worker dans un fichier de surcharge Compose et utilisez http://host.docker.internal:<port>.

Obtenir la liste des modèles ne prouve pas que la traduction fonctionne : essayez d’abord un livre court.

Les clés d’API sont stockées chiffrées avec SECRET_KEY et ne sont jamais renvoyées au navigateur.

Traduire un premier livre

1. Dans la bibliothèque, cliquez sur Ajouter du contenu et choisissez Livres EPUB (ou Chapitres TXT (webnovel) pour un web novel, ou des chapitres Markdown, HTML ou DOCX). Choisissez où va le livre : une série existante, une nouvelle série ou un volume indépendant.
2. Ouvrez le livre et cliquez sur Configurer le livre : choisissez le provider, les langues et le niveau de qualité. Laissez la mémoire sur Interne sauf si vous faites tourner OpenViking.
3. Cliquez sur Lancer le pilote automatique. Libris analyse le livre, le traduit, le relit et règle de lui-même les points en suspens ; la page du pilote automatique explique chaque étape.
4. Une fois terminé, cliquez sur Télécharger l’EPUB (Télécharger les chapitres pour un volume texte).

Le guide utilisateur complet, en français, est user-guide.fr.md.

Ouvrir Libris à votre réseau

Par défaut, Libris n’écoute que sur la machine elle-même (127.0.0.1). Les réglages mentionnés ici sont décrits dans la référence de configuration.

Sur un réseau privé (HTTP simple)

Modifiez .env en remplaçant your-server par le nom ou l’adresse IP de la machine. COOKIE_SECURE=false est nécessaire ici, car le navigateur refuse les cookies Secure en HTTP simple sur toute autre adresse que localhost :

BIND_ADDRESS=0.0.0.0
PORT=8088
ALLOWED_ORIGINS=http://your-server:8088
COOKIE_SECURE=false

Appliquez la modification :

docker compose up -d --no-build --wait

Toute personne qui peut joindre ce port peut voir la page de connexion : restreignez-le avec le pare-feu de l’hôte. ALLOWED_ORIGINS vérifie seulement quelle page web a envoyé une requête ; ce n’est pas un pare-feu.

Sur Internet (HTTPS)

Laissez Libris sur 127.0.0.1 et placez devant lui un proxy inverse HTTPS. Dans .env :

BIND_ADDRESS=127.0.0.1
ALLOWED_ORIGINS=https://books.example.com
COOKIE_SECURE=true
FORWARDED_ALLOW_IPS=172.18.0.1

FORWARDED_ALLOW_IPS est l’adresse depuis laquelle les requêtes du proxy atteignent le conteneur, afin que Libris lise l’adresse réelle de chaque visiteur (utilisée dans les journaux et pour ralentir les tentatives de deviner un mot de passe). Pour un proxy sur le même hôte, il s’agit généralement de la passerelle du réseau Compose ; les lignes d’accès de docker compose logs api indiquent de quelle adresse proviennent les requêtes.

Le proxy doit :

• transmettre sans les modifier les en-têtes Origin et Host du navigateur, et définir X-Forwarded-For et X-Forwarded-Proto ;
• accepter des corps de requête jusqu’à MAX_UPLOAD_MB (256 Mo par défaut) ;
• garder ouvertes et sans mise en mémoire tampon les connexions de longue durée pour la progression en direct (/api/projects/<id>/events, server-sent events).

Un exemple nginx minimal (certificats configurés comme d’habitude pour votre serveur) :

server {
    listen 443 ssl;
    server_name books.example.com;

    client_max_body_size 260m;

    location / {
        proxy_pass http://127.0.0.1:8088;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 1h;
    }
}

Un proxy qui tourne dans un conteneur ne peut pas utiliser son propre localhost pour joindre Libris : donnez-lui un réseau Docker partagé ou l’adresse de l’hôte.

Mettre à jour

Lisez le journal des modifications, mettez les livres en cours en pause et faites une sauvegarde, puis relancez la même commande :

curl --fail --location --silent --show-error https://libris-translate.com/install.sh | sudo bash

Elle met l’installation sur le latest stable courant en conservant tous les secrets, comptes, livres et volumes Docker. Pour choisir une version précise :

curl --fail --location --silent --show-error https://libris-translate.com/install.sh | sudo env LIBRIS_TAG=0.28.0 bash

Avant de changer l’image, le bootstrap compare /opt/libris/docker-compose.yml au modèle de l’image installée. Un fichier inchangé est remplacé automatiquement. Un fichier personnalisé n’est jamais écrasé : le nouveau modèle est écrit dans /opt/libris/docker-compose.yml.libris-new, et la mise à jour s’arrête avant de changer LIBRIS_IMAGE. Fusionnez volontairement vos adaptations de proxy ou de montages, puis relancez la commande. Les migrations de base s’exécutent automatiquement avant le démarrage de l’application web. Vérifiez l’état sain puis reprenez les livres mis en pause :

curl --fail http://127.0.0.1:8088/health

Une mise à jour par un simple docker compose pull avance les images mais garde l’ancien fichier Compose. Libris repère ce que la nouvelle version attend et que le fichier ne lui donne pas (un montage comme /logs, celui du journal) : /health répond "configuration": "outdated" ou "degraded", les administrateurs voient un bandeau et le détail dans Paramètres › Santé de l’installation, et librisctl doctor liste les mêmes vérifications. Relancez l’installateur, ou fusionnez docker-compose.yml.libris-new, puis recréez les conteneurs.

Libris ne se met jamais à jour seul. Quand le serveur de licences annonce une version plus récente (il la tient du site, qui publie chaque version une fois ses images disponibles), les administrateurs voient un bandeau « Libris X.Y.Z est disponible » avec le journal des modifications, la commande de l’installateur (ou celle qui fixe LIBRIS_TAG=X.Y.Z) et le même rappel : sauvegarder, mettre les livres en pause. Chaque administrateur peut le masquer pour cette version. Rien n’est montré aux autres membres, ni quand le serveur de licences est plus ancien ou injoignable.

Une image plus ancienne ne peut pas annuler une migration de schéma. Pour revenir en arrière, restaurez la sauvegarde faite avant la mise à jour ; voir sauvegarde et restauration. Pour contrôler plus finement les redémarrages, voir operations (en anglais).

Commandes courantes

docker compose ps                              # état de chaque service
docker compose logs --since=10m api worker     # journaux récents
docker compose restart api                     # redémarrer l’application web
docker compose stop                            # arrêter Libris, tout conserver
docker compose start                           # le redémarrer
curl --fail http://127.0.0.1:8088/health       # {"status":"ok","version":"..."}

Désinstaller

Arrêtez Libris et supprimez ses conteneurs en conservant vos données :

docker compose down

Pour tout supprimer définitivement (base de données, livres, traductions), uniquement après une sauvegarde que vous avez vérifiée :

cd /opt/libris
docker compose --profile codex down --volumes --remove-orphans
docker image rm "$(sed -n 's/^LIBRIS_IMAGE=//p' .env | head -n 1)"

Vérifiez avec docker volume ls qu’il ne reste aucun volume libris_* (ni epub-translator_*), puis supprimez le dossier Libris, qui contient .env.

Construire depuis les sources

Les contributeurs peuvent construire l’image au lieu de la télécharger :

LIBRIS_IMAGE=libris:local docker compose build --pull api
LIBRIS_IMAGE=libris:local docker compose up -d --no-build --wait

Voir development (en anglais) pour les tests et l’environnement de développement.

Environnements pris en charge

Livres. Les livres EPUB 2 et 3 recomposables sont pris en charge, et une traduction vers une langue qui s’écrit de droite à gauche (arabe, hébreu, persan, ourdou) est exportée de droite à gauche. Les livres à mise en page fixe et ceux protégés par DRM ne sont pas pris en charge : les uns et les autres sont refusés à l’import. Un livre est à mise en page fixe quand son paquet déclare rendition:layout = pre-paginated (pour tout le livre, ou sur chaque page de texte de son spine), quand ses options Apple Books (META-INF/com.apple.ibooks.display-options.xml) mettent fixed-layout à true, ou quand il porte la méta Kindle fixed-layout : ses pages ont des dimensions fixes, et une traduction plus longue ou plus courte déborderait ou serait coupée. Quand seules certaines pages de texte sont fixes, le livre est importé avec un avertissement qui dit combien. Les entrées d’archive chiffrées sont refusées. Les volumes texte peuvent aussi être importés sous forme de chapitres TXT, Markdown, HTML ou DOCX, ou en JSON via l’API d’automatisation. EPUBCheck valide la structure d’un EPUB exporté, pas la qualité de sa traduction.

Archives de projet. Libris restaure les archives de projet (Exporter › Projet complet (.zip)) écrites par n’importe quelle version antérieure. Les archives écrites par cette version ne peuvent pas être lues par les versions antérieures à la 0.6.

Dépannage

Sur un hôte piloté par le script de déploiement de production (en anglais), les mêmes vérifications — et l’incantation Compose dont ces commandes ont besoin — tiennent en une seule commande : librisctl doctor (en anglais).

Lorsque vous écrivez à support@libris-translate.com pour obtenir de l’aide, depuis l’adresse qui a reçu votre licence, joignez la version de Libris, la sortie de docker version, celle de docker compose ps et quelques minutes de journaux. Retirez d’abord les mots de passe, les clés d’API, les cookies et le texte des livres.