> ## Documentation Index
> Fetch the complete documentation index at: https://gproxy.leenhawk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloudflare Workers, Netlify, and Vercel

> Deploy GPROXY on Cloudflare Workers, Netlify, or Vercel, connect a database, and sign in.

GPROXY ships deployment templates for Cloudflare Workers, Netlify Functions and Vercel Functions. Use this page when you want a hosted gateway without running a server; for Docker, Render and Heroku, see [Docker, Render, and Heroku](https://gproxy.leenhawk.com/deployment/containers.md).

The templates download prebuilt release bundles at build time, so you do not need a Rust toolchain. The console and the API share the deployment's domain, and the console is at `/console/`.

## Choosing a platform

| Platform | Platform database | Existing database | WebSocket / Realtime |
| - | - | - | - |
| [Cloudflare Workers](#cloudflare-workers) | D1, created during deployment | libSQL / Turso | Supported |
| [Netlify Functions](#netlify) | Netlify Database | PostgreSQL | Not supported |
| [Vercel Functions](#vercel) | PostgreSQL product selected during deployment | PostgreSQL | Supported (platform Beta) |

All three serve HTTP and SSE streaming. If clients need WebSocket or Realtime, choose Cloudflare Workers or Vercel, or run the [CLI or a container](https://gproxy.leenhawk.com/download.md) instead.

On Cloudflare the gateway runs as WebAssembly inside the Worker. On Netlify and Vercel a small Node.js function starts the native `gproxy-serverless` executable and forwards requests to it. The management API and the console are the same on all three; database types, function duration and request size limits come from the platform.

## Before you deploy

Every template asks for two secrets. Prepare them first and keep a copy.

* `GPROXY_ADMIN_PASSWORD`: the console password, at least 8 characters.
* `GPROXY_MASTER_KEY`: a 32-byte key that encrypts upstream credentials in the database, written as 64 hex characters or base64. Generate one with `openssl rand -hex 32`.

The username is `admin` unless you also set `GPROXY_ADMIN_USER`. The password is applied on every startup: if a user with that name exists, only that user's password is changed; if none does, administrator `0` is re-enabled and given the configured name and password. The full rules are under [Bootstrap](https://gproxy.leenhawk.com/reference/configuration.md#bootstrap) in the configuration reference.

> [!WARNING]
>
> Use the same `GPROXY_MASTER_KEY` for every update and redeployment. Credentials sealed under one key cannot be opened with another, so a new key leaves every stored upstream credential unreadable.

If you connect an existing database rather than a platform one, have its connection details ready as well. Each platform's section says which values it needs.

## Cloudflare Workers

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)][cloudflare-auto]

[Use an external libSQL / Turso database][cloudflare-external]

The deploy button creates a D1 database. The second link deploys a variant that connects to an existing libSQL or Turso database and does not create D1.

1. Open the entry you want and connect your GitHub or GitLab account.
2. For D1, choose a database name; Cloudflare creates the database and binds it as `DB`. For an external database, enter `GPROXY_DATABASE_URL` and `GPROXY_LIBSQL_TOKEN`.
3. Enter the administrator password and the master key. Leave the build command as `npm run build` and the deploy command as `npm run deploy`, then deploy.

A Turso URL can be written as `libsql://your-db.turso.io` or as the equivalent HTTPS address. The Worker talks to libSQL over its HTTP interface, so a PostgreSQL connection string does not work here.

A D1 deployment can be switched to libSQL later by setting the same two variables; `GPROXY_DATABASE_URL` takes precedence over the D1 binding. Switching the connection selects a different database. Nothing is copied from D1.

To deploy with Wrangler yourself or change the Worker configuration, see [Deploying to Cloudflare manually](#deploying-to-cloudflare-manually).

## Netlify

[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)][netlify-auto]

[Use an existing PostgreSQL database][netlify-external]

The deploy button uses Netlify Database. The second link opens the same template with a field for an external PostgreSQL connection.

1. Open the entry you want, authorize the repository, and enter the administrator password and the master key.
2. With Netlify Database, the function reads the platform's connection string and you enter nothing. With an existing database, enter its PostgreSQL connection string as `GPROXY_DATABASE_URL`.
3. Keep the template's build command and Functions configuration, then deploy.

An external connection string looks like `postgresql://user:password@db.example.com/gproxy?sslmode=require`; use the values your database provider gives you.

Netlify may still provision a platform database when you supply an external connection. It does no harm: `GPROXY_DATABASE_URL` is checked first.

## Vercel

[![Deploy with Vercel](https://vercel.com/button)][vercel-auto]

[Use an existing PostgreSQL database][vercel-external]

The deploy button asks you to attach a new PostgreSQL product. The second link skips that and asks for `GPROXY_DATABASE_URL` instead.

1. Open the entry you want. With the deploy button, select and attach a PostgreSQL product when prompted.
2. Enter the administrator password and the master key, and for an existing database also `GPROXY_DATABASE_URL`.
3. Keep the template's build command and `vercel.json`, then deploy.

The function looks for a connection string in `GPROXY_DATABASE_URL`, then `DATABASE_URL`, then `POSTGRES_URL`. If the product you attached sets a variable with another name, copy its value into `GPROXY_DATABASE_URL`.

The template uses Node.js Functions. Do not switch it to the Edge Runtime; the function starts a native executable, which the Edge Runtime cannot do.

## Signing in

1. Open `https://your-domain/console/`. The bare domain leads there as well.
2. Sign in as `admin` (or the name you set in `GPROXY_ADMIN_USER`) with the configured password.
3. Add a provider and a credential, and test the credential.
4. Create a model route and an API key, then send a request as described in [Your first request](https://gproxy.leenhawk.com/getting-started/first-request.md).

Clients use the deployment URL as their base URL, for example `https://gateway.example.com/v1`, and authenticate with the API key you created.

On Netlify and Vercel, a request that arrives while the gateway cannot start is answered with status 503 and the message `GPROXY is unavailable. Check the deployment database and secrets in the platform console.` Look at the function logs. The usual causes are a database that is not attached, a connection string that does not start with `postgres://` or `postgresql://`, or a missing password or master key. The executable must report that it is ready within 45 seconds; a database that cannot be reached shows up as a startup timeout. The PostgreSQL account also needs permission to create the `gproxy` schema and the application tables.

## Updating

Configuration, accounts and usage live in the database, so an update only replaces the code. Keep the database and the master key.

The D1 template and the Netlify and Vercel templates download the latest stable release at build time and verify its SHA-256 checksum against the release's `SHA256SUMS`. To upgrade, clear the platform's build cache and redeploy. To stay on one version, set the build environment variable `GPROXY_RELEASE_VERSION` to a release tag; that release must include the bundle for your platform.

The external-database Cloudflare template is different: its `prepare-release.mjs` names a fixed release tag (currently `v4.2.0`) and ignores `GPROXY_RELEASE_VERSION`. To upgrade it, change the tag in that file in the repository the deployment created, then redeploy.

Hosted deployments do not use the console's in-place binary updater.

## Runtime limits

Every template handles HTTP and SSE. Netlify Functions do not accept WebSocket upgrades; the gateway answers such requests with status 501. Vercel supports WebSocket through its [WebSocket Beta](https://vercel.com/docs/functions/websockets). Function duration limits and instance recycling can still close a WebSocket on any platform, so clients must reconnect.

The Vercel template sets `maxDuration` to 300 seconds in `vercel.json`. Long inference requests, large files and high concurrency remain subject to each platform's limits; check the current [Netlify Functions](https://docs.netlify.com/build/functions/overview/) and [Vercel Functions](https://vercel.com/docs/functions/limitations) allowances against your workload.

The Netlify and Vercel templates do not configure file storage. For S3 or R2, or for files that clients download by public link, build a custom Worker as described below, or run the CLI.

OAuth endpoints and published file links need the gateway's public address. On Netlify and Vercel, set `GPROXY_PUBLIC_BASE_URL` to fix it; without it, the function uses the production URL the platform reports. When no public address is known, OAuth endpoints answer with each request's own `Host` and publication links stay disabled. On Workers, set `public_base_url` in `GPROXY_CONFIG` (see below).

## Deploying to Cloudflare manually

### From the release bundle

Download `gproxy-edge-cloudflare.zip` from a release, extract it, and change into its `cloudflare` directory. It contains the built Worker, the console and a `wrangler.toml`.

For D1, install the dependencies and create the database:

```sh theme={null}
pnpm install
pnpm exec wrangler d1 create gproxy
```

Copy the database ID that Wrangler prints into `wrangler.toml`. Keep the binding name `DB`:

```toml theme={null}
[[d1_databases]]
binding = "DB"
database_name = "gproxy"
database_id = "replace-with-your-database-id"
```

Store the master key and the administrator password as secrets, check the deployment, and deploy:

```sh theme={null}
pnpm exec wrangler secret put GPROXY_MASTER_KEY
pnpm exec wrangler secret put GPROXY_ADMIN_PASSWORD
pnpm exec wrangler deploy --dry-run
pnpm exec wrangler deploy
```

For libSQL instead of D1, set `GPROXY_DATABASE_URL` and `GPROXY_LIBSQL_TOKEN` and remove the unused D1 binding. The release bundle is built with libSQL support; keep that feature enabled if you build your own.

GPROXY creates its tables on first startup. You do not need to run Wrangler SQL migrations.

### Worker configuration

`GPROXY_CONFIG` holds a JSON configuration document. Secrets with their own names, such as `GPROXY_MASTER_KEY`, override the matching fields. This example uses D1 and sets the public address:

```toml theme={null}
[vars]
GPROXY_CONFIG = '{"store":{"kind":"d1","binding":"DB"},"cache":{"kind":"store"},"public_base_url":"https://gateway.example.workers.dev"}'
```

The console is served by Workers Assets, so loading it does not run the Worker. Keep the template's routing so that `/console/` is served from the assets and every other path reaches the gateway:

```toml theme={null}
[assets]
directory = "./public"
binding = "ASSETS"
not_found_handling = "single-page-application"
run_worker_first = ["/*", "!/", "!/console", "!/console/*"]
```

A Worker can use D1 or libSQL. It has no local SQLite, no TCP database connections and no local file directory. For S3 or R2 file storage, build with the `s3` feature, set `GPROXY_S3_ACCESS_KEY_ID` and `GPROXY_S3_SECRET_ACCESS_KEY`, and add the file storage fields to the configuration; they are listed in the [configuration reference](https://gproxy.leenhawk.com/reference/configuration.md).

### Building from source

From the repository root:

```sh theme={null}
rustup target add wasm32-unknown-unknown
cargo install worker-build
pnpm --dir console install --frozen-lockfile
pnpm --dir deploy/cloudflare install
pnpm --dir deploy/cloudflare build
pnpm --dir deploy/cloudflare check
```

`build` compiles the Worker into `deploy/cloudflare/build/` and the console into `deploy/cloudflare/public/`; `check` is a Wrangler dry run. [Building from source](https://gproxy.leenhawk.com/development/building.md) covers the other build and packaging options.

[cloudflare-auto]: https://deploy.workers.cloudflare.com/?url=https%3A%2F%2Fgithub.com%2FLeenHawk%2Fgproxy%2Ftree%2Fdev%2Fdeploy%2Fcloudflare-button

[cloudflare-external]: https://deploy.workers.cloudflare.com/?url=https%3A%2F%2Fgithub.com%2FLeenHawk%2Fgproxy%2Ftree%2Fdev%2Fdeploy%2Fcloudflare-external

[netlify-auto]: https://app.netlify.com/start/deploy?repository=https%3A%2F%2Fgithub.com%2FLeenHawk%2Fgproxy&branch=dev&create_from_path=deploy%2Fserverless

[netlify-external]: https://app.netlify.com/start/deploy?repository=https%3A%2F%2Fgithub.com%2FLeenHawk%2Fgproxy&branch=dev&create_from_path=deploy%2Fserverless#GPROXY_DATABASE_URL=

[vercel-auto]: https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FLeenHawk%2Fgproxy%2Ftree%2Fdev%2Fdeploy%2Fserverless&project-name=gproxy&repository-name=gproxy&env=GPROXY_ADMIN_PASSWORD%2CGPROXY_MASTER_KEY&products=%5B%7B%22type%22%3A%22integration%22%2C%22group%22%3A%22postgres%22%2C%22protocol%22%3A%22storage%22%7D%5D

[vercel-external]: https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FLeenHawk%2Fgproxy%2Ftree%2Fdev%2Fdeploy%2Fserverless&project-name=gproxy&repository-name=gproxy&env=GPROXY_ADMIN_PASSWORD%2CGPROXY_MASTER_KEY%2CGPROXY_DATABASE_URL


## Related topics

- [Docker, Render, and Heroku](https://gproxy.leenhawk.com/deployment/containers.md)
- [GPROXY](https://gproxy.leenhawk.com/index.md)
- [Building from Source](https://gproxy.leenhawk.com/development/building.md)
- [Adding a Channel](https://gproxy.leenhawk.com/development/adding-a-channel.md)
- [Configuration Schema](https://gproxy.leenhawk.com/reference/configuration-schema.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.