# FreeLLMAPI → ClearAI PHP v1.3.0: Docker deployment test kit

This kit contains the uploaded FreeLLMAPI source **unchanged** plus a separate, locked-down deployment overlay. It does not install into your ClearAI cPanel folder. It needs a Linux VPS/server with Docker Compose, a domain you control, and ports 80/443 reachable. The backend takes Node.js 20+ inside Docker; PHP hosting requires no Node.js. **No live service has been deployed or tested.**

## Architecture

ClearAI PHP on cPanel → `https://<gateway-hostname>/v1/chat/completions` → Caddy HTTPS proxy → FreeLLMAPI Docker backend → configured AI providers.

The public proxy publishes **only `/v1/*`**. The FreeLLMAPI dashboard (root, `/api/*`) is reachable only over an authenticated SSH tunnel to `127.0.0.1:3001` on the VPS. FreeLLMAPI enforces the unified API key on its `/v1` routes. No API keys are included in this archive.

## 1. Prepare VPS and DNS

- Get a VPS or Docker-capable always-on machine with Docker Compose, OpenSSL and SSH access. Allow inbound 80/443; keep 3001 blocked from the Internet. A small VPS with several GB RAM is preferable for the source build.
- Choose a hostname e.g. `llm.example.com`; point its DNS A/AAAA records to your VPS. Wait for DNS propagation. Do **not** use the ClearAI PHP domain as the gateway hostname.
- Upload and extract this ZIP to a folder on the VPS. From that folder run:

```bash
chmod +x setup-clearai.sh verify-clearai.sh
./setup-clearai.sh llm.example.com
docker compose -f docker-compose.clearai.yml up -d --build
docker compose -f docker-compose.clearai.yml ps
```

The setup script creates a private `.env` containing a freshly generated 32-byte encryption key. **Back this key up securely together with the FreeLLMAPI SQLite data volume**: changing it later prevents stored upstream credentials from decrypting. The scripts intentionally refuse to overwrite an existing `.env`.

Caddy requests a public TLS certificate automatically. If a different service already uses VPS ports 80 or 443, first decide how to integrate with that server's reverse proxy; do not launch two conflicting proxies.

## 2. Create your dashboard account privately

On your laptop/desktop terminal, use SSH local forwarding (keep the tunnel open):

```bash
ssh -L 13001:127.0.0.1:3001 VPS_USER@VPS_IP
```

On that computer, visit `http://127.0.0.1:13001`, complete first-run account setup. If prompted for a one-time setup code, check VPS logs:

```bash
docker compose -f docker-compose.clearai.yml logs --tail=120 freellmapi
```

In the private dashboard: add an upstream provider API key under **Keys** (for instance a free-tier provider for which you have registered), test/enable models, configure the fallback chain, and copy the **unified API key** from the Keys header. FreeLLMAPI is an aggregator of upstream provider quotas—not a promise of unlimited free tokens.

For a quick connectivity check, run `./verify-clearai.sh` on the VPS and paste the unified API key when prompted. This queries `https://<hostname>/v1/models?available=true` and returns JSON. It does **not** make a chat completion.

## 3. Enter in ClearAI

On `https://clearai.netdaa.co.za` open **Settings → Model provider → FreeLLMAPI** and enter:

- **API Key:** the FreeLLMAPI **unified** API key (not an upstream provider key).
- **Model:** `auto`.
- **API base URL:** `https://llm.example.com/v1` (replace with your actual hostname; keep `/v1`).

Save → reopen settings → **Test saved connection & list models**. The check only establishes authentication and model-list availability. Send a short chat message to verify **actual inference**, then verify real output and limits. Keep fallback checkboxes disabled until the chat tests pass.

## 4. Troubleshooting

- **Connection refused / DNS error:** check A/AAAA records, Docker containers, firewall 80/443, and cPanel outbound 443. The Caddy container must be able to request TLS certificates.
- **HTTP 401/403:** paste the **unified** key, not Google/Groq/OpenRouter API key.
- **Models returned but chat fails:** configure an enabled upstream provider with remaining quota; `/v1/models` may include catalog-only models. Use `available=true` to inspect ready models, then test chat.
- **Proxy 404 at /**: deliberate. Only `/v1/*` is publicly accessible. Use the SSH tunnel for the dashboard.
- **Dashboard won't open from your phone:** expected—there is intentionally no public admin UI. Access it through an SSH tunnel on a computer. Exposing the dashboard publicly is not recommended.
- **Cannot use Docker on your cPanel:** you need a separate VPS or managed container server. Uploading this ZIP to PHP hosting does not run the gateway.
- **Build errors:** ensure the VPS can download Node/Docker packages and has RAM/disk for `npm ci` and the TypeScript/React build. View logs with `docker compose -f docker-compose.clearai.yml logs -f`.

## 5. Upgrades, rollback, data

- The overlay is separate from the project's own `docker-compose.yml` and `Dockerfile`; it builds the uploaded source, not the potentially changing `latest` image.
- For upgrades, backup the `.env` and named Docker volume first; upgrade source only after testing and reading the release notes.
- Stop service: `docker compose -f docker-compose.clearai.yml down` (**without** `-v`, which would delete database state).
- ClearAI files, UI and current models stay unchanged by this kit. Its existing v1.3.0 FreeLLMAPI settings are the PHP connector.

## Scope of validation

Checked uploaded source for `server` package, Node/TypeScript dependencies, official `/v1` paths, `auto` routing, documentation for unified key, and Dockerfile. Deployment overlay verified structurally and scripts checked for syntax. Actual docker image build, SSL provisioning and paid/free provider responses require a real VPS and credentials, so they have **not** been verified here.