LibreTranslate Engine¶

This role deploys LibreTranslate as a plain translation engine, without a public vhost, reverse proxy, MCP adapter or analytics. Callers reach it over the container network and talk to its HTTP API directly.

Use web-svc-libretranslate instead when the deployment needs a public domain, single sign-on, CSP handling or the MCP adapter.

Description¶

LibreTranslate is an open-source machine translation API that can be self-hosted. This role provides it as a backend other roles and build pipelines call directly, such as the gettext catalog translation the i18n make targets drive. Everything that exists only to serve a browser is left out, so the image carries the engine and its models and nothing else.

Overview¶

Deployment via Docker Compose or Swarm
No domain, no reverse proxy, no browser surface
Host-bound port for local callers, container alias for in-stack callers
Models arrive lazily, at build time or by a post-deploy task, selected per deployment

Architecture¶

ARCHITECTURE.md draws LibreTranslate Engine from its own metadata: the containers it runs under compose, what changes under swarm, how each volume is backed, and every role it depends on or is depended upon by.

Section	Drawn from
Compose	`meta/services.yml`
Swarm	`meta/services.yml` replicas and placement
Volumes	`meta/volumes.yml` against the NFS decision chain
Dependencies	`meta/services.yml` and `meta/main.yml` of every role

Features¶

Configurable container image and version
Language selection via services.libretranslate-engine.load_only
Direction selection via services.libretranslate-engine.directions, which keeps either every language pair or only those translating out of English
Optional GPU execution, asserted after the deploy
Package-cache CA installed into the build context
Health check over the bundled interpreter

Quick Setup¶

Development¶

Clone, set up the workstation, and deploy LibreTranslate Engine onto the local stack:

git clone https://github.com/infinito-nexus/core.git
cd core
make onboard
make compose-deploy mode=reinstall apps=svc-ai-libretranslate-engine full_cycle=false

Production¶

Run the published image to provision the inventory and deploy LibreTranslate Engine to a managed server over SSH. The image logs in as root, so the server must accept root over a public key, and the two key variables are the two halves of one key pair: the private half authenticates the deploy, and the public half is what the deploy keeps authorized for root and installs for the administrator account. Naming a public half that does not belong to the private one locks the running deploy out at its next reconnect.

APP=svc-ai-libretranslate-engine
HOST="<your-server>"
DOMAIN="<your-domain>"
TLS_MODE=self_signed
SSH_PUBLIC_KEY="<your-ssh-public-key>"
SSH_PRIVATE_KEY="<your-ssh-private-key-file>"
WORKDIR="$HOME/.infinito.nexus"

mkdir -p "$WORKDIR/inventories"
docker run --rm \
  -v "$WORKDIR/inventories:/etc/infinito.nexus/inventories" \
  -v "$SSH_PRIVATE_KEY:/run/secrets/deploy_key:ro" \
  -e APP="$APP" -e HOST="$HOST" -e DOMAIN="$DOMAIN" -e TLS_MODE="$TLS_MODE" -e SSH_PUBLIC_KEY="$SSH_PUBLIC_KEY" \
  ghcr.io/infinito-nexus/core/debian:latest bash -c '
    INVENTORY=/etc/infinito.nexus/inventories/production
    infinito administration inventory provision "$INVENTORY" \
      --inventory-file "$INVENTORY/devices.yml" \
      --host "$HOST" \
      --include "$APP" \
      --vars "{\"TLS_MODE\": \"$TLS_MODE\", \"DOMAIN_PRIMARY\": \"$DOMAIN\", \"SYS_SVC_SSHD_PERMIT_ROOT_LOGIN\": \"prohibit-password\", \"users\": {\"root\": {\"authorized_keys\": [\"$SSH_PUBLIC_KEY\"]}, \"administrator\": {\"authorized_keys\": [\"$SSH_PUBLIC_KEY\"]}}}" &&
    infinito administration deploy dedicated "$INVENTORY/devices.yml" \
      --password-file "$INVENTORY/.password" \
      -u root --private-key /run/secrets/deploy_key \
      --diff -vv'

The inventory under $WORKDIR is written by the container as root, including the vault password at inventories/production/.password. Run sudo chown -R "$USER" "$WORKDIR" afterwards to read it.

Credits¶

Kevin Veen-Birkenbach

Part of the Infinito.Nexus Project and maintained by Kevin Veen-Birkenbach. Licensed under the Infinito.Nexus Community License (Non-Commercial).

That licence covers this role. The software it deploys is a separate grant: AGPL-3.0-only, under which commercial use is allowed. You owe its authors this much: publish the source of changes once you offer it over a network, which a hosted deployment does. Permission for one of the two is not permission for the other.

Configuration¶

meta/services.yml carries the knobs:

Key	Meaning
`image` / `version`	upstream image, suffixed `-cuda` when `gpu` is set
`load_only`	ISO 639-1 codes to load; empty means every package the engine offers
`loading_model`	when the models arrive: `lazy`, `build` or `task`
`directions`	`both` or `from_source`
`gpu`	run on CUDA and assert the device arrived
`ports.local.http`	host-bound port

loading_model¶

value	when models arrive	cost
`lazy` (default)	the served container fetches one the first time a request needs it	no build and no deploy wait; the first request for a pair pays for it
`build`	baked into the image	the build downloads every selected model, 13 GB for the full set; later requests never wait
`task`	a post-deploy task installs them into the running container	the deploy waits instead of the build, and an image rebuild does not refetch

Under lazy and task the models live on a node-local bind mount, so a rebuild or a recreate finds what an earlier run already fetched. build is mounted without it, because a bind is never seeded from the image and would hide what the build baked.

GPU¶

With gpu: true the role builds the -cuda image and, when sys-svc-container counts the host as a GPU host (see its README), asserts after the deploy that CTranslate2 counts at least one CUDA device. Any other host builds the CPU image and skips the assertion.