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/.dockerignorenew file mode 100644index 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.pdfdiff --git a/.github/workflows/docker.yml b/.github/workflows/docker.ymlnew file mode 100644index 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=maxdiff --git a/Dockerfile b/Dockerfilenew file mode 100644index 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.mdindex 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.```bashgit clone https://github.com/tashfeenahmed/freellmapi.gitcd 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" > .envnpm run dev```@@ -113,13 +130,32 @@ database-stored development key when `DEV_MODE=true` and `NODE_ENV` is notOpen 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:```bashnpm run buildnode 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 APIAny 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 reviewdiff --git a/docker-compose.yml b/docker-compose.ymlnew file mode 100644index 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.mdnew file mode 100644index 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.