Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

feat(docker): Docker + GHCR support (adopts #44, +multi-arch & localhost-bind) (#129)

Tashfeen606397fa65a9
diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 00000000..b04cc417
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,20 @@
+.git
+.github
+node_modules
+client/node_modules
+server/node_modules
+shared/node_modules
+client/dist
+server/dist
+server/data
+dist
+.env
+.env.*
+*.db
+*.db-wal
+*.db-shm
+*.bak
+.DS_Store
+npm-debug.log*
+repo-assets
+free-ai-apis.pdf
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
new file mode 100644
index 00000000..880760f3
--- /dev/null
+++ b/.github/workflows/docker.yml
@@ -0,0 +1,54 @@
+name: Docker
+
+on:
+ push:
+ branches: [main]
+ tags: ['v*.*.*']
+ pull_request:
+ branches: [main]
+
+permissions:
+ contents: read
+ packages: write
+
+jobs:
+ build:
+ name: Build Docker image
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: docker/setup-qemu-action@v3
+
+ - uses: docker/setup-buildx-action@v3
+
+ - name: Log in to GHCR
+ if: github.event_name != 'pull_request'
+ uses: docker/login-action@v3
+ with:
+ registry: ghcr.io
+ username: ${{ github.actor }}
+ password: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Docker metadata
+ id: meta
+ uses: docker/metadata-action@v5
+ with:
+ images: ghcr.io/${{ github.repository_owner }}/freellmapi
+ tags: |
+ type=ref,event=branch
+ type=ref,event=tag
+ type=sha,prefix=sha-
+ type=raw,value=latest,enable={{is_default_branch}}
+
+ - name: Build and publish
+ uses: docker/build-push-action@v6
+ with:
+ context: .
+ file: ./Dockerfile
+ platforms: linux/amd64,linux/arm64
+ push: ${{ github.event_name != 'pull_request' }}
+ tags: ${{ steps.meta.outputs.tags }}
+ labels: ${{ steps.meta.outputs.labels }}
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 00000000..3050000c
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,46 @@
+# syntax=docker/dockerfile:1.7
+
+ARG NODE_IMAGE=node:20-bookworm-slim
+
+FROM ${NODE_IMAGE} AS deps
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+COPY shared/package.json ./shared/
+COPY server/package.json ./server/
+COPY client/package.json ./client/
+
+RUN npm ci
+
+FROM deps AS build
+WORKDIR /app
+
+COPY . .
+
+RUN npm run build
+RUN npm prune --omit=dev
+
+FROM ${NODE_IMAGE} AS runtime
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV PORT=3001
+
+COPY --from=build --chown=node:node /app/package.json /app/package-lock.json ./
+COPY --from=build --chown=node:node /app/node_modules ./node_modules
+COPY --from=build --chown=node:node /app/shared ./shared
+COPY --from=build --chown=node:node /app/server/package.json ./server/package.json
+COPY --from=build --chown=node:node /app/server/dist ./server/dist
+COPY --from=build --chown=node:node /app/client/dist ./client/dist
+
+RUN mkdir -p /app/server/data && chown -R node:node /app/server/data
+
+USER node
+
+EXPOSE 3001
+VOLUME ["/app/server/data"]
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+ CMD node -e "fetch('http://127.0.0.1:' + (process.env.PORT || 3001) + '/api/ping').then((res) => { if (!res.ok) process.exit(1); }).catch(() => process.exit(1));"
+
+CMD ["node", "server/dist/index.js"]
diff --git a/README.md b/README.md
index e23c9dcb..f33d5289 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,7 @@ Aggregate the free tiers from Google, Groq, Cerebras, SambaNova, NVIDIA, Mistral
- [Features](#features)
- [Not yet supported](#not-yet-supported)
- [Quick start](#quick-start)
+- [Docker](#docker)
- [Using the API](#using-the-api)
- [Screenshots](#screenshots)
- [How it works](#how-it-works)
@@ -92,18 +93,34 @@ PRs that add any of these are very welcome. See [Contributing](#contributing).
## Quick start
-**Prerequisites:** Node.js 20+, npm.
+**Recommended:** Docker Compose. It runs the API and dashboard together on port 3001 and persists SQLite in a named volume.
+
+**Prerequisites:** Docker, Docker Compose, OpenSSL.
```bash
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
-npm install
# Generate an encryption key for at-rest key storage
-cp .env.example .env
-echo "ENCRYPTION_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")" >> .env
+ENCRYPTION_KEY="$(openssl rand -hex 32)"
+printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
+
+docker compose up -d
+```
+
+Open http://localhost:3001, add your provider keys on the **Keys** page, reorder the **Fallback Chain** to taste, and grab your unified API key from the **Keys** page header. That unified key is what you point your OpenAI SDK at.
-# Start server + dashboard together
+### Local development
+
+**Prerequisites:** Node.js 20+, npm.
+
+```bash
+git clone https://github.com/tashfeenahmed/freellmapi.git
+cd freellmapi
+npm install
+cp .env.example .env
+ENCRYPTION_KEY="$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')"
+printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
npm run dev
```
@@ -113,13 +130,32 @@ database-stored development key when `DEV_MODE=true` and `NODE_ENV` is not
Open http://localhost:5173 (the Vite dev UI), add your provider keys on the **Keys** page, reorder the **Fallback Chain** to taste, and grab your unified API key from the **Keys** page header. That unified key is what you point your OpenAI SDK at.
-For a production build:
+For a production build without Docker:
```bash
npm run build
node server/dist/index.js # server + dashboard both served on :3001
```
+## Docker
+
+FreeLLMAPI publishes a single production image that contains the Express server and the built React dashboard:
+
+```bash
+docker pull ghcr.io/tashfeenahmed/freellmapi:latest
+```
+
+The included `docker-compose.yml` is the recommended install path:
+
+```bash
+docker compose up -d
+docker compose logs -f freellmapi
+```
+
+SQLite data is stored in the `freellmapi-data` volume at `/app/server/data`. Keep the same `.env` `ENCRYPTION_KEY` and volume when upgrading, because provider keys are encrypted at rest.
+
+More Docker operations and examples live in [docker/README.md](./docker/README.md).
+
## Using the API
Any OpenAI-compatible client works. Examples:
@@ -308,6 +344,7 @@ PRs should include a test, keep the existing test suite green, and match the `.e
<a href="https://github.com/JammyJames1234"><img src="https://images.weserv.nl/?url=github.com/JammyJames1234.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@JammyJames1234" /></a>
<a href="https://github.com/Sumit4codes"><img src="https://images.weserv.nl/?url=github.com/Sumit4codes.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@Sumit4codes" /></a>
<a href="https://github.com/meliani"><img src="https://images.weserv.nl/?url=github.com/meliani.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@meliani" /></a>
+<a href="https://github.com/thedavidweng"><img src="https://images.weserv.nl/?url=github.com/thedavidweng.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@thedavidweng" /></a>
## Terms of Service review
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 00000000..cde5e39f
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,33 @@
+services:
+ freellmapi:
+ image: ghcr.io/tashfeenahmed/freellmapi:latest
+ build:
+ context: .
+ dockerfile: Dockerfile
+ env_file:
+ - .env
+ environment:
+ NODE_ENV: production
+ PORT: 3001
+ # Bound to localhost by default — FreeLLMAPI is single-user and must not be
+ # exposed to the internet. Set HOST_BIND=0.0.0.0 to reach it from your LAN.
+ ports:
+ - "${HOST_BIND:-127.0.0.1}:${PORT:-3001}:3001"
+ volumes:
+ - freellmapi-data:/app/server/data
+ restart: unless-stopped
+ healthcheck:
+ test:
+ [
+ "CMD",
+ "node",
+ "-e",
+ "fetch('http://127.0.0.1:3001/api/ping').then((res) => { if (!res.ok) process.exit(1); }).catch(() => process.exit(1));"
+ ]
+ interval: 30s
+ timeout: 5s
+ start_period: 15s
+ retries: 3
+
+volumes:
+ freellmapi-data:
diff --git a/docker/README.md b/docker/README.md
new file mode 100644
index 00000000..5be329e4
--- /dev/null
+++ b/docker/README.md
@@ -0,0 +1,90 @@
+# 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:
+
+```bash
+ENCRYPTION_KEY="$(openssl rand -hex 32)"
+printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
+```
+
+Start the app:
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+docker compose ps
+```
+
+Tail logs:
+
+```bash
+docker compose logs -f freellmapi
+```
+
+Stop the app:
+
+```bash
+docker compose down
+```
+
+Update to the latest GHCR image after a release:
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+Rebuild locally from source:
+
+```bash
+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:
+
+```bash
+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.