kevinveenbirkenbachandClaude Opus 5
4986e80dd4
The Production block never set one. inventory provision writes only
ansible_connection for a local host, so DOMAIN_PRIMARY stayed at the
group_vars default of infinito.localhost and the deployment served a zone its
own resolver knows nothing about. CoreDNS templates answers for
INFINITO_DOMAIN_RE and nothing else, so every lookup of the deployment's own
name came back NXDOMAIN.
Mastodon is where that surfaced. tootctl accounts create validates the address
through EmailMxValidator, which resolves MX and then, for the domain itself,
A and AAAA. All six queries returned NXDOMAIN in run 33574056480, the
validator recorded email :unreachable, and the admin account was never created.
Only the guide rows were affected: the matrix rows write
DOMAIN_PRIMARY: "{{ lookup('env', 'INFINITO_DOMAIN') }}" into their host_vars
and resolve fine.
The template now carries DOMAIN=<your-domain> in both the host and the
container form and threads it into --vars, with the container form passing it
through the docker run boundary as well. The two guide runners substitute it
the way they already substitute the SSH key, so the replay deploys under
INFINITO_DOMAIN like every other CI deploy. compose_deploy.sh moves its env
load ahead of the substitutions to have the value; host_deploy.sh had no env
load at all.
A production reader is asked for a domain now instead of silently inheriting
infinito.localhost, which no real deployment wants either. The shipped default
keeps its value: sys-svc-nss documents that *.localhost resolves through the
myhostname NSS module without any zone, and host-side tasks lean on it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
6.8 KiB
LibreTranslate
This role deploys LibreTranslate as a containerized web service using Docker Compose. It is designed to integrate seamlessly into the Infinito.Nexus stack, including optional Redis and database backends, CSP handling, and analytics integration.
Description
LibreTranslate is an open-source machine translation API that can be self-hosted. This role provides a standardized, reproducible deployment with optional extensions such as Redis caching, database persistence, and Matomo tracking.
The role follows Infinito.Nexus conventions:
- container abstraction (
container,compose) - per-role meta configuration under
meta/services.ymlandmeta/server.yml - CSP-aware reverse proxy integration
- optional shared services (database, analytics)
Overview
- Deployment via Docker Compose
- Stateless by default, with optional stateful backends
- Designed for reverse-proxy setups
- Suitable for internal services, public APIs, or desktop integration
- Compatible with the Infinito.Nexus role and metadata system
Cosmos
The diagram places LibreTranslate in the Infinito.Nexus cosmos: the components it deploys (capabilities), the central services it consumes (dependencies), and its outward reach (federation and bridged external networks).
flowchart LR
subgraph deps [Dependencies]
dep_svc_db_redis["svc-db-redis 🐳🐝"]
dep_svc_net_tor["svc-net-tor 🐳🐝"]
dep_web_app_hermes["web-app-hermes 🐳🐝"]
dep_web_app_keycloak["web-app-keycloak 🐳🐝"]
dep_web_app_matomo["web-app-matomo 🐳🐝"]
dep_web_app_openclaw["web-app-openclaw 🐳🐝"]
dep_web_app_openwebui["web-app-openwebui 🐳🐝"]
dep_web_app_prometheus["web-app-prometheus 🐳🐝"]
dep_web_svc_css["web-svc-css 💻"]
end
subgraph role [web-svc-libretranslate 🐳🐝]
svc_libretranslate["libretranslate"]
svc_sso["sso"]
svc_logout["logout ❌"]
svc_matomo["matomo"]
svc_redis["redis"]
svc_css["css"]
svc_recaptcha["recaptcha"]
svc_javascript["javascript"]
svc_prometheus["prometheus"]
svc_libretranslatemcp["libretranslatemcp"]
svc_tor["tor"]
svc_openwebui["openwebui"]
svc_hermes["hermes"]
svc_openclaw["openclaw"]
svc_flowise["flowise ❌"]
end
dep_svc_db_redis -. "0..1" .-> svc_redis
dep_svc_net_tor -. "0..1" .-> svc_tor
dep_web_app_hermes -. "0..1" .-> svc_hermes
dep_web_app_keycloak -. "0..1" .-> svc_sso
dep_web_app_matomo -. "0..1" .-> svc_matomo
dep_web_app_openclaw -. "0..1" .-> svc_openclaw
dep_web_app_openwebui -. "0..1" .-> svc_openwebui
dep_web_app_prometheus -. "0..1" .-> svc_prometheus
dep_web_svc_css -. "0..1" .-> svc_css
Solid 1:1 edges are fixed relationships; dashed 0..1 edges are conditional (enabled only in matching deployments); red 0..0 edges are turned off in this role. Node markers show the role's deploy modes (💻 host, 🐳 compose, 🐝 swarm); ❌ marks a service that is explicitly turned off, and ⚙️ an Ansible role dependency declared in meta/main.yml.
Features
- LibreTranslate service deployment
- Configurable container image and version
- Optional Redis backend
- Optional database backend
- Optional Matomo analytics integration
- CSP configuration support
- Custom JavaScript injection
- Desktop integration toggle
- Health checks via HTTP
- Network and dependency handling via shared system roles
Quick Setup
Development
Clone, set up the workstation, and deploy LibreTranslate onto the local stack:
git clone https://github.com/infinito-nexus/core.git
cd core
make onboard
make compose-deploy mode=reinstall apps=web-svc-libretranslate full_cycle=false
Production
Run the published image to provision the inventory and deploy LibreTranslate to a managed server (the mounted volume persists the inventory):
APP=web-svc-libretranslate
HOST=<your-server>
DOMAIN=<your-domain>
TLS_MODE=self_signed
SSH_PUBLIC_KEY="<your-ssh-public-key>"
docker run --rm -it \
-v "$PWD/inventories:/etc/infinito.nexus/inventories" \
-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 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\", \"users\": {\"administrator\": {\"authorized_keys\": [\"$SSH_PUBLIC_KEY\"]}}}" &&
infinito administration deploy dedicated "$INVENTORY/devices.yml" \
--password-file "$INVENTORY/.password" \
--diff -vv'
Single sign-on
OIDC is wired in via a sidecar web-app-keycloak's SSO-proxy sidecar that fronts the human-facing web UI only.
The programmatic API endpoints (/translate, /detect, …) MUST stay reachable with API-key auth even when the UI is gated, so the OIDC gate is restricted to the UI subpath; otherwise machine clients break.
LDAP is not feasible: LibreTranslate authenticates programmatic clients with API keys, and LDAP cannot map onto that model. RBAC is also not feasible because authorisation in LibreTranslate is API-key-tier only and decoupled from any IDP. The OIDC gate protects the UI but does not grant differential authorisation inside the app. These LDAP and RBAC exceptions are documented per lifecycle.md.
Configuration
All configuration is handled via meta/services.yml (services map at file root) and meta/server.yml (server block at file root).
Key sections include:
services.libretranslate: image and versionservices.redis: enable Redis backendservices.matomo: enable analyticsdomains: canonical and alias domainscsp:
Persona contract opt-outs
The sidecar oauth2-proxy admits only the LibreTranslate administrator RBAC group and whitelists just the machine API paths (/translate, /detect, …); see meta/services.yml. Inside the app, authorisation is API-key-tier only and decoupled from the IdP, as documented under Single sign-on above.
A non-admin visitor therefore has no UI session to drive, so templates/playwright.env.j2 declares PERSONA_BIBER_BLOCKED=true. The administrator and guest personas run unconditionally.
Credits
Implemented by Kevin Veen-Birkenbach. Part of the Infinito.Nexus Project and maintained by Kevin Veen-Birkenbach. Licensed under the Infinito.Nexus Community License (Non-Commercial).