docker/README.md

Docker Guide

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.

Prerequisites

• Docker
• Docker Compose
• OpenSSL for generating ENCRYPTION_KEY

Quick Start

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" > .env

Start the app:

docker compose up -d

Open http://localhost:3001, add provider keys on the Keys page, then use the generated freellmapi-... key with any OpenAI-compatible client.

Example API Call

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."}]
  }'

Operations

Check status:

docker compose ps

Tail logs:

docker compose logs -f freellmapi

Stop the app:

docker compose down

Update to the latest GHCR image after a release:

docker compose pull
docker compose up -d

Rebuild locally from source:

docker compose up -d --build

Configuration

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.

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.

Published Image

Images are published to GitHub Container Registry:

docker pull ghcr.io/tashfeenahmed/freellmapi:latest

The 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.