PRODUCTION.md

# Production Operations Guide

Phillnet Mini Text-Vision is a **single-process, text-and-still-image inference service**. The included stack is designed for a controlled deployment boundary: one model process, one serialized generation at a time, local base64 image inputs only, optional API-key authentication, and explicit CORS origins.

## Deployment topology

```text
Trusted clients
    │ HTTPS + API key
    ▼
TLS reverse proxy / edge rate limiter
    │ localhost HTTP
    ▼
Docker Compose: Phillnet Mini Text-Vision
    │ one Uvicorn worker + one loaded model
    ▼
Text generation and still-image understanding
```

Keep the model container bound to loopback by default. Terminate TLS, rate limit, and log access at a reverse proxy or managed ingress. The model container itself is intentionally not a public multi-tenant gateway.

## First deployment

```bash
cp .env.example .env
# Set PHILLNET_API_KEY to a long random secret.
# Set PHILLNET_CORS_ORIGINS to the exact browser application origin.
docker compose up --build -d

docker compose ps
curl http://127.0.0.1:8000/ready
```

The service reports `ready: true` only after the processor and checkpoint are loaded.

## Reverse-proxy example

The following Nginx location keeps the container private, applies a request body limit, and forwards the authorization header. Configure a valid TLS server block around it.

```nginx
location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Authorization $http_authorization;
    proxy_set_header X-API-Key $http_x_api_key;
    client_max_body_size 12m;
    proxy_read_timeout 1800s;
    proxy_send_timeout 1800s;
}
```

Apply an edge rate limit appropriate to available RAM and latency. One model worker is deliberate: a concurrent long-context generation can overcommit local memory. Scale by adding isolated model replicas behind a router, not by increasing Uvicorn workers inside one model container.

## Authentication and CORS

Set `PHILLNET_API_KEY` in `.env`. The protected completion route accepts either of these headers:

```http
Authorization: Bearer YOUR_SECRET
```

```http
X-API-Key: YOUR_SECRET
```

Set `PHILLNET_CORS_ORIGINS` to a comma-separated list of known origins such as `https://app.example.com`. Leave it empty for server-to-server callers. Never use a wildcard origin together with a browser-facing credential policy.

## Inference and input limits

| Guardrail | Default | Reason |
|---|---:|---|
| Concurrent generations | 1 | Avoids contention and memory overcommit on one local checkpoint. |
| Maximum visible answer | 8,192 tokens | Matches the model’s persisted response policy. |
| Maximum images per request | 4 | Bounds multimodal preprocessing work. |
| Maximum decoded image size | 10 MiB | Prevents oversized inline payloads. |
| Maximum image pixels | 24,000,000 | Mitigates decompression-bomb and preprocessing risks. |
| Maximum request body | 12 MiB | Rejects oversized JSON before inference. |

## Health and observability

Use these endpoints in the surrounding platform:

| Endpoint | Purpose | Authentication |
|---|---|---|
| `GET /health` | Basic liveness and advertised capability surface. | No |
| `GET /ready` | Readiness after checkpoint and processor load. | No |
| `POST /v1/chat/completions` | Text and optional still-image inference. | Required when `PHILLNET_API_KEY` is set. |

The completion response includes `usage` counts and `elapsed_seconds`, which are sufficient for basic application-side request telemetry. Do not log request images or full user prompts unless your data-retention policy explicitly allows it.

## Upgrade and rollback

Build tagged images rather than relying on mutable local source.

```bash
docker compose build
docker image tag phillnet-mini-text-vision:1.1.0 registry.example.com/phillnet-mini-text-vision:1.1.0
# Push to your trusted registry, then deploy that immutable tag.
```

Retain the preceding image tag and the matching `RELEASE_MANIFEST.json`. Verify the checkpoint hash before switching traffic. Roll back by returning the compose image reference to the prior known-good tag and running `docker compose up -d`.

## Scope boundary

This service supports only **text generation** and **still-image understanding**. It does not expose image generation, video generation, audio, tools, agents, browsing, remote URL fetching, or arbitrary local file access.