keenpix

KO | EN

gitlite — search

#cloud-native #awesome #json #dotnet #ai #privacy #gemini #nlp #command-line #claude

(★ 9)

Image optimization CDN with managed cloud and a self-hosted transform engine.

File Explorer

ZIP Download

- config.json
- README.md
- - bug_report.yml
  - config.yml
  - feature_request.yml
- - README.md
  - v0.3.1.md
  - v0.3.2.md
- - ci.yml
  - docker.yml
  - release.yml
- PULL_REQUEST_TEMPLATE.md
- - CHANGELOG.md
  - components.json
  - Dockerfile
  - nitro.config.ts
  - package.json
  - playwright.config.ts
  - source.config.ts
  - tsconfig.json
  - turbo.json
  - vite.config.ts
  - vitest.config.ts
- - CHANGELOG.md
  - package.json
  - tsconfig.json
  - worker-configuration.d.ts
  - wrangler.jsonc
- - CHANGELOG.md
  - Dockerfile
  - package.json
  - source.config.ts
  - tsconfig.json
  - vite.config.ts
- - CHANGELOG.md
  - Dockerfile
  - package.json
  - tsconfig.json
- - CHANGELOG.md
  - Dockerfile
  - package.json
  - tsconfig.json
- - keenpix-public-search-audit-2026-08-18.md
- - acquisition-measurement-2026-09-05.md
- - package.json
  - tsconfig.json
- - package.json
  - tsconfig.json
- - package.json
  - tsconfig.json
- - CHANGELOG.md
  - package.json
  - tsconfig.json
- - package.json
  - tsconfig.json
- - package.json
  - tsconfig.json
- - package.json
  - prisma.config.ts
  - tsconfig.json
- - package.json
  - tsconfig.json
- - LICENSE
  - tsconfig.json
- - package.json
  - tsconfig.json
- - CHANGELOG.md
  - LICENSE
  - package.json
  - README.md
  - tsconfig.json
- - CHANGELOG.md
  - package.json
  - tsconfig.json
- docker-images.md
- docker-images.mjs
- docker-images.test.mjs
- release.mjs
.dockerignore
.env.example
.gitattributes
.gitignore
AGENTS.md
biome.json
brand.md
CHANGELOG.md
CLAUDE.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
DEPLOY-CLOUD.md
DEPLOY-PRODUCTION.md
docker-compose.cloud.yml
docker-compose.coolify.yml
docker-compose.production.yml
docker-compose.yml
docker-entrypoint.sh
knip.config.ts
LICENSE
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
RELEASE.md
SECURITY.md
tsconfig.json
tsconfig.package.json
turbo.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

Keenpix brand image

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Keenpix is a self-hosted image optimization layer for teams that want the speed of an image CDN without handing the pipeline to another service. Point it at an allowlisted origin, request one URL, and Keenpix fetches the image, transforms it with [sharp](https://sharp.pixelplumbing.com/), caches the variant through memory, Dragonfly, and R2/MaxIO tiers, records analytics, and serves a CDN-ready response.

It is built for operators who want the important parts kept visible: project allowlists, request logs, disk cache behavior, and deployment configuration all live in your own stack.

Don't want to run it yourself? The same engine is available as a managed cloud at [keenpix.com](https://keenpix.com) — one managed-delivery meter, unlimited transforms and team members, and a 14-day free trial. The cloud funds the open-source work.

## What Keenpix ships

- **Transform API** - `GET /img/https://origin.example/photo.jpg?project=...&w=...&fmt=...` resizes, crops, filters, re-encodes, negotiates modern formats, and returns immutable cache headers.
- **No public API keys** - access is gated by each project's domain allowlist. An empty allowlist fails closed with 403, so a fresh project is never an open proxy.
- **Internal API keys** - trusted backend systems can manage projects, domains, and pipeline settings through authenticated JSON endpoints.
- **Projects and origins** - each project owns its source host rules, settings, request logs, and analytics.
- **Delivery controls** - optional expiring/versioned HMAC URLs, automatic Client Hints, and project-level watermark overlays.
- **Built-in analytics** - requests, bandwidth saved, cache hit rate, output formats, latency, top images, and source domains come from Postgres rollups fed by the request log; optional Cloudflare edge analytics show the cache layer in front.
- **Self-host dashboard** - seeded super admin, staff invitations, project settings, API keys, Cloudflare edge analytics, and operational views. Transactional email is configured via `EMAIL_PROVIDER` (Postmark / Resend / SMTP) in the environment.
- **Open-internet hardening** - allowlist checks, private/loopback/link-local/CGNAT blocking, IPv4-mapped IPv6 handling, DNS rebinding protection, response-size limits, decompression-bomb limits, and bounded worker concurrency.

Stack: TanStack Start (React 19, SSR) · Prisma 7 + PostgreSQL · sharp · BullMQ + Dragonfly · Docker. AGPL-3.0 licensed.

---

## Code style

Keenpix keeps helpers and utils scoped by folder and purpose:

- `helpers/<domain>/` is for pure domain helpers with real parsing, composition, or validation behavior. Do not put broad catch-all files like `helpers/admin.ts` here.
- `utils/<primitive>/` is for pure generic primitives, not product-specific response shaping.
- Do not extract functions that only return object literals or forward fields. Keep that code in the owning module unless the helper removes real logic or validation edge cases.
- Use operation verbs precisely: `getProject` for one identified project, `listProjects` for a collection, and explicit mutation/check verbs such as `create`, `update`, `delete`, `verify`, `enable`, `disable`, `add`, and `remove`.
- `data-access/` talks to the database; `actions/` combine data-access/helpers/utils/integrations into use cases; `functions/` validate, authorize, shape entry/exit data, and call actions.
- Function complexity lint rules are disabled on purpose. Prefer readable local control flow over splitting code only for a metric.

See [AGENTS.md](./AGENTS.md) and [apps/app/src/README.md](./apps/app/src/README.md) for the full repository rules.

---

## Quick start (Docker — the self-host path)

Requires Docker + Docker Compose.

```bash
cp .env.example .env
# Generate independent auth and worker secrets (compose refuses to start without them):
#   openssl rand -hex 32   →   BETTER_AUTH_SECRET=...
#   openssl rand -hex 32   →   KEENPIX_WORKER_SECRET=...
# Set POSTGRES_PASSWORD, KEENPIX_SUPER_ADMIN_EMAIL, and KEENPIX_SUPER_ADMIN_PASSWORD in .env.
docker compose up -d
```

The app comes up on **http://localhost:3000** and the standalone docs site on **http://localhost:3003** by default. Set `KEENPIX_PORT` or `KEENPIX_DOCS_PORT` to change the host ports, and pin `KEENPIX_APP_IMAGE`, `KEENPIX_TRANSFORM_IMAGE`, `KEENPIX_WORKER_IMAGE`, and `KEENPIX_DOCS_IMAGE` to one release tag for controlled rollouts. Compose runs Postgres, Dragonfly, the control plane, transform data plane, BullMQ worker, and docs; applies migrations on app boot; seeds the default org and super admin user; and health-checks every runtime. The private worker ops server provides `/health/live`, `/health/ready`, `/health/details`, and a BullMQ dashboard at `/workbench` on port 3001. Dragonfly is configured with its BullMQ-required Lua compatibility flag and five-minute snapshots.

The Docker image entrypoint accepts `start` (default), `migrate`, and `seed`. For normal installs, leave the default `start`; it applies migrations, seeds bootstrap data, then starts the app. Set `KEENPIX_RUN_MIGRATIONS=false` or `KEENPIX_RUN_SEED=false` only when an external deployment workflow owns those steps.

## Quick start (Coolify)

Use [docker-compose.coolify.yml](./docker-compose.coolify.yml) for a Coolify service stack.

1. In Coolify, create a new resource with **Docker Compose Empty**.
2. Paste the contents of `docker-compose.coolify.yml`.
3. Set your public domain on the `app` service. Coolify will generate `SERVICE_URL_APP`, database credentials, the auth secret, and the super-admin password. `BETTER_AUTH_URL` and `KEENPIX_APP_URL` are inferred from `SERVICE_URL_APP`, which must match the browser-facing URL without the container port.
4. Optionally change `KEENPIX_SUPER_ADMIN_EMAIL` from the default `admin@example.com`.
5. Deploy, then sign in with `KEENPIX_SUPER_ADMIN_EMAIL` and the generated `SERVICE_PASSWORD_64_ADMIN` value shown in Coolify's environment variables.

The Coolify stack uses the four published Keenpix images, keeps Postgres, Dragonfly, MaxIO, transform, and worker networking private, persists database/cache volumes, runs migrations and seed on app startup, and exposes the app and docs through Coolify's proxy. Coolify generates Better Auth, worker, Postgres, MaxIO, admin, and Workbench credentials when they are not supplied.

If an earlier Coolify deploy failed with a Postgres 18 message about existing data in `/var/lib/postgresql/data`, remove the failed `keenpix-pg` volume from that Coolify resource or recreate the resource before deploying this compose. The Coolify compose now uses a fresh `keenpix_pg18` volume mounted at `/var/lib/postgresql`, which is the Postgres 18-compatible layout.

**First run (empty database):**
1. Open http://localhost:3000 and sign in with `KEENPIX_SUPER_ADMIN_EMAIL` and `KEENPIX_SUPER_ADMIN_PASSWORD`.
2. Create a **project** (its origin hostname is added to the allowlist automatically).
3. In **Settings**, invite staff by copying an invitation link. To email those invitations, set `EMAIL_PROVIDER` (and its vars) in the environment.
4. Add any other image hosts under **Allowed hosts**, and copy the **Project ID** (shown at the top of Settings).
5. Request an image — **no API key**, just make sure the source host is allowlisted:
   ```bash
   curl -o out.webp \
     "http://localhost:3000/img/https://your-cdn.example.com/photo.jpg?project=<PROJECT_ID>&w=600&fmt=webp"
   ```

---

## Quick start (local dev)

Requires Node 22+, pnpm, and a PostgreSQL database.

```bash
pnpm install
cp .env.example .env          # point DATABASE_URL at your Postgres
                              # and set KEENPIX_SUPER_ADMIN_EMAIL / KEENPIX_SUPER_ADMIN_PASSWORD
pnpm db:migrate               # apply schema
pnpm db:seed                  # seed default org + admin user
pnpm dev                      # http://localhost:3000
```

---

## Configuration

All via environment variables (see `.env.example`):

| Variable | Required | Purpose |
|---|---|---|
| `DATABASE_URL` | ✅ | PostgreSQL connection string. |
| `POSTGRES_PASSWORD` | ✅ (compose) | Password for the bundled Compose Postgres service. Compose refuses to start without it. |
| `BETTER_AUTH_SECRET` | ✅ (prod) | Session signing secret — `openssl rand -hex 32`. The app refuses to boot in production with a missing or known-weak/placeholder value. |
| `BETTER_AUTH_URL` | – | Public base URL (default `http://localhost:3000`). HTTPS enables secure cookies automatically. |
| `KEENPIX_APP_URL` | – | Canonical URL used for hosted docs metadata and generated OG/LLM links. Defaults to `BETTER_AUTH_URL`. |
| `KEENPIX_SUPER_ADMIN_EMAIL` | ✅ | Email for the seeded super admin account. |
| `KEENPIX_SUPER_ADMIN_PASSWORD` | ✅ | Password for the seeded super admin account. |
| `KEENPIX_ADMIN_EMAIL` / `KEENPIX_ADMIN_PASSWORD` | – | Legacy aliases for the super-admin bootstrap variables. |
| `LOG_LEVEL` | – | Server log level (`info` by default). |
| `KEENPIX_LOG_DIR` | – | Optional directory for rotating evlog NDJSON files. Structured logs always continue to stdout. |
| `VITE_KEENPIX_PUBLIC_URL` | – | Browser-facing app URL for local/source builds when it cannot be inferred from the browser origin. |
| `VITE_GTM_CONTAINER_ID` | – | Primary consent-gated Google Tag Manager container ID. The published container must contain an unpaused Google tag and event routing; setting the ID alone does not route events. Because Vite embeds this value at build time, set it as both a Docker build argument and a runtime variable in cloud deployments. |
| `VITE_GA_MEASUREMENT_ID` | – | Consent-gated direct GA4 fallback used only when GTM is unset. Set it at both Docker build time and runtime. |
| `EMAIL_PROVIDER` | – | Selects the one active email provider: `postmark`, `resend`, or `smtp`. Unset disables email. The selected provider's vars are validated at startup. |
| `POSTMARK_API_KEY` / `POSTMARK_FROM` / `POSTMARK_MESSAGE_STREAM` | – | Postmark credentials (when `EMAIL_PROVIDER=postmark`). |
| `RESEND_API_KEY` / `RESEND_FROM` | – | Resend credentials (when `EMAIL_PROVIDER=resend`). |
| `SMTP_HOST` / `SMTP_PORT` / `SMTP_SECURE` / `SMTP_USER` / `SMTP_PASSWORD` / `SMTP_FROM_EMAIL` / `SMTP_FROM_NAME` | – | SMTP connection (when `EMAIL_PROVIDER=smtp`; `SMTP_HOST` + `SMTP_FROM_EMAIL` required). |
| `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` / `CLOUDFLARE_ZONE_ID` | – | Cloudflare edge analytics fallback when Settings → CDN cache is not enabled. All four are required in cloud mode so billable, project-attributed edge delivery is captured before usage watermarks advance; they remain optional when self-hosting. Use zone **Analytics → Read** for `CLOUDFLARE_API_TOKEN` and account **Account Analytics → Read** for `CLOUDFLARE_ACCOUNT_API_TOKEN`. |
| `CLOUDFLARE_HOST` | – | Optional hostname filter for Cloudflare edge analytics when one zone serves multiple `/img/*` hosts. |
| `CLOUDFLARE_SAAS_API_TOKEN` / `CLOUDFLARE_SAAS_ZONE_ID` / `CLOUDFLARE_SAAS_CNAME_TARGET` / `CLOUDFLARE_SAAS_EDGE_SECRET` | – | Managed-cloud custom delivery domains. Configure the fallback origin and `apps/delivery-edge` first. The application token needs zone **SSL and Certificates → Edit**; the separate Worker deployment identity owns the wildcard route. |
| `KEENPIX_MODE` | – | `selfhost` (default) or `cloud`. Self-host is single-tenant with no public marketing site, self-signup, or billing. |
| `KEENPIX_RUN_MIGRATIONS` / `KEENPIX_RUN_SEED` | – | Docker entrypoint controls for running migrations and bootstrap seed before app start. Defaults to `true`. |
| `KEENPIX_CACHE_DIR` | – | Disk cache location (default `./.keenpix-cache`). |
| `KEENPIX_CACHE_MAX_BYTES` | – | LRU eviction cap. The app default is 2 GB; the Docker/Coolify compose files default to 8 GB for CDN-fronted origin-shield use. |
| `KEENPIX_CACHE_STALE_MS` | – | Serve cached variants immediately after this age and refresh them in the background; `0` disables internal stale refresh. Default 24h. |
| `KEENPIX_MEMORY_CACHE_MAX_BYTES` | – | In-process hot variant LRU cap; set `0` to disable. The app default is 64 MB; the Docker/Coolify compose files default to 256 MB. |
| `KEENPIX_CACHE_REDIS_URL` | – | Dragonfly transformed-variant tier; Compose supplies `redis://dragonfly:6379`. |
| `KEENPIX_CACHE_DRAGONFLY_MAX_BYTES` | – | Dragonfly variant LRU budget (default 512 MB). |
| `KEENPIX_CACHE_DELETE_AFTER_MS` | – | Terminal variant lifetime across all cache tiers (default 30 days; `0` disables). |
| `KEENPIX_CACHE_S3_*` | – | Cloudflare R2 or S3-compatible durable cache. Compose configures MaxIO when not overridden. |
| `KEENPIX_MAX_WATERMARK_BYTES` | – | Maximum fetched project watermark asset (default 5 MB). |
| `KEENPIX_MAX_ORIGIN_BYTES` | – | Reject origin responses larger than this (default 50 MB). |
| `KEENPIX_MAX_INPUT_PIXELS` | – | Decompression-bomb ceiling (default ~50 MP). |
| `KEENPIX_MAX_DIMENSION` | – | Longest output side when a request omits `w`/`h` (default 4096). |
| `KEENPIX_ORIGIN_TIMEOUT_MS` | – | Per-attempt origin fetch timeout; a slow origin returns 504 (default 10000). |
| `KEENPIX_QUEUE_URL` | – | BullMQ connection URL. Compose points it at the bundled Dragonfly service. |
| `KEENPIX_WORKBENCH_USERNAME` / `KEENPIX_WORKBENCH_PASSWORD` | – | Optional basic auth for the worker's `/workbench` BullMQ dashboard. Both must be set together; production presets generate them. |
| `KEENPIX_WORKER_SECRET` | ✅ (prod) | Independent 32+ character secret authenticating worker callbacks to the app. |
| `KEENPIX_WORKER_CONCURRENCY` | – | Concurrent durable prewarm jobs per worker process (default 4). |
| `KEENPIX_WORKER_PORT` | – | Internal worker ops port (default 3001). Compose probes `/health/ready` without publishing it publicly. |
| `KEENPIX_MEM_LIMIT` / `KEENPIX_CPU_LIMIT` / `KEENPIX_MEM_RESERVATION` | – | Opt-in Docker Compose resource caps for the app container. Default `0` = no limit. When set, Docker enforces them and the Operations page CPU/RAM gauges read the cap as the real ceiling. A too-low memory cap can get the app OOM-killed. |
| `KEENPIX_PG_MEM_LIMIT` / `KEENPIX_PG_CPU_LIMIT` / `KEENPIX_PG_MEM_RESERVATION` | – | Same opt-in resource caps for the bundled Postgres container. Default `0` = no limit. |

The cloud usage job also captures project-attributed Cloudflare `/img/*` edge
history hourly. Billing counts every successful response once regardless of
whether Cloudflare, Keenpix's optimized-variant cache, or a new origin transform
serves it: an edge hit is counted at the edge, while an edge miss is counted only
when the application returns it. Optimizer savings (`bytesSaved`) remain a
separate analytics measure and are never added to delivered bytes. Customer
analytics remain organization/project scoped. See
[`apps/docs/notes/analytics-history.md`](apps/docs/notes/analytics-history.md) for retention, export,
coverage, and the prospective project-attributed edge design.

---

## Transform API

```
GET /img/<origin-url>?project=<id>&w=&h=&q=&fmt=&fit=&dpr=&blur=&...
```

**No authentication header.** Access is controlled by the project's allowlist — the request only succeeds if the source URL's host is listed under that project's **Allowed hosts**.

| Param | Meaning |
|---|---|
| `project` | Project id (copy it from **Settings → Project ID**). Its allowlist is the gate. |
| path source | Source image URL after `/img/` — its host must be on the project allowlist. |
| `w` / `h`, `resize` / `s` | Target width/height (1–5000). `w=auto` uses image Client Hints; `resize`/`s` accept `WIDTHxHEIGHT`, `WIDTH`, or `xHEIGHT`. |
| `q` | Quality 30–100 (default 75). |
| `fmt` | `auto` (Accept-negotiated), `avif`, `webp`, `jpeg`, `png`, `gif`, `heif`, `tiff`, `svg`. |
| `fit` | `cover` / `contain` / `fill` / `inside` / `outside`. |
| `position` / `pos` / `gravity` | Crop anchor for `cover`/`contain`: edges, corners, compass gravity, `entropy`, or `attention`. |
| `dpr` | Device pixel ratio 1–3, or `auto` for `Sec-CH-DPR`. |
| `enlarge` | Allows upscaling when set to `1`/`true`; omitted requests do not upscale. |
| `kernel` | Resize kernel: `nearest`, `linear`, `cubic`, `mitchell`, `lanczos2`, `lanczos3`, `mks2013`, `mks2021`. |
| `background` / `bg`, `flatten` | Fill color and alpha flattening controls. |
| `extract` / `crop`, `trim`, `extend`, `extendWith` | Exact crop rectangle, edge trim, and output padding controls. |
| `rotate` / `r`, `flip`, `flop` | Arbitrary rotation and vertical/horizontal mirroring. |
| `blur`, `sharpen`, `median`, `gamma`, `negate`, `normalize`, `threshold` | Pixel filters and corrections. |
| `brightness`, `saturation`, `hue`, `lightness`, `tint`, `grayscale` / `greyscale` | Color adjustment controls. |
| `animated` / `a` | Preserve animated GIF/WebP frames when output supports them. |

Simple source URLs can be written directly in the path. If the source URL contains its own `?` or `#`, URL-encode the source before appending Keenpix transform parameters.

Responses set immutable cache control, advertise `Sec-CH-DPR`, `Sec-CH-Width`,
and `Sec-CH-Viewport-Width`, and vary by the effective negotiation headers. A CDN
can cache each image variant once you configure it to cache `/img/*` with the full
query string. The source URL lives in the path so Cloudflare and other CDNs can
still see the source file extension; use omitted `fmt` / `fmt=auto` only when your
CDN can cache separate `Accept` variants, and use explicit `fmt` values when you
intentionally want a fixed output format.

Keenpix also supports internal stale-while-revalidate across its ordered cache
coordinator. Production reads memory → Dragonfly → R2/MaxIO, promotes lower hits,
writes durable tiers first, and deletes variants from the chain after
`KEENPIX_CACHE_DELETE_AFTER_MS`. After `KEENPIX_CACHE_STALE_MS`, a cached variant
is still served immediately and a refresh starts in the background.

For good cache hit rates, keep frontend widths normalized. Instead of generating arbitrary widths from every viewport value, choose a small shared ladder such as `320`, `480`, `640`, `768`, `960`, and `1280`, then reuse those values across your CMS and frontend. Each unique `src + project + w + h + q + fmt + fit + dpr + blur` combination is a separate variant.

For Cloudflare, create a Cache Rule matching `http.host eq "keenpix.com" and starts_with(http.request.uri.path, "/img/")` that marks responses eligible for cache. On non-Enterprise plans, leave the Cache key section unset; Cloudflare's default/standard cache key already includes the full request URI with query string, so each `?w=` / `?fmt=` variant is cached separately. Do not enable "Ignore query string". If using `fmt=auto`, the cache key also needs to vary by `Accept`, which requires custom cache-key header support; otherwise prefer explicit `fmt=avif` / `fmt=webp` URLs from integrations.

On Keenpix Cloud, Pro and Business customers can connect branded delivery
hostnames under Settings → Custom domains. Once the displayed CNAME is active,
`https://images.customer.com/img/<source-url>` resolves the associated project
without exposing `?project=`. Self-hosters configure the same host routing and
TLS behavior in their own reverse proxy.

Framework image components usually map their `format` prop directly to `fmt`. Leave that prop unset for browser-based AVIF/WebP negotiation; `format="avif"` or `format="webp"` forces that format.

`fmt=auto` is raster negotiation only, even for SVG origins: Keenpix rasterizes through Sharp and returns AVIF, WebP, or JPEG from the `Accept` header. Only explicit `fmt=svg` returns `image/svg+xml`; it serves SVG origins through SVGO optimization and active-content stripping, and raster transform modifiers do not apply to SVG output.

### IPX modifier comparison

Keenpix is remote-origin and project-allowlist oriented rather than a storage-provider router, but its Sharp modifier surface now covers the practical IPX-style image operations.

| IPX-style capability | Keenpix support | Notes |
|---|---|---|
| `w`, `h`, `q`, `fmt`, `fit`, `dpr`, `blur` | Supported | Original focused surface. |
| `position` / `pos` / `gravity` | Supported | Includes edges, corners, compass gravity, `entropy`, and `attention`. |
| `background` | Supported | Used by `contain`, `flatten`, `extend`, and arbitrary rotate. |
| `flatten` | Supported | Merges alpha onto the configured background. |
| `fit=outside` | Supported | Sharp `outside` fit mode. |
| `resize` / `s=WxH` | Supported | Compact aliases; explicit `w`/`h` take priority. |
| `enlarge` | Supported, opt-in | Default remains no-upscale. |
| `kernel` | Supported | Sharp resize kernels. |
| `extract` / `crop` | Supported | `left,top,width,height`. |
| `trim` | Supported | Boolean or threshold. |
| `extend` | Supported | CSS-like one, two, or four-value padding. |
| arbitrary `rotate` | Supported | EXIF auto-orient still runs first. |
| `flip` / `flop` | Supported | Vertical / horizontal mirror. |
| `sharpen`, `median`, `gamma` | Supported | Conservative numeric ranges. |
| `negate`, `normalize`, `threshold` | Supported | Boolean and threshold controls. |
| `modulate`, `tint`, `grayscale` | Supported | Brightness/saturation/hue/lightness, tint, grayscale. |
| `animated` / `a` | Supported | Enables Sharp animated decoding. |
| Extra formats | Supported | Adds `gif`, `heif`, `tiff`, and explicit `svg` alongside `avif`, `webp`, `jpeg`, `png`. |
| SVGO/SVG optimization | Supported | `fmt=svg` optimizes SVG origins with SVGO and strips active content; `fmt=auto` still returns a negotiated raster format. |
| Local/storage providers | Product-scope difference | Keenpix intentionally uses remote origins gated by project allowlists instead of filesystem/Unstorage providers. |

**Failure modes:**

| Status | When |
|---|---|
| **400** | Missing source URL or `?project`, or a malformed/non-http(s) URL |
| **403** | Source host not on the project allowlist (or the allowlist is empty), it resolves to a private/loopback/link-local/CGNAT/multicast address (incl. IPv4-mapped IPv6 and DNS-rebinding), or the project requires signed URLs and `sig` is missing/invalid |
| **404** | Unknown `project` id |
| **413** | Origin image exceeds `KEENPIX_MAX_ORIGIN_BYTES` |
| **502** | Origin unreachable, errored, returned a non-image body, or too many redirects |
| **504** | Origin timed out |

In an `<img>`, any non-200 shows as a broken image — a 403 almost always means the source host isn't on the allowlist.

---

## SDK API

SDK API keys are for trusted backend integrations such as JoodCMS. They are separate from the public image transform flow: `/img/*` still uses project allowlists and does not require an authentication header.

Create a key from **Settings → API keys** as a super admin. Keys can be scoped to every project or to a single project. Project scope is stored on the Better Auth API key metadata, so no custom token table is used. Project-scoped keys can only read or write that project and cannot create new projects. The key is shown once. Send it as either:

```bash
Authorization: Bearer <KEY>
# or
X-Keenpix-Api-Key: <KEY>
```

All SDK endpoints live under `/api/sdk/v1`, return JSON, and use `Cache-Control: no-store`. The legacy unversioned paths remain compatibility aliases. The self-host build currently uses the default org (`org_default`) for SDK project operations. Authentication intentionally uses API keys: Keenpix does not operate an OAuth authorization server, separate API sandbox, or official CLI. Use the REST API or `@keenpix/sdk`.

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/api/sdk/v1/projects` | List projects visible to the key. All-project keys see all default-org projects; project-scoped keys receive only their project. |
| `POST` | `/api/sdk/v1/projects` | Create a project. All-project write key required. Body: `name`, `origin`, optional `allowedOrigins`. |
| `GET` | `/api/sdk/v1/projects/<projectId>` | Fetch one project. |
| `GET` | `/api/sdk/v1/projects/<projectId>/configuration` | Fetch integration-safe image configuration for clients such as JoodCMS. |
| `PATCH` | `/api/sdk/v1/projects/<projectId>/settings` | Update transform defaults. Body may include `autoFormat`, `stripMetadata`, and/or `defaultQuality`. |
| `POST` | `/api/sdk/v1/projects/<projectId>/prewarm` | Queue cache prewarming for uploaded or newly published source images. |
| `POST` | `/api/sdk/v1/projects/<projectId>/domains` | Add an allowed source host. Body: `{ "host": "cdn.example.com" }`. Use a hostname, not a URL. |
| `DELETE` | `/api/sdk/v1/projects/<projectId>/domains?host=<host>` | Remove an allowed source host. A JSON body `{ "host": "cdn.example.com" }` is also accepted. |

Create a project:

```bash
curl -X POST "https://keenpix.example.com/api/sdk/v1/projects" \
  -H "Authorization: Bearer $KEENPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Storefront",
    "origin": "https://cdn.example.com",
    "allowedOrigins": ["cdn.example.com"]
  }'
```

Read the project configuration that JoodCMS stores and displays:

```bash
curl "https://keenpix.example.com/api/sdk/v1/projects/$PROJECT_ID/configuration" \
  -H "Authorization: Bearer $KEENPIX_API_KEY"
```

Response shape:

```json
{
  "configuration": {
    "projectId": "cm...",
    "projectName": "Storefront",
    "origin": "https://cdn.example.com",
    "allowedOrigins": ["cdn.example.com"],
    "imageBaseUrl": "https://keenpix.example.com/img",
    "transformUrlTemplate": "https://keenpix.example.com/img/<source-url>?project=cm...",
    "defaults": {
      "autoFormat": true,
      "defaultQuality": 75,
      "stripMetadata": true
    },
    "supportedParameters": [
      "project", "url", "w", "h", "q", "fmt", "fit", "dpr", "blur",
      "position", "pos", "gravity", "background", "flatten", "resize", "s",
      "enlarge", "kernel", "extract", "crop", "trim", "extend", "rotate",
      "flip", "flop", "sharpen", "median", "gamma", "negate", "normalize",
      "threshold", "brightness", "saturation", "hue", "lightness", "tint",
      "grayscale", "animated"
    ]
  }
}
```

`imageBaseUrl` and `transformUrlTemplate` are derived from `X-Forwarded-Host` and `X-Forwarded-Proto` when a proxy sends them, then fall back to the request origin. In proxied deployments, configure the reverse proxy to forward the public host and protocol so integrations see the external Keenpix URL.

Manage domains and settings:

```bash
curl -X POST "https://keenpix.example.com/api/sdk/v1/projects/$PROJECT_ID/domains" \
  -H "Authorization: Bearer $KEENPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "host": "assets.customer.com" }'

curl -X PATCH "https://keenpix.example.com/api/sdk/v1/projects/$PROJECT_ID/settings" \
  -H "Authorization: Bearer $KEENPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "autoFormat": true, "defaultQuality": 82, "stripMetadata": true }'
```

Prewarm uploaded images from a trusted integration. This endpoint returns `202` after queuing work; it does not wait for every transform and does not write user-delivery latency rows.

```bash
curl -X POST "https://keenpix.example.com/api/sdk/v1/projects/$PROJECT_ID/prewarm" \
  -H "Authorization: Bearer $KEENPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": ["https://cdn.example.com/uploads/photo.jpg"],
    "widths": [320, 640, 768, 960, 1280],
    "formats": ["avif", "webp"],
    "quality": 75,
    "fit": "cover"
  }'
```

If `widths` or `formats` are omitted, Keenpix prewarms the default width ladder `320, 640, 768, 960, 1280` for `avif` and `webp`. A single request is capped at 200 variants.

Failure modes:

| Status | When |
|---|---|
| **400** | Invalid JSON, invalid URL/host, or invalid settings. |
| **401** | Missing or invalid API key. |
| **403** | API key is project-scoped and cannot access the requested project or operation. |
| **404** | Unknown project or endpoint. |
| **429** | API key rate limit exceeded. |

---

## Scripts

| Command | Does |
|---|---|
| `pnpm dev` | Dev server on :3000 |
| `pnpm build` / `pnpm preview` | Production build / preview |
| `pnpm test` | Unit tests (vitest) |
| `pnpm typecheck` | `tsc --noEmit` |
| `pnpm lint` / `pnpm fix` | Biome check / auto-fix |
| `pnpm knip` / `pnpm doctor` | Dead-code and React health scans |
| `pnpm health` | Full local quality gate: lint, typecheck, tests, knip, doctor, build |
| `pnpm db:migrate` / `db:seed` | Prisma migrate / seed |

---

## Releases and Docker Images

Keenpix releases use one semantic version tag (`vMAJOR.MINOR.PATCH`, e.g. `v0.3.1`) for the platform, Docker images, SDK, and every public framework package. Before tagging, align the five private app/edge package versions plus the public package versions and author `.github/release-notes/vMAJOR.MINOR.PATCH.md` using the [release-note template](./.github/release-notes/README.md). Pushing the tag validates the structured, self-contained notes before publishing public packages, then creates one GitHub Release grouped by component through [release.yml](./.github/workflows/release.yml). npm publishing authenticates with the GitHub Actions OIDC identity for `lord007tn/keenpix` and `release.yml`; it does not use a long-lived npm token. Package-specific tags and GitHub Releases are not used. Docker builds and publishing remain intentionally manual-only: run [docker.yml](./.github/workflows/docker.yml) on the reviewed tag and explicitly enable its publish input to push all four GHCR images as `vX.Y.Z` and `vX.Y`.

Public `@keenpix/*` integration packages use Changesets to record package-facing work, while the complete package family and platform are released on the same version. Run `pnpm changeset` for a package-facing change and describe the final user impact directly in the versioned release-note file. The package family is versioned together so adapters cannot drift away from the shared core contract.

```bash
git tag v0.3.1
git push origin v0.3.1
```

See [RELEASE.md](./RELEASE.md) for the full maintainer checklist. Compose defaults to the `keenpix-app`, `keenpix-transform`, `keenpix-worker`, and `keenpix-docs` GHCR images; pin all four to the same tag or digest.

---

## Hosted Docs

Hosted builds serve the marketing page, Fumadocs documentation, docs search, `llms.txt`, `llms-full.txt`, and generated docs OG images. Self-hosted builds serve the dashboard, API, and documentation, but skip the marketing landing page and LLM export routes.

---

## Architecture

The repository is a pnpm/Turborepo monorepo. Product runtimes live in `apps/`; reusable and publishable boundaries live in `packages/`. There are intentionally no `internal/` or `tooling/` namespaces.

```text
apps/
  app/                 TanStack control plane, dashboard, and public API
  docs/                standalone TanStack Start and Fumadocs application
  transform/           independently scaled image transformation data plane
  worker/              independently scaled BullMQ prewarm consumer
  delivery-edge/       independently deployed Cloudflare delivery Worker
packages/
  analytics/           buffered transform analytics collection
  auth/                shared Better Auth configuration primitives
  bullmq/              BullMQ connections, queues, jobs, and worker factories
  cache/               unstorage-backed disk, memory, S3, and Redis caching
  clickhouse/          ClickHouse client, configuration, queries, and schema
  contracts/           versioned cross-service request and job contracts
  database/            Prisma schema, migrations, generated client, and seed
  email/               provider-neutral transactional email delivery
  logger/              shared evlog terminal and optional disk logging
  sdk/                 publishable server-side management SDK
  transform/           reusable Sharp, SVG, origin, signing, and SSRF logic
  frameworks/
    core/              framework-neutral URL and responsive-image behavior
    react, next, vue, nuxt, svelte, sveltekit, astro, remix, ...
```

Inside `apps/app`, the one-way server layers remain **route → function → action → data-access**. Image delivery runs in `apps/transform`, which owns the HTTP data-plane lifecycle while delegating reusable Sharp, SSRF, origin, signing, SVG, cache, and analytics behavior to flat packages. The control plane proxies self-hosted transform requests during the migration, while the delivery-edge Worker targets the transform origin directly. Durable SDK prewarm work has its own scaling lifecycle in `apps/worker`; every BullMQ connection, queue, job contract, and worker factory lives in `packages/bullmq`. Transactional delivery lives in `packages/email`, and all Node runtimes share evlog through `packages/logger`.

The app, transform service, worker, and docs site each have an independent Docker image. Dragonfly backs BullMQ, while image caching is configured separately so queue storage and transformed-image storage cannot accidentally share an eviction policy.

Every framework adapter extends `@keenpix/core` rather than reimplementing URL construction, responsive attributes, or request signing. The initial family covers HTML, React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro, Remix, TanStack Start, Angular, Analog, Solid, SolidStart, Qwik, Preact, Gatsby, Expo, React Native, Docusaurus, VitePress, Vite, Lit, Eleventy, Ember, Fresh, Redwood, and Waku.

---

## License

[GNU Affero General Public License v3.0](./LICENSE) (AGPL-3.0-only) covers the Keenpix application and private operational packages. The public SDK and framework integrations are MIT licensed so applications can adopt them without inheriting the server's copyleft license.

The self-host engine stays AGPL and free — no rug-pull, no CLA, and no features removed from self-host to upsell the cloud. Releases published before the relicense (v0.1.11 and earlier) remain available under Apache-2.0.

keenpix

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README