Docker Compose is the recommended way to run FreeLLMAPI for personal use. The container serves the Express API and the built React dashboard from one process on port 3001, with SQLite persisted in a named volume.
- Docker
- Docker Compose
- OpenSSL for generating
ENCRYPTION_KEY
Create a .env file with a 32-byte encryption key:
ENCRYPTION_KEY="$(openssl rand -hex 32)"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .envStart the app:
docker compose up -dOpen http://localhost:3001, add provider keys on the Keys page, then use the generated freellmapi-... key with any OpenAI-compatible client.
curl http://localhost:3001/v1/chat/completions \
-H "Authorization: Bearer freellmapi-your-unified-key" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [{"role": "user", "content": "Say hello from FreeLLMAPI."}]
}'Check status:
docker compose psTail logs:
docker compose logs -f freellmapiStop the app:
docker compose downUpdate to the latest GHCR image after a release:
docker compose pull
docker compose up -dRebuild locally from source:
docker compose up -d --build| Variable | Required | Default | Description |
|---|---|---|---|
ENCRYPTION_KEY |
Yes | None | 64-character hex key used to encrypt provider API keys at rest. Generate it once and keep it stable. |
PORT |
No | 3001 |
Host port exposed by Docker Compose. The container listens on port 3001. |
FREEAPI_DB_PATH |
No | /app/server/data/freellmapi.db |
SQLite file path. Set this when your host only persists one mounted directory. |
FREEAPI_DB_BACKUP_PATH |
No | None | Local encrypted backup file. Restored on startup if the DB file is missing, then refreshed while the app runs. |
FREEAPI_DB_BACKUP_URL |
No | None | HTTP(S) encrypted backup target. Startup uses GET; periodic backups use PUT. |
FREEAPI_DB_BACKUP_TOKEN |
No | None | Optional bearer token for FREEAPI_DB_BACKUP_URL. |
FREEAPI_DB_BACKUP_KEY |
No | ENCRYPTION_KEY |
64-character hex key for backup encryption. Use a separate stable key if possible. |
FREEAPI_CONFIG_PATH |
No | None | JSON config file applied idempotently after migrations on every boot. |
FREEAPI_CONFIG_JSON |
No | None | Inline JSON config. Takes precedence over FREEAPI_CONFIG_PATH. |
The freellmapi-data volume stores SQLite data at /app/server/data. Keep the same volume and ENCRYPTION_KEY when upgrading, otherwise existing encrypted provider keys cannot be decrypted.
Example freellmapi.config.json:
{
"keys": [
{ "platform": "groq", "key": "gsk_...", "label": "main" }
],
"customProviders": [
{
"baseUrl": "http://host.docker.internal:11434/v1",
"label": "Ollama",
"models": [
{ "model": "llama3.1:8b", "displayName": "Local Llama", "supportsTools": true }
]
}
],
"routing": { "strategy": "balanced" }
}Images are published to GitHub Container Registry:
docker pull ghcr.io/tashfeenahmed/freellmapi:latestThe Docker workflow builds pull requests without pushing. After this repository receives the workflow on main, pushes to main and version tags publish images to GHCR automatically.