Deploying to Cloudflare Workers

Relevant source files

The following files were used as context for generating this wiki page:

• src/index.ts
• README.md
• src/handlers/admin.ts
• package.json
• src/admin-html.ts
• src/server.ts

Deploying gr8hopper to Cloudflare Workers is the recommended method for production environments. This approach leverages Cloudflare's global edge network to provide a lightweight, high-performance, and cost-effective URL redirect service. The application is designed to be deployed as a single serverless function that uses Cloudflare KV for persistent storage of routes and settings.

This deployment model offers significant advantages, including minimal latency for redirects, aggressive caching at the edge, and zero-maintenance data storage. The entire application, including the admin UI, is self-contained within the Worker, making it a portable and efficient solution.

Sources: README.md

Architecture Overview

When deployed on Cloudflare, gr8hopper consists of a Hono-based application running as a single Worker script. It interfaces with a Cloudflare KV namespace for all data storage and can optionally connect to the Cloudflare API for cache purging.

Sources: src/index.ts, README.md

The following diagram illustrates the high-level architecture of gr8hopper on Cloudflare Workers.

Deployment Steps

The deployment process uses the wrangler CLI, the official tool for managing Cloudflare developer products.

Sources: README.md, package.json:13

1. Create a KV Namespace

First, create a KV namespace to store the application's routes and settings. This is a one-time setup.

npx wrangler kv namespace create ROUTES_KV

This command will output a namespace ID, which is required for the next step.

Sources: README.md

2. Configure wrangler.production.toml

Create a wrangler.production.toml file by copying the provided example. This file is git-ignored to protect your production-specific IDs.

cp wrangler.production.toml.example wrangler.production.toml

Then, edit wrangler.production.toml and insert the KV namespace ID you obtained in the previous step.

# wrangler.production.toml

# ... other configurations

[[kv_namespaces]]
binding = "ROUTES_KV"
id = "your-production-kv-namespace-id" # <-- Replace with your ID

Sources: README.md, src/index.ts:28

3. Set Admin Credentials

Admin credentials are required and must be set as secrets for the Worker.

npx wrangler secret put ADMIN_USERNAME
npx wrangler secret put ADMIN_PASSWORD

The application will fail to start if these secrets are not configured.

Sources: README.md, src/index.ts:38-46

4. (Optional) Configure Cache Purge

To enable the "Purge All" button in the admin UI, set the following secrets. The API token needs Zone.Cache Purge permission.

npx wrangler secret put CLOUDFLARE_API_TOKEN
npx wrangler secret put CLOUDFLARE_ZONE_ID

Sources: README.md, src/index.ts:55-57, src/handlers/admin.ts:398-401

5. (Optional) Bulk Import Routes

You can pre-populate the KV namespace with routes from a JSON file using an npm script. This is useful for initial setup or CI/CD pipelines.

# Import routes.json to production KV
npm run import:routes routes.json

Sources: README.md, package.json:15

6. Deploy the Worker

Deploy the application to your Cloudflare account using the deploy script defined in package.json.

npm run deploy

This command bundles the code and uploads it to Cloudflare, applying the configuration from wrangler.production.toml.

Sources: package.json:13, README.md

7. (Optional) Add a Custom Domain

After deployment, you can assign a custom domain to your Worker via the Cloudflare Dashboard under Workers & Pages > [your worker] > Settings > Triggers > Custom Domains.

Sources: README.md

Configuration

Configuration for the Cloudflare Worker is managed through wrangler.production.toml and environment secrets.

Worker Secrets

Secrets are used for sensitive information and are injected into the Worker environment at runtime.

Variable	Required	Description
ADMIN_USERNAME	Yes	The username for accessing the admin panel.
ADMIN_PASSWORD	Yes	The password for accessing the admin panel.
ADMIN_PATH	No	Customizes the URL path for the admin panel. Defaults to admin.
CLOUDFLARE_API_TOKEN	No	An API token with Zone.Cache Purge permissions. Enables the cache purge feature.
CLOUDFLARE_ZONE_ID	No	The Zone ID of your domain on Cloudflare. Required for the cache purge feature.

Sources: src/index.ts:35-57, README.md

Request Handling

The Worker entry point is src/index.ts. It uses a single Hono app instance to handle all incoming requests. On the first request (cold start), it initializes the storage adapter and request handlers.

This diagram shows the request lifecycle within the worker.

Data Storage with Cloudflare KV

For Cloudflare deployments, gr8hopper uses Cloudflare KV as its data store.

• Adapter: The KVAdapter class, defined in src/storage/kv.ts, implements the StorageAdapter interface to interact with the KV namespace.
• Data: All routes and global settings are stored as key-value pairs.
• Consistency: KV has an eventual consistency model. Changes made in the admin UI may take up to 60 seconds to propagate globally to all of Cloudflare's edge locations.

Sources: src/index.ts:26-31, README.md

Cache Management

A core feature of the Cloudflare deployment is its aggressive caching strategy to ensure high performance and low cost.

Caching Strategy

1. First Request: When a unique URL is requested for the first time, the Worker executes, looks up the route in KV, generates the destination URL, and returns a 301 Moved Permanently redirect. This response includes Cache-Control headers.
2. Subsequent Requests: The 301 response is cached at the Cloudflare edge. All subsequent requests for the same URL are served directly from the edge cache, which means the Worker does not execute.

Sources: README.md

Cache Purging

If a redirect destination needs to be updated, the Cloudflare CDN cache must be purged. This can be done via the "Purge All" button in the admin UI, provided the CLOUDFLARE_API_TOKEN and CLOUDFLARE_ZONE_ID secrets are configured.

The cache purge flow is as follows: