Libris Translate
Français

Installation guide

Install Libris Translate on a blank server

From a freshly installed Linux server to Libris Translate running, signed in and activated. Allow about twenty minutes, most of it downloads. The official installer, install.sh, does the work; this page explains each step, what to answer and what it creates.

No server yet? Rent and prepare a VPS

In short

On a Linux server with Docker, with the registry credentials from your licence email at hand:

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

On video

Install Libris Translate, from a blank server to a first book · 1 min 57 The whole procedure filmed on a blank server with Libris Translate 0.23.0, without sound. The administrator password and the ChatGPT sign-in code are blurred; the licence key and the registry username are examples.
What the video shows, step by step
  • Before you start: a Linux x86-64 server with Docker Engine 26 or newer and Compose v2, 2 GB of free memory, a language model and the licence email.
  • Step 1: check Docker with sudo docker compose version.
  • Step 2: sign in to the registry with sudo docker login registry.libris-translate.com, using the username and token from the licence email.
  • Step 3: run the official install command; the installer from the image takes over, creates /opt/libris and starts PostgreSQL, the migration, the API, the worker and the Codex bridge.
  • Step 4: check the installation with curl --fail http://127.0.0.1:8088/health, then read the administrator password with sudo grep '^BOOTSTRAP_' /opt/libris/.env.
  • Step 5: sign in as admin at http://localhost:8088.
  • Step 6: activate the licence in Settings › Licence.
  • Step 7: add a model in Settings › LLM providers; here, a “Codex · ChatGPT account” provider, signed in with a device code, using the GPT-6 Luna model.
  • Step 8: add an EPUB with Add content, then “Import and run the whole pipeline”; the autopilot takes the book all the way to the final EPUB.

Step 1 Check the machine

Libris Translate runs as a set of Docker containers on one Linux server that you administer. Do you need help renting and preparing a server? You need:

  • a Linux x86-64 (AMD64) server. Ubuntu and Debian are supported with Docker’s official packages; ARM64, the Fedora/RHEL family, Windows and macOS are not tested, and the images are published for AMD64 only;
  • at least 2 GB of free memory, and disk space for your books, their translations, exports and backups. No GPU: the language model runs elsewhere;
  • a language model Libris Translate can reach: a hosted service with an API key (OpenAI, Anthropic or any OpenAI-compatible provider) or your own inference server;
  • your licence email: it contains the licence key and the read-only credentials of the image registry.

Step 2 Administrator and network access

  • An account that can use sudo, or root. The installer writes to /opt/libris and drives Docker, which both need root.
  • Outbound HTTPS (port 443) to libris-translate.com (the installer), registry.libris-translate.com (the Libris Translate images), Docker Hub (the PostgreSQL image), sub.libris-translate.com (licence checks, once an hour and when a job ends) and your model provider. Optionally, www.ecb.europa.eu for the daily exchange rates that convert a provider’s prices typed in another currency; without it, prices are typed in the installation’s own currency.
  • No inbound port. Libris Translate listens on 127.0.0.1:8088, on the server itself: from another computer you reach it through an SSH tunnel (step 7) until you decide to publish it behind HTTPS.

Step 3 Install Docker

The installer uses Docker but does not install it. Install Docker Engine 26 or newer with the Compose v2 plugin by following Docker’s official guide for your distribution. On Ubuntu and Debian, that means the docker-ce and docker-compose-plugin packages from Docker’s own repository: the distribution’s docker.io package may lack Compose v2. Then check:

bash 
sudo docker version
sudo docker compose version

Both commands must print a version, and docker compose version must say v2 or later: the old docker-compose command is not enough.

Step 4 Keep the registry credentials at hand

Your licence email contains three different secrets:

  • the licence key, which you will enter in Libris Translate itself (step 8);
  • the registry username;
  • the registry token, the password of the registry. It only allows downloading the Libris Translate images.

Never type the token on a command line or put it in an environment variable: it would stay in your shell history. The installer asks for it in the terminal, without displaying it. If you prefer, store it for root beforehand; Docker also asks for it without displaying it:

bash 
sudo docker login registry.libris-translate.com

At Username, enter the registry username; at Password, paste the registry token — not the licence key. Docker answers Login Succeeded.

Step 5 Run the installer

On the server, as the account that can use sudo, run the official command. It downloads install.sh from this site over HTTPS and runs it as root:

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

You can read the script before running it: libris-translate.com/install.sh. It installs the latest stable release, latest. To install exactly Libris Translate 0.28.0 instead:

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

Step 6 Answer the installer

The installer first tries the credentials Docker already holds. If you did not log in beforehand, Docker prints an authorisation error, which is expected, and the installer says The stored Docker registry login could not pull Libris; use the read-only credentials supplied with your licence. It then asks two questions in the terminal:

QuestionAnswer
Registry username: the registry username from your licence email, then Enter
Registry token: the registry token, then Enter. Nothing appears while you paste it: that is normal

Nothing else is asked. The installer then works on its own for a few minutes:

  1. it downloads registry.libris-translate.com/libris/libris:latest and records its immutable digest. Every image carries its own installer: the script downloaded from this site hands over to the one of the image it has just pulled and says Continuing with the installer of registry.libris-translate.com/libris/libris@sha256:…. The installer, the Compose file and the configuration template on your server therefore always come from the very image they start;
  2. it downloads the matching Codex bridge and checks that both images come from the same build;
  3. it says Installing Libris 0.28.0 in /opt/libris. and creates /opt/libris, readable by root only, with docker-compose.yml and .env, both taken from the image. .env receives random secrets and the image’s default settings, among them BOOTSTRAP_USERNAME=admin, BIND_ADDRESS=127.0.0.1, PORT=8088 and COMPOSE_PROFILES=codex;
  4. it starts PostgreSQL, the database migration, the web application, the worker and the Codex bridge, and waits until they are healthy;
  5. it ends with Libris 0.28.0 is ready at http://localhost:8088, followed by the command that displays the administrator password (step 8) and the SSH tunnel to use on a remote server (step 7).

Your books, accounts and database live in Docker volumes, not in /opt/libris. /opt/libris/.env holds the initial administrator password and the secrets that protect your data: keep it private and include it in your backups.

Step 7 Check that Libris Translate is running

On the server, the health check answers {"status":"ok","version":"…"}:

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

The state of each service: all are running or healthy, except migrate, which stops once the database is up to date (exited (0) is normal).

bash 
sudo docker compose --project-directory /opt/libris ps

Open http://localhost:8088 in a browser on the server. On a remote server, open a tunnel from your own computer, leave it open, then open the same address on your computer:

bash 
ssh -L 8088:127.0.0.1:8088 you@your-server

To reach Libris Translate from your network or over HTTPS, follow Open Libris to your network in the Docker guide.

Step 8 Sign in and activate the licence

The installer has already created the administrator account, admin. Display its generated password on the server:

bash 
sudo grep '^BOOTSTRAP_' /opt/libris/.env
  1. Sign in as admin with this password, then change it from your account page. Treat the output of the command above as a password: never paste it into a ticket, a chat or a screenshot.
  2. Open Settings › Licence, paste the licence key from your email into Licence key and click Activate. The installation binds to this machine and renews its authorisation on its own from then on.
  3. Open Settings › LLM providers, click New provider, enter your model’s address, key and name, click Save, then Test / detect models.
  4. Import a first book: Your first translation walks through it.

Step 9 Update Libris Translate

Updating is the same command. First read the changelog, pause running books and make a backup. Then:

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

The installer recognises the installation in /opt/libris and says Updating the existing Libris configuration in /opt/libris to 0.28.0. It keeps .env and its secrets, every account, every book and every Docker volume: only the image references change, and database migrations run on their own. An installation made before 0.16 also receives COMPOSE_PROFILES=codex, so that a plain docker compose pull updates the Codex bridge too. A customised docker-compose.yml is never overwritten: the new template is written beside it as docker-compose.yml.libris-new and the update stops until you merge it.

Check the health again (step 7) and resume the paused books. Returning to an older image does not undo a database migration: to go back, restore the backup made before the update.

If the installer stops

Its messages start with Libris installation:. The most common ones:

MessageWhat to do
docker is required. Docker is not installed, or not in root’s path: go back to step 3.
Docker Compose v2 is required. Install the docker-compose-plugin package from Docker’s repository (step 3).
the registry rejected those credentials. Paste the registry token, not the licence key, with the username from the same email. If the email is old, ask for new credentials.
the registry pull failed and no terminal is available. Run the command from an interactive terminal (an SSH session), or store the credentials first with sudo docker login (step 4).
installing under /opt requires root; run this command through sudo. Keep sudo bash at the end of the command.
LIBRIS_HOME is not empty; choose an empty directory so no data is overwritten. /opt/libris exists and holds something else: move it aside. The installer never overwrites it.
contains an incomplete installation; do not overwrite it. Only one of .env and docker-compose.yml is in /opt/libris: restore the missing one from your backup.
docker-compose.yml has local changes. Merge docker-compose.yml.libris-new into your file, then run the command again (step 9).
could not download the images of the stack. The configuration is kept; run the same command again to resume. A network or registry interruption: check outbound HTTPS access (step 2), then run the same command again. Nothing is lost.
the stack did not start. The configuration is kept; inspect 'docker compose logs' in /opt/libris, then run the same command again to resume. Read the logs with the command below, fix the cause (often memory or disk space), then run the same command again.

Recent logs of the application:

bash 
sudo docker compose --project-directory /opt/libris logs --since=10m api worker

Anything else: see the troubleshooting table of the Docker guide, or write to support@libris-translate.com with the Libris Translate version and the installer’s last lines — never the contents of .env.

Go further