SysDeck/klanker-gate/docs/getting-started/01-installation.md

Installation

This tutorial covers the shortest verified path to a working Frosty Deno installation.

Prerequisites

• Git
• Deno 2.9.x
• Docker and Docker Compose v2.20+ if you want PostgreSQL and optional observability through the shipped Compose assets

Notes:

• The main project does not use the npm CLI for the gateway or the control UI.
• PostgreSQL is a hard dependency for the production bootstrap path.
• Node and npx are only required for the separate tests/browser Playwright harness.

1. Clone the repository

git clone <your-repository-url> klanker-gate
cd klanker-gate

2. Bootstrap Deno-managed dependencies

deno task setup

This installs the npm:esbuild script dependency used by the control UI build.

3. Start PostgreSQL

The quickest path is the included Compose service:

docker compose up -d postgres

This gives you the default local connection used in .env.example:

postgres://frosty:frosty@localhost:5432/frosty

4. Create your .env

Copy the checked-in example and edit it for your environment:

cp .env.example .env

At minimum, set:

• one provider credential such as OPENAI_API_KEY
• FROSTY_PG_URL

Optional but recommended for any non-local environment:

• FROSTY_ADMIN_TOKEN
• FROSTY_ALLOWED_HOSTS
• FROSTY_ENCRYPTION_KEY

5. Start the gateway

deno task dev

Verified behavior of this command:

• loads .env
• starts the gateway on http://localhost:8080
• watches the gateway files for reloads

If PostgreSQL is unreachable, the production bootstrap path fails closed instead of starting with empty state.

6. Verify the install

curl http://localhost:8080/healthz
curl http://localhost:8080/v1/models

If you built the UI, http://localhost:8080/ will serve the control plane from the same origin as the API.

7. Build the control UI

The gateway serves API-only until the UI bundle exists.

deno task build-ui

After that, restart or keep the gateway running and visit:

http://localhost:8080/

What you have now

At this point you have:

• a running gateway on port 8080
• PostgreSQL-backed durable state
• at least one configured provider if you supplied credentials
• an optional same-origin operator UI if you built the control plane

Continue with 02-configuration.md to configure providers, governance, logging, cache, and admin protection.