Quick Start Guide

Relevant source files

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

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

gr8hopper is a lightweight, performance-first URL redirect service designed for complex, parameter-driven routing. It allows you to centralize redirect logic, whether you're routing traffic to different domains based on dynamic parameters or just need a simple, self-hosted redirector. It can be deployed to the edge on Cloudflare Workers for minimal latency or as a standalone service on any VPS using Node.js, Bun, or Docker.

This guide provides instructions for deploying and configuring gr8hopper. It covers the primary deployment methods, environment configuration, and an overview of the admin interface for managing redirects.

Sources: README.md:7-29

Deployment

gr8hopper offers two primary deployment models: a Docker container for VPS environments and a serverless deployment on Cloudflare Workers for edge performance.

Sources: README.md:46-54, 303-311

Docker (VPS/Self-Hosted)

The easiest way to get started is by using the official Docker image. This method is suitable for any virtual private server (VPS) or local machine.

1. Run the Docker Container:

Use the following command to run the gr8hopper container. You must provide an admin username and password.

docker run -d --restart unless-stopped \
  -p 3000:3000 \
  -e ADMIN_USERNAME=your-username \
  -e ADMIN_PASSWORD=your-secure-password \
  -v gr8hopper-data:/app/data \
  --name gr8hopper \
  ghcr.io/dima6312/gr8hopper:latest

Sources: README.md:47-54

2. Docker Compose (Recommended):

For a more robust setup, use Docker Compose. Create a docker-compose.yml file and a corresponding .env file for your credentials.

docker-compose.yml

services:
  gr8hopper:
    build:
      context: .
      dockerfile: examples/Dockerfile
    container_name: gr8hopper
    ports:
      - "3000:3000"
    environment:
      - ADMIN_USERNAME=${ADMIN_USERNAME:?ADMIN_USERNAME is required}
      - ADMIN_PASSWORD=${ADMIN_PASSWORD:?ADMIN_PASSWORD is required}
      - ADMIN_PATH=${ADMIN_PATH:-admin}
      - CONFIG_FILE=/app/data/routes.json
      - PORT=3000
    volumes:
      - gr8hopper-data:/app/data
    restart: unless-stopped

.env

ADMIN_USERNAME=your-unique-username
ADMIN_PASSWORD=a-very-secure-password

This configuration uses a named volume gr8hopper-data to persist the routes.json file, which stores all your redirect configurations.

Sources: README.md:330-354

The following diagram illustrates the Docker deployment architecture.

Cloudflare Workers (Edge)

Deploying to Cloudflare Workers provides a zero-cost, high-performance solution that runs on Cloudflare's global edge network. Redirects are stored in Cloudflare KV.

1. Create a KV Namespace:
This namespace will store your routes and settings.

npx wrangler kv namespace create ROUTES_KV

2. Configure wrangler.production.toml:
Copy the example file and add the KV namespace ID from the previous step.

cp wrangler.production.toml.example wrangler.production.toml
# Edit wrangler.production.toml and add your KV ID

3. Set Admin Credentials:
Store your admin credentials securely as secrets.

npx wrangler secret put ADMIN_USERNAME
npx wrangler secret put ADMIN_PASSWORD

4. Deploy:

npm run deploy

Sources: README.md:304-325

The diagram below shows the Cloudflare Workers architecture.

Configuration

Configuration is managed through environment variables and a web-based admin panel.

Environment Variables

These variables are essential for setting up the service, especially for authentication.

Variable	Default	Platform	Description
PORT	3000	VPS	HTTP server port.
CONFIG_FILE	./routes.json	VPS	Path to the JSON file for storing routes.
ADMIN_USERNAME	(required)	Both	Admin panel username. Using 'admin' is forbidden.
ADMIN_PASSWORD	(required)	Both	Admin panel password.
ADMIN_PATH	admin	Both	URL path for the admin panel.
CLOUDFLARE_API_TOKEN	undefined	CF	API token for purging the Cloudflare cache.
CLOUDFLARE_ZONE_ID	undefined	CF	Zone ID for purging the Cloudflare cache.

Sources: README.md:144-151, src/server.ts:93-96, 100-116, src/index.ts:47-56

Admin Panel Settings

Global settings can be configured in the admin panel under the "Settings" section.

Field	Default	Description
fallback_url	/not-found	The URL to redirect to when a requested route is not found.
cache_ttl	604800	The browser cache duration in seconds (default is 1 week).
route_param	r	The URL query parameter used to select the redirect route (e.g., ?r=my-route).

Sources: README.md:155-160, src/admin-html.ts:1330-1349

Admin Panel & API

The admin panel provides a UI for managing all aspects of gr8hopper. It is accessible at /admin by default and is protected by Basic Authentication using the ADMIN_USERNAME and ADMIN_PASSWORD.

Sources: README.md:153, src/server.ts:157-159

Features

• Route Management: Create, edit, delete, and toggle redirect routes.
• Settings: Configure global options like fallback URL and cache duration.
• Import/Export: Backup and restore all routes and settings via a JSON file.
• Cache Purge: (Cloudflare only) A button to purge all cached redirects from the CDN.

Sources: README.md:155-164, src/admin-html.ts:1360-1372, 1388-1411

Admin API Endpoints

The admin UI is powered by a set of RESTful API endpoints.

Method	Endpoint	Description
GET	/admin/routes	List all routes.
POST	/admin/routes	Create a new route.
GET	/admin/routes/:id	Get a single route's configuration.
PATCH	/admin/routes/:id	Update an existing route (partial updates supported).
DELETE	/admin/routes/:id	Delete a route.
GET	/admin/settings	Get global settings.
PUT	/admin/settings	Update global settings.
GET	/admin/export	Export all routes and settings as a JSON file.
POST	/admin/import	Import a JSON file, replacing all existing routes.
POST	/admin/purge-cache	Purge the Cloudflare CDN cache.

Sources: README.md:168-177, src/handlers/admin.ts

The following sequence diagram shows the flow for creating a new route via the admin panel.

How It Works: The Redirect Flow

gr8hopper's core function is to process an incoming URL, find a matching route, and issue a permanent (301) redirect. It uses aggressive caching to ensure high performance.

This diagram illustrates the redirect process.

Route Configuration

A route is defined by a unique ID, a destination template, and its status.

Field	Type	Required	Description
id	string	Yes	The unique identifier for the route, used in the URL (?r=id). Can be a pattern.
template	string	Yes	The target URL, with {param} placeholders for dynamic values.
active	boolean	Yes	Toggles whether the redirect is enabled or disabled.
passthrough	boolean	No	If true, appends query parameters from the source URL to the destination.

Sources: README.md:88-93, 1100-1103

Example:

• Route Config: { "id": "partner-a", "template": "https://partner-a.com/product/{id}?ref={route}" }
• Incoming Request: https://your-domain.com/?r=partner-a&id=12345
• Resulting Redirect: 301 Redirect to https://partner-a.com/product/12345?ref=partner-a

The {route} placeholder is automatically replaced with the route's ID. Other placeholders like {id} are populated from the query parameters of the incoming request.

Sources: README.md:85-103