Antes de começar
O Liteleaf é destinado a usuários autenticados e confiáveis. São necessários Docker Engine com Compose v2, nome DNS, proxy HTTPS, armazenamento persistente e um destino de backup antes de convidar usuários. O compilador LaTeX tem limites e privilégios reduzidos, mas não é um sandbox forte para documentos hostis.
Escolha o perfil de implantação
Standalone
Use docker-compose.standalone.yml para testes ou um grupo muito pequeno e
confiável. Ele executa uma réplica, SQLite e TeX Live no mesmo contêiner. Não
oferece alta disponibilidade, colaboração entre réplicas nem o isolamento de
compilação da produção. Inicie com docker compose -f docker-compose.standalone.yml up -d.
Use volumes nomeados gerenciados pelo Docker para dados persistentes; o volume de
dados da aplicação deve ser gravável como UID/GID 65532.
Produção
Use docker-compose.prod.yml para departamentos e instituições. Ele separa
aplicação, compilador, PostgreSQL e Redis. Use volumes nomeados gerenciados pelo
Docker para PostgreSQL, Redis, dados da aplicação e backups, em vez de caminhos
do host. Defina URL pública HTTPS, senhas do banco e Redis e um token do
compilador com pelo menos 32 caracteres aleatórios. Suba a stack, confira
/health/ready localmente e então aponte o proxy HTTPS para a porta HTTP
configurada. A primeira conta criada no navegador é a administradora.
Variáveis de ambiente de produção
Crie um arquivo .env ao lado de docker-compose.prod.yml; não o versione.
Gere os segredos obrigatórios com:
openssl rand -base64 36
openssl rand -hex 32
openssl rand -base64 32 # chave TOTP: exatamente 32 bytes decodificados
Use valores diferentes para POSTGRES_PASSWORD, REDIS_PASSWORD e
LITELEAF_COMPILER_TOKEN. Defina LITELEAF_TOTP_ENCRYPTION_KEY apenas com a
saída base64 do último comando e guarde-a com segurança: alterá-la torna os
segredos TOTP existentes ilegíveis.
| Grupo | Variáveis | Finalidade e ponto de partida seguro |
|---|---|---|
| Obrigatórias | LITELEAF_PUBLIC_URL, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, REDIS_PASSWORD, LITELEAF_COMPILER_TOKEN |
Origem HTTPS pública, identidade do banco, segredos aleatórios distintos e token compartilhado somente entre app e compilador. |
| Imagens e porta | LITELEAF_VERSION, LITELEAF_APP_IMAGE, LITELEAF_COMPILER_IMAGE, LITELEAF_PULL_POLICY, LITELEAF_HTTP_PORT |
Escolhem release/imagens e porta do host. Mantenha a tag publicada fixada para atualizações controladas. |
| Conexões | LITELEAF_DATABASE_MAX_CONNS, LITELEAF_REDIS_POOL_SIZE, LITELEAF_REDIS_PREFIX, LITELEAF_RELAY_INTERVAL, LITELEAF_RECONCILE_AFTER |
Ajuste apenas depois de observar capacidade; os defaults atendem uma réplica da app. O prefixo isola instalações Redis compartilhadas. |
| Sessão e login | LITELEAF_SESSION_TTL, LITELEAF_LOGIN_RATE_WINDOW, LITELEAF_LOGIN_MAX_ATTEMPTS, LITELEAF_FALLBACK_LOCALE |
Controlam duração da sessão, rate limit e idioma padrão. |
| Compilador | LITELEAF_COMPILE_TIMEOUT, LITELEAF_COMPILER_CONCURRENCY |
O padrão é 180 segundos e um job concorrente; aumente somente após dimensionar CPU, memória e controles de abuso. |
| Armazenamento e limites | LITELEAF_BLOB_ROOT, LITELEAF_BACKUP_ROOT, LITELEAF_BACKUP_MAX_UPLOAD, LITELEAF_PROJECT_ARCHIVE_COMPRESSED_MAX, LITELEAF_PROJECT_ARCHIVE_EXPANDED_MAX |
Caminhos internos e limites de upload/arquivo. Mantenha as raízes em volumes nomeados e ajuste os limites ao armazenamento disponível. |
| Retenção e projetos | LITELEAF_MAX_PROJECTS_PER_USER, LITELEAF_MAX_ACTIVE_COMPILATIONS_PER_USER, LITELEAF_COMPILATION_RETENTION, LITELEAF_TRASH_RETENTION, LITELEAF_JOB_RETENTION, LITELEAF_RETENTION_INTERVAL, LITELEAF_EDITOR_AUTOSAVE_INTERVAL, LITELEAF_AUTO_COMPILE_ON_SAVE |
Cotas, janelas de limpeza, autosave e comportamento de compilação. 0 pode significar ilimitado quando documentado pela aplicação. |
| Integrações opcionais | LITELEAF_OLLAMA_URL, LITELEAF_OLLAMA_MODEL, LITELEAF_OLLAMA_GENERATION_TIMEOUT, LITELEAF_OLLAMA_KEEP_ALIVE, LITELEAF_MAX_ASSISTANT_REQUESTS, LITELEAF_ASSISTANT_RATE_WINDOW, LITELEAF_GIT_ENABLED |
Habilite apenas serviços aprovados e alcançáveis; URL Ollama vazia desativa IA e Git false oculta o Backup Git. |
| Identidade e e-mail | LITELEAF_OIDC_ISSUER_URL, LITELEAF_OIDC_CLIENT_ID, LITELEAF_OIDC_CLIENT_SECRET, LITELEAF_OIDC_DISPLAY_NAME, LITELEAF_SMTP_ADDR, LITELEAF_SMTP_FROM, LITELEAF_SMTP_USERNAME, LITELEAF_SMTP_PASSWORD |
SSO e envio de recuperação de senha opcionais. Não exponha segredos de cliente e SMTP em logs. |
| Proxy e observabilidade | LITELEAF_TRUSTED_PROXIES, LITELEAF_METRICS_TOKEN, LITELEAF_BACKGROUND_WORKERS, LITELEAF_TOTP_ENCRYPTION_KEY |
Confie somente em proxies administrados, proteja métricas por token e mantenha workers ativos na app principal. |
Valide e opere a stack com:
docker compose -f docker-compose.prod.yml config
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs -f app compiler
curl --fail http://127.0.0.1:8080/health/ready
docker volume ls
Quando o Compose usar volumes nomeados, o Docker os cria na primeira subida.
Inspecione-os com docker volume inspect <nome>; faça backup pelos fluxos
verificados da aplicação, em vez de editar arquivos de volume diretamente.
Configure a instância
A console administrativa em /admin é exclusiva de administradores globais.
Nela é possível revisar saúde, filas, armazenamento e versão; administrar
usuários, papéis, bloqueios, sessões, cotas, projetos, templates, auditoria e
backups. A lista de usuários é paginada e pesquisável. Uma cota herdada do valor
global usa NULL; 0 significa ilimitado. Cotas individuais substituem as
globais, enquanto valores Docker são fallback quando não há configuração salva.
Configure primeiro o login local. OIDC é opcional: cadastre o callback
https://seu-host/auth/oidc/callback e configure issuer, client ID, segredo e
nome de exibição. TOTP, códigos de recuperação, revogação de sessão e bloqueio
de conta complementam a proteção. Mantenha segredos no arquivo de ambiente ou
no gerenciador de segredos: a console nunca os devolve.
Integrações e correção
O Ollama é externo e opcional. Defina um endpoint HTTP(S) alcançável pelo contêiner da aplicação e escolha um modelo instalado e um prompt nas configurações administrativas de IA. O administrador pode testar a integração; modelo e prompt salvos têm prioridade sobre o ambiente. Informe aos usuários o destino do texto selecionado conforme a política institucional.
A correção ortográfica interativa usa dicionários Aspell de inglês e português do Brasil. Ela sugere substituições, adiciona palavras ao dicionário do projeto e sublinha problemas no editor. Garanta a presença dos dois dicionários na imagem implantada. O timeout padrão de compilação é 180 segundos; aumente-o apenas considerando capacidade e risco de abuso.
Backup, recuperação e atualização
Crie e verifique um backup antes de cada atualização. Confirme readiness, entre com uma conta não administrativa, compile um projeto canário e consulte a auditoria. Não faça downgrade do schema depois de executar migrações. Execute periodicamente um restore drill com PostgreSQL e blobs descartáveis.
Os projetos guardam revisões manuais atribuídas e checkpoints automáticos de
inatividade consolidados, permitindo restaurar um estado conhecido. Cada projeto
também pode expor uma origem Git autenticada e somente-leitura para um pull
mirror do Forgejo ou Gitea; o serviço remoto agenda o espelho e o Liteleaf não
guarda suas credenciais. Use LITELEAF_GIT_ENABLED=false para desativar esse
recurso e suas rotas.