Deploying with Node.js/Bun

Relevant source files

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

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

This document provides a technical overview of deploying the gr8hopper application as a standalone server using Node.js or Bun. This deployment method is suitable for Virtual Private Server (VPS) environments and contrasts with the edge deployment on Cloudflare Workers. The Node.js/Bun server uses a local JSON file for data persistence and is configured via environment variables.

The primary entry point for this deployment model is src/server.ts, which leverages the Hono framework and its @hono/node-server adapter to create an HTTP server.

Sources: src/server.ts:4, README.md:10

Server Architecture

The Node.js/Bun server is built around the Hono web framework, providing a lightweight and fast foundation. The architecture consists of several key components that are initialized and wired together at startup.

The server uses a JsonFileAdapter for storing route configurations and global settings, reading from and writing to a local JSON file. It exposes two main sets of routes: public-facing redirect routes and a password-protected admin area for managing the service.

Sources: src/server.ts:10-15, CONTRIBUTING.md:32-37

The following diagram illustrates the high-level architecture of the Node.js server:

This diagram shows how an incoming request is handled by the Hono server, passed through middleware, and routed to either the Admin or Redirect handler, which in turn interact with the JSON file storage adapter.

Sources: src/server.ts:162-177, src/handlers/admin.ts:18

Configuration

The server is configured exclusively through environment variables. This design choice is ideal for containerized and modern VPS deployments. For local development, a .dev.vars file can be used to load these variables automatically, but this is skipped in a production environment.

Sources: src/server.ts:20-28, src/server.ts:88-91

Environment Variables

The following table details the environment variables used to configure the server:

Variable	Default	Description
PORT	3000	The HTTP port the server will listen on.
CONFIG_FILE	./routes.json	The file path for storing route and settings data. For Docker, this is /app/data/routes.json.
ADMIN_USERNAME	(required)	The username for accessing the admin panel. Cannot be admin.
ADMIN_PASSWORD	(required)	The password for accessing the admin panel.
ADMIN_PATH	admin	The URL path for the admin panel (e.g., http://.../admin).

The application will exit with a fatal error if ADMIN_USERNAME or ADMIN_PASSWORD are not set, or if ADMIN_USERNAME is set to the generic value 'admin'.

Sources: README.md:156-162, src/server.ts:93-134

Security Configuration

For production VPS deployments, it is recommended to run the application behind a reverse proxy like Nginx. This allows for HTTPS termination and the addition of important security headers.

# Example Nginx snippet for adding security headers
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Frame-Options "DENY" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "no-referrer" always;

Sources: SECURITY.md:72-77

Startup Sequence

When the server starts, it follows a specific sequence to initialize all components before it begins accepting requests.

The sequence diagram below shows the server startup process:

This sequence ensures that all dependencies like storage and handlers are ready before the server begins listening for traffic.

Sources: src/server.ts:85-188

Request Routing

All incoming requests are handled by a single Hono application instance. Middleware is used to apply authentication and CORS policies to the admin-related paths.

The routing logic is as follows:

1. Requests to the path defined by ADMIN_PATH (e.g., /admin) and any sub-paths (e.g., /admin/routes) are first processed by CORS and Basic Authentication middleware.
2. Authenticated requests to the root of the admin path (/admin or /admin/) serve the admin panel HTML.
3. Authenticated requests to sub-paths of the admin path are routed to the adminHandler for API operations.
4. All other requests are routed to the redirectHandler to be processed as potential redirects.

This flow is visualized in the diagram below:

Deployment & Execution

The README.md and package.json files outline several methods for deploying and running the server in a Node.js or Bun environment.

Using NPM/Node.js

The application can be run directly from source or after being built.

• Development (with hot-reload): npm run dev:node
• Production (from source): npm start (which runs node dist/server.js)
• Global Install: npm install -g gr8hopper followed by npx gr8hopper

Sources: package.json:11-13, README.md:288-299

Using Bun

Bun can run the TypeScript source file directly.

bun install
ADMIN_USERNAME=your-username ADMIN_PASSWORD=your-password bun run src/server.ts

Sources: README.md:302-303, package.json:14

Using Docker

The recommended method for a VPS deployment is using Docker or Docker Compose. The repository provides a Dockerfile for building a production-ready image.

Docker Run Command:

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

This command uses a named volume gr8hopper-data to persist the routes.json file.

Sources: README.md:52-60

Docker Compose:
The README.md also provides a docker-compose.yml example that uses an .env file for credentials and includes a health check.

Sources: README.md:244-275

Using Systemd

For a more traditional VPS setup, a systemd service can be created to manage the Node.js process. This involves creating an environment file for credentials and a service unit file.

Systemd Service File (/etc/systemd/system/gr8hopper.service):

[Unit]
Description=Gr8hopper
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/gr8hopper
ExecStart=/usr/bin/node dist/server.js
EnvironmentFile=/etc/gr8hopper/.env
Environment=PORT=3000
Restart=on-failure

[Install]
WantedBy=multi-user.target

This setup requires securing the environment file with appropriate permissions (chmod 600).

Sources: README.md:280-296

Summary

Deploying gr8hopper with Node.js or Bun provides a flexible, self-hosted solution for running the redirect service on a VPS. The architecture is simple, relying on a Hono-based server, a single JSON file for state, and environment variables for all configuration. The provided Docker, systemd, and direct execution methods offer multiple pathways for production deployment, with security best practices like using a reverse proxy and strong credentials being paramount.

Sources: src/server.ts, README.md