Before you begin
Liteleaf is for authenticated, trusted users. Docker Engine with Compose v2 is required. Plan a DNS name, HTTPS reverse proxy, persistent storage, and a backup destination before inviting users. The LaTeX compiler has limits and reduced privileges, but it is not a strong sandbox for hostile documents.
Choose a deployment profile
Standalone
Use docker-compose.standalone.yml for testing or a very small, trusted group.
It runs one replica, SQLite, and TeX Live in one container. It does not provide
high availability, collaboration between replicas, or the compiler isolation of
production. Start it with docker compose -f docker-compose.standalone.yml up -d.
Use Docker-managed named volumes for persistent data; the application data volume
must be writable as UID/GID 65532.
Production
Use docker-compose.prod.yml for departments and institutions. It separates
the app, compiler, PostgreSQL, and Redis. Use Docker-managed named volumes for
PostgreSQL, Redis, application data, and backups rather than host paths. Set a
public HTTPS URL, database and Redis passwords, and a compiler token of at least
32 random characters. Start the stack, check /health/ready locally, then point
the HTTPS proxy to the configured HTTP port. The first account created in the
browser is the administrator.
Production environment variables
Create a .env file beside docker-compose.prod.yml; do not commit it. Generate
the required secrets with:
openssl rand -base64 36
openssl rand -hex 32
openssl rand -base64 32 # TOTP key: exactly 32 decoded bytes
Use distinct values for POSTGRES_PASSWORD, REDIS_PASSWORD, and
LITELEAF_COMPILER_TOKEN. Set LITELEAF_TOTP_ENCRYPTION_KEY only with the last
command's base64 output, and retain it securely: changing it makes existing TOTP
secrets unreadable.
| Group | Variables | Purpose and safe starting point |
|---|---|---|
| Required | LITELEAF_PUBLIC_URL, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, REDIS_PASSWORD, LITELEAF_COMPILER_TOKEN |
Public HTTPS origin; database identity; distinct random secrets; compiler token shared only by app and compiler. |
| Images and port | LITELEAF_VERSION, LITELEAF_APP_IMAGE, LITELEAF_COMPILER_IMAGE, LITELEAF_PULL_POLICY, LITELEAF_HTTP_PORT |
Select the release/images and host port. Keep the published release tag pinned for controlled upgrades. |
| Connections | LITELEAF_DATABASE_MAX_CONNS, LITELEAF_REDIS_POOL_SIZE, LITELEAF_REDIS_PREFIX, LITELEAF_RELAY_INTERVAL, LITELEAF_RECONCILE_AFTER |
Tune only after observing capacity; defaults are appropriate for one app replica. Prefix isolates shared Redis installations. |
| Session and login | LITELEAF_SESSION_TTL, LITELEAF_LOGIN_RATE_WINDOW, LITELEAF_LOGIN_MAX_ATTEMPTS, LITELEAF_FALLBACK_LOCALE |
Control session duration, rate limiting, and default interface language. |
| Compiler | LITELEAF_COMPILE_TIMEOUT, LITELEAF_COMPILER_CONCURRENCY |
Default is 180 seconds and one concurrent job; increase only after sizing CPU, memory, and abuse controls. |
| Storage and limits | LITELEAF_BLOB_ROOT, LITELEAF_BACKUP_ROOT, LITELEAF_BACKUP_MAX_UPLOAD, LITELEAF_PROJECT_ARCHIVE_COMPRESSED_MAX, LITELEAF_PROJECT_ARCHIVE_EXPANDED_MAX |
Container paths and upload/archive ceilings. Keep roots on named volumes and set limits to match available storage. |
| Retention and projects | 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 |
Quotas, cleanup windows, autosave, and compilation behavior. 0 can mean unlimited where the application documents it. |
| Optional integrations | 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 |
Enable only reachable, approved services; leave Ollama URL empty to disable AI and set Git to false to hide Git backup. |
| Identity and 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 |
Optional single sign-on and password reset delivery. Keep client and SMTP secrets out of logs. |
| Proxy and observability | LITELEAF_TRUSTED_PROXIES, LITELEAF_METRICS_TOKEN, LITELEAF_BACKGROUND_WORKERS, LITELEAF_TOTP_ENCRYPTION_KEY |
Trust only proxy addresses under your control, protect metrics with a token, and keep workers enabled on the primary app instance. |
Validate and operate the stack with these commands:
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
When the Compose definition uses named volumes, Docker creates them at first
startup. Inspect them with docker volume inspect <name>; back up data through
the application's verified backup workflow rather than editing volume files.
Configure the instance
The administrative console is available at /admin only to global admins. Use
it to review health, queues, storage, and the installed version; manage users,
roles, locks, sessions, quotas, projects, templates, audit records, and backups.
User lists are paginated and searchable. A quota inherited from the global value
uses NULL; a value of 0 means unlimited. Individual quotas override global
quotas, while Docker values remain the fallback when no setting is saved.
Configure local login first. OIDC is optional: register the callback
https://your-host/auth/oidc/callback, then configure the issuer, client ID,
client secret, and display name. TOTP, recovery codes, session revocation, and
account locks provide further account protection. Keep secrets in environment
files or your deployment secret store; the console never returns them.
Integrations and correction
Ollama is optional and external. Set an HTTP(S) endpoint reachable from the app container, then choose an installed model and prompt in the administrative AI settings. Administrators can test the integration; their saved model and prompt take priority over environment defaults. Inform users where selected text is sent according to institutional policy.
The interactive spelling correction uses Aspell dictionaries for English and Brazilian Portuguese. It proposes replacements, can add a word to the project dictionary, and underlines spelling issues in the editor. Ensure those two dictionaries are present in the deployed image. The compiler timeout defaults to 180 seconds and should be adjusted only with capacity and abuse risk in mind.
Backups, recovery, and updates
Create and verify backups before every update. Confirm readiness, sign in with a non-admin account, compile a canary project, and inspect the audit trail. Do not downgrade the schema after migrations have run. Run a restore drill periodically against disposable PostgreSQL data and blob storage.
Projects maintain attributed manual revisions and consolidated automatic idle
checkpoints. Users can restore a known project state. Each project can also
offer an authenticated, read-only Git origin for a Forgejo or Gitea pull mirror;
the remote service schedules the mirror and Liteleaf never stores its credentials.
Set LITELEAF_GIT_ENABLED=false to disable this capability and its routes.