Self-hosting

Glyphfield is a Next.js application with dynamic API, social image, Markdown and full-documentation routes. It is not a static export. A complete deployment runs the Next.js server and lets the browser use Canvas, WebGL, storage, files and downloads normally.

Requirements

Install and run

corepack enable
pnpm install --frozen-lockfile
pnpm dev

pnpm dev starts Next.js with Turbopack on http://localhost:3012.

For a production server:

pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm build
pnpm start

pnpm typecheck generates the documentation collection with fumadocs-mdx before it type-checks. pnpm start runs next start. Set the host and port with your hosting platform or the next start options. Integrations should read their own BASE_URL instead of hard-coding a deployment hostname.

Environment variables

Set NEXT_PUBLIC_STUDIO_URL before pnpm build, because Next.js reads NEXT_PUBLIC_ variables when it builds. The application code in src reads two other environment variables: NODE_ENV, which Next.js sets itself, and VERCEL_ENV, which Vercel sets. Google Analytics loads only on a Vercel production deployment that keeps the default NEXT_PUBLIC_STUDIO_URL, so a copy that sets its own origin sends no analytics. public/llms.txt is a static file that names https://www.glyphfield.com, so edit it in a self-hosted copy.

Routes to keep

Do not configure a CDN to turn the dynamic API, Markdown, social image or full-documentation routes into one long-lived static response.

Local-first storage

Projects and tool state live in each visitor's browser, and there is no server database. This has three consequences for operators:

1. Deploying a new server does not move anyone's browser projects.
2. A change of hostname, scheme or port creates a separate browser storage origin.
3. Server backups do not contain user projects, saved designs or original local files.

Before changing a production origin, ask users to follow Backup and restore.

Proxy and response requirements

• Forward GET, POST and OPTIONS requests with their bodies.
• Keep the Content-Type, Content-Disposition, cache and CORS headers of API responses.
• Accept request bodies up to 5,250,000 bytes, the application's limit, so the application can return its own 413 error.
• Do not rewrite raw SVG responses from /api/generate as HTML.
• After any change to security headers, including cross-origin isolation, test Canvas, fonts, local files, downloads and WebGL.
• Serve production over HTTPS. The clipboard and the EyeDropper API (Pick screen color) work only in a secure context.

Health checks

After deploying, check the contracts as well as the home page:

BASE_URL=https://your-glyphfield.example

curl -fsS "$BASE_URL/api/agent" | jq '.schemaVersion'
curl -fsS "$BASE_URL/api/labs" | jq '.count'
curl -fsS "$BASE_URL/api/materials" | jq '.count'
curl -fsS "$BASE_URL/openapi.json" | jq '.openapi'
curl -fsS "$BASE_URL/docs/reference/endpoints.md" | head
curl -fsS "$BASE_URL/llms-full.txt" | head

Then open the deployed Studio in a supported browser, create a temporary project, render a material, reload once and export a small PNG. Passing HTTP checks does not prove that browser storage or graphics work.

Generation smoke test

curl -fsS -X POST "$BASE_URL/api/generate" \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "background",
    "identity": { "preset": "gt" },
    "settings": { "width": 1200, "height": 630 },
    "output": "raw"
  }' \
  -o glyphfield-smoke.svg

test -s glyphfield-smoke.svg

Read GET /api/generate before changing the request. The live contract is authoritative.

Operational ownership

The application validates request shapes, body size and geometry limits. The hosting platform owns network rate limiting, request logs, abuse response, uptime and rollback. A passing local build does not confirm that a firewall rule is active on the host. API security describes the production rate limit, and Browser support covers graphics, storage and codec checks.

Release checklist

1. Install from the lockfile.
2. Generate the docs collection and type-check.
3. Run the contract and rendering tests.
4. Build the production application.
5. Review firewall changes before publishing them.
6. Check the discovery, Markdown, OpenAPI, generation and social image routes.
7. Check browser storage and one still or motion export that the release affects.
8. Keep the previous deployment available until the source and export smoke tests pass.

Contributing, Troubleshooting and Storage and privacy cover development and operations further.