Environment Variables

Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/dima6312/gr8hopper/blob/HEAD/README.md) - [src/server.ts](https://github.com/dima6312/gr8hopper/blob/HEAD/src/server.ts) - [src/index.ts](https://github.com/dima6312/gr8hopper/blob/HEAD/src/index.ts) - [src/handlers/admin.ts](https://github.com/dima6312/gr8hopper/blob/HEAD/src/handlers/admin.ts) - [src/middleware/auth.ts](https://github.com/dima6312/gr8hopper/blob/HEAD/src/middleware/auth.ts) - [SECURITY.md](https://github.com/dima6312/gr8hopper/blob/HEAD/SECURITY.md)

Environment variables are the primary method for configuring a gr8hopper instance. They control critical settings such as authentication credentials, server port, storage paths, and integration with platform-specific features like Cloudflare's cache purging. The required variables differ slightly depending on the deployment platform (VPS/Docker vs. Cloudflare Workers).

Proper configuration via environment variables is essential for a secure and functional deployment. The application will fail to start if required authentication variables are not provided, ensuring that instances are not deployed in an insecure state.

Variable Loading Process

The application loads environment variables at startup. The process differs between the Node.js server (for VPS/Docker) and the Cloudflare Workers entry point.

This diagram illustrates the startup and configuration loading flow for both platforms.

Summary of Environment Variables

The following table summarizes all environment variables used by gr8hopper.

Variable	Default	Platform	Description
ADMIN_USERNAME	(required)	Both	Admin panel username. The value 'admin' is rejected for security.
ADMIN_PASSWORD	(required)	Both	Admin panel password.
ADMIN_PATH	admin	Both	The URL path for the admin interface (e.g., /admin).
PORT	3000	VPS/Docker	The HTTP port the Node.js server listens on.
CONFIG_FILE	./routes.json	VPS/Docker	Path to the JSON file used for storing routes and settings.
CLOUDFLARE_API_TOKEN	(optional)	Cloudflare	A Cloudflare API token with Zone.Cache Purge permission. Enables the "Purge All" button in the admin UI.
CLOUDFLARE_ZONE_ID	(optional)	Cloudflare	The Zone ID of your domain on Cloudflare. Required for the cache purge feature.

Sources: README.md:120-127, src/server.ts:89-92, src/index.ts:40-52, src/handlers/admin.ts:310-315

Detailed Variable Explanations

Core Authentication Variables

These variables are mandatory for both deployment platforms and are used to secure the admin panel.

ADMIN_USERNAME & ADMIN_PASSWORD

These credentials are used for HTTP Basic Authentication on all admin-related endpoints (/admin/*). The application will refuse to start if these are not set.

Validation Logic (VPS/Docker):

• The src/server.ts entry point explicitly checks for the presence of process.env.ADMIN_USERNAME and process.env.ADMIN_PASSWORD.
• If either is missing, an error is logged to the console, and the process exits with code 1.
• For enhanced security, the username admin (case-insensitive) is explicitly disallowed to prevent the use of common, easily guessable credentials.

// File: src/server.ts:95-110, 122-133

// ADMIN_USERNAME and ADMIN_PASSWORD are required for security - no defaults
if (!process.env.ADMIN_USERNAME) {
  console.error(`
╔════════════════════════════════════════════════════════════════════════════╗
║  ❌ FATAL: ADMIN_USERNAME environment variable is required!                ║
║                                                                            ║
║  Set it with: export ADMIN_USERNAME=your-username                          ║
╚════════════════════════════════════════════════════════════════════════════╝
`)
  process.exit(1)
}
// ... similar check for ADMIN_PASSWORD ...

// Reject generic 'admin' username for security
if (ADMIN_USERNAME.toLowerCase() === 'admin') {
  console.error(`
╔════════════════════════════════════════════════════════════════════════════╗
║  ❌ FATAL: ADMIN_USERNAME cannot be 'admin'!                               ║
// ...
╚════════════════════════════════════════════════════════════════════════════╝
`)
  process.exit(1)
}

Sources: src/server.ts:95-133, src/index.ts:40-52, src/middleware/auth.ts, SECURITY.md:16-18

Core Application Variables

ADMIN_PATH

This variable allows you to change the admin panel's URL from the default /admin to a custom path. This is a security-through-obscurity measure to make it harder for unauthorized users to find the login page.

• VPS/Docker: Read from process.env.ADMIN_PATH with a default of 'admin'.
• Cloudflare Workers: Read from env.ADMIN_PATH with a default of 'admin'.

Sources: src/server.ts:91, src/index.ts:38, README.md:126

VPS/Docker Specific Variables

These variables are only relevant when running gr8hopper as a standalone Node.js process, typically via Docker or systemd.

• PORT: Specifies the TCP port for the HTTP server. Defaults to 3000.
• CONFIG_FILE: Defines the file system path to the routes.json file, which acts as the database in this mode. Defaults to ./routes.json. The Docker image remaps this to /app/data/routes.json inside a volume.

Sources: src/server.ts:89-90, README.md:122-123

Cloudflare Workers Specific Variables

When deploying to Cloudflare, configuration is provided through bindings and secrets set in wrangler.toml or the Cloudflare dashboard.

CLOUDFLARE_API_TOKEN & CLOUDFLARE_ZONE_ID

These are optional secrets used to enable the "Purge CDN Cache" feature in the admin UI.

• If both CLOUDFLARE_API_TOKEN and CLOUDFLARE_ZONE_ID are set as secrets, the admin handler will use them to make an API call to Cloudflare to purge the entire zone cache.
• This functionality is handled in src/handlers/admin.ts. The /admin/purge-cache endpoint is protected by the same basic auth as other admin routes.

// File: src/handlers/admin.ts:310-315
app.post('/purge-cache', async (c) => {
    if (!cloudflare?.apiToken || !cloudflare?.zoneId) {
      return c.json({
        error: 'Cache purging not configured. Set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ZONE_ID environment variables.'
      }, 400)
    }
// ...

Sources: src/handlers/admin.ts:310-335, src/index.ts:55-57, README.md:204-205

Development Environment (.dev.vars)

For local development in a VPS/Docker-like environment, src/server.ts includes a utility function loadDevVars to load environment variables from a .dev.vars file at the project root.

• This function is only executed if NODE_ENV is not 'production'.
• It parses the .dev.vars file and sets the variables in process.env if they are not already set.
• This provides a convenient way to manage development credentials without exporting them in the shell.

Sources: src/server.ts:18-86