Cómo autoalojar LibreTranslate en 2026: modelos, límites de la API y datos persistentes

Si ya has intentado autoalojar LibreTranslate, probablemente conozcas este estado frustrante: la interfaz aparece, pero los modelos no se han descargado o no está disponible un par de idiomas solicitado. Recrear el contenedor rara vez soluciona un desacuerdo entre las URL, el estado y las dependencias.

Este recorrido utiliza un único criterio de finalización concreto: enumerar los idiomas instalados, traducir una frase fija en ambas direcciones y probar la cuota de la API key y las respuestas de error. Cada decisión de configuración se evalúa según ese criterio, no según un indicador verde del contenedor.

Restaurar LibreTranslate en un host vacío

Enumera el estado antes de crear el primer registro real: los modelos descargados, la base de datos de API keys y la configuración personalizada. Monta /home/libretranslate/.local antes del bootstrap, escribe datos de ejemplo inocuos y sustituye el contenedor para demostrar que la ruta es realmente persistente. Confirma el montaje escribiendo datos inocuos, sustituyendo LibreTranslate y leyéndolos de nuevo.

Las snapshots son útiles para volver atrás rápidamente, pero necesitas una copia de seguridad independiente cuando el host o el volumen desaparecen. Restaura en un entorno vacío con la imagen fijada y verifica que los modelos y el estado de las API keys se recuperan, y que el corpus de regresión se completa con resultados aceptables. Usa volúmenes persistentes y snapshots para mantener diferenciados estos dos mecanismos de recuperación.

Puertos, procesos y servicios privados

No dejes que la imagen de LibreTranslate elija accidentalmente la arquitectura de producción. La imagen proporciona un proceso en el puerto 5000; el almacenamiento, el routing y los requisitos externos siguen necesitando ciclos de vida definidos deliberadamente. El requisito del runtime local es disponer de almacenamiento para descargar modelos y de CPU o GPU adecuadas para los pares de idiomas. Mantén explícito su ciclo de vida para que mover LibreTranslate entre hosts no cambie su comportamiento de forma silenciosa.

El despliegue estará listo para pruebas más profundas cuando pueda enumerar los idiomas instalados, traducir una frase fija en ambas direcciones y probar la cuota de la API key y las respuestas de error. Sigue la transacción en los logs y observa los modelos de idiomas cargados, el tiempo de inferencia de CPU, las solicitudes en paralelo y el espacio de disco consumido por las descargas de modelos. Estas observaciones muestran si la topología actual aísla el componente correcto.

Verificar el despliegue de LibreTranslate de extremo a extremo

Un gate de producción para LibreTranslate debe poder ejecutarlo alguien que no haya creado el despliegue. Dale a esa persona la versión fijada, una cuenta de prueba no sensible y esta tarea: enumerar los idiomas instalados, traducir una frase fija en ambas direcciones y probar la cuota de la API key y las respuestas de error. Si las instrucciones requieren acceso al shell no documentado, el servicio todavía no está preparado desde el punto de vista operativo.

Repite el gate después de sustituir únicamente el contenedor. A continuación, restaura los modelos descargados, la base de datos de API keys y la configuración personalizada en una infraestructura vacía, y demuestra que los modelos y el estado de las API keys se recuperan, y que el corpus de regresión se completa con resultados aceptables. Mide los modelos de idiomas cargados, el tiempo de inferencia de CPU, las solicitudes en paralelo y el espacio de disco consumido por las descargas de modelos durante ambas ejecuciones correctas; las diferencias inesperadas suelen revelar la ausencia de una caché, un índice, un worker o un montaje de datos.

Añade una prueba de fallo: envía una entrada inocua cercana al límite de recursos o de formato asociado a este límite: los modelos no se han descargado o no está disponible un par de idiomas solicitado. LibreTranslate debe emitir un error útil, conservar el estado existente y recuperarse cuando vuelva a cumplirse la condición válida. Guarda las marcas de tiempo y las líneas relevantes de los logs, ocultando los secretos. Estas evidencias se convierten en la referencia para el siguiente cambio de imagen o configuración.

Configuración del contenedor que conviene revisar

Usa un comando que exponga todas las decisiones importantes. Esta configuración base vincula LibreTranslate al loopback del host, añade los montajes de datos conocidos y proporciona el primer ajuste necesario. Confirma el requisito local antes de exponerlo: almacenamiento para descargar modelos y CPU o GPU adecuadas para los pares de idiomas.

docker run -d \
  --name libretranslate \
  --restart unless-stopped \
  -p 127.0.0.1:5000:5000 \
  -v libretranslate-data:/home/libretranslate/.local \
  -e LT_API_KEYS=true \
  libretranslate/libretranslate:latest

Sustituye las tags flotantes por una versión probada o un digest. Después del arranque, inspecciona docker logs --tail 200 libretranslate y confirma que el proceso escucha en el puerto 5000. A continuación, ejecuta la acción de aceptación de LibreTranslate; una respuesta de la página raíz no puede demostrar que todo el escenario funcione: enumerar los idiomas instalados, traducir una frase fija en ambas direcciones y probar la cuota de la API key y las respuestas de error.

Credenciales, roles y superficies expuestas

El riesgo de seguridad específico de la aplicación consiste en ejecutar una API pública ilimitada que otros pueden agotar. La respuesta operativa es habilitar API keys o autenticación upstream, aplicar rate limiting a los clientes públicos e instalar únicamente los pares de idiomas necesarios. Completa el bootstrap mediante una ruta restringida y elimina inmediatamente después el acceso temporal de configuración.

LT_API_KEYS controla el comportamiento, no la confidencialidad; valida su tipo y valor, y almacena las credenciales reales de LibreTranslate por separado. Concede al proceso de LibreTranslate únicamente sus montajes documentados y las rutas hacia sus dependencias; evita el acceso al root del host y al socket de Docker. Registra los fallos de autenticación y los errores de configuración, pero oculta los tokens, las cadenas de conexión y el contenido de los usuarios.

Mantener separadas las URL internas y externas

La emisión de TLS solo es la mitad de la ruta de LibreTranslate. Sirve la API mediante HTTPS y documenta la base path correcta. Envía el tráfico internamente al puerto 5000 y reenvía el esquema externo para que las URL generadas y las cookies seguras sigan siendo coherentes.

Usa el escenario completo de LibreTranslate desde una red limpia, no solo la página raíz. Un error 502 o de certificado se puede aislar con la configuración automática del dominio y TLS. Si el tráfico llega al proceso y los modelos no se han descargado o no está disponible un par de idiomas solicitado, diagnostica esa condición donde se produce en lugar de acumular redirecciones.

Pruebas de fallo para LibreTranslate

Las pruebas de capacidad deben ejercitar los modelos de idiomas cargados, el tiempo de inferencia de CPU, las solicitudes en paralelo y el espacio de disco consumido por las descargas de modelos, no una solicitud repetida a /. Ejecuta el escenario «enumerar los idiomas instalados, traducir una frase fija en ambas direcciones y probar la cuota de la API key y las respuestas de error» con una concurrencia realista y registra la latencia, la tasa de errores y el crecimiento del almacenamiento.

La planificación de actualizaciones debe tener en cuenta este riesgo: los paquetes de modelos y las versiones del servidor pueden cambiar el resultado de las traducciones, por lo que debes mantener un corpus de regresión pequeño. Prueba la nueva versión con entradas representativas, repite la transacción de aceptación y compara el resultado. Si los modelos no se han descargado o no está disponible un par de idiomas solicitado, captura la transacción fallida e inspecciona el primer límite implicado en lugar de asumir que el ingress es el responsable.

Desplegar LibreTranslate en Dockup sin perder sus límites

Una plantilla de Dockup debe codificar la imagen, el puerto 5000, los montajes, los tiempos de health check, el dominio, TLS y la entrega de secretos. Dockup debe conservar la configuración del runtime de LibreTranslate mientras el operador confirma este requisito local: almacenamiento para descargar modelos y CPU o GPU adecuadas para los pares de idiomas. El mismo despliegue puede dirigirse a servidores de Dockup o a capacidad asociada por el cliente.

Cuando la ruta esté activa, aplica la configuración pública e intenta enumerar los idiomas instalados, traducir una frase fija en ambas direcciones y probar la cuota de la API key y las respuestas de error. Haz copias de seguridad de los modelos descargados, la base de datos de API keys y la configuración personalizada, y mantén el ejercicio de restauración en el plan operativo; son responsabilidades de LibreTranslate que siguen siendo visibles después del aprovisionamiento de la infraestructura.

Preguntas frecuentes

¿Qué necesita LibreTranslate para un despliegue de producción?

Enruta el contenedor de LibreTranslate en el puerto 5000 a través de un único origen HTTPS. El requisito del runtime local es disponer de almacenamiento para descargar modelos y de CPU o GPU adecuadas para los pares de idiomas. No consideres que LibreTranslate está listo hasta que puedas enumerar los idiomas instalados, traducir una frase fija en ambas direcciones y probar la cuota de la API key y las respuestas de error.

¿Qué datos de LibreTranslate deben incluirse en una copia de seguridad?

Conserva /home/libretranslate/.local e incluye los modelos descargados, la base de datos de API keys y la configuración personalizada en el mismo manifiesto de recuperación. Una restauración limpia de LibreTranslate solo es válida cuando los modelos y el estado de las API keys se recuperan, y el corpus de regresión se completa con resultados aceptables.

¿Necesita LibreTranslate HTTPS detrás de un reverse proxy?

Usa HTTPS para el origen público de LibreTranslate y mantén el puerto 5000 en la ruta interna. Aplica correctamente la configuración de LibreTranslate: sirve la API mediante HTTPS y documenta la base path correcta. En LibreTranslate, HTTPS protege las credenciales o el contenido de los usuarios durante el tránsito y mantiene coherente el comportamiento del cliente sensible al origen.

¿Cómo debe probarse una actualización de LibreTranslate?

Restaura el estado actual de LibreTranslate en un despliegue aislado, aplica la versión candidata y repite su transacción de aceptación. Presta especial atención porque los paquetes de modelos y las versiones del servidor pueden cambiar el resultado de las traducciones, por lo que debes mantener un corpus de regresión pequeño. Conserva la imagen anterior de LibreTranslate hasta comprender los límites de migración de datos y rollback.