Hercules Terminal Web App

Main interface overview

Why?

Years ago I added JSON APIs to hercules. The end goal of which was to ultimately replace/enhance the current hercules web interface.

Features

• Themes! Change the look of the interface
• Implements almost all the original hercules web server features
• Supports live updates, such as CPU usage, PSW, etc
• New hercules console that auto refreshes
• View device configuration with filterable results
• Interactive system 370 panel
• Built in TN3270 emulator!

Demo

Interactive demo of the Hercules web interface

Note

This is a [mostly] AI generated application.

To Test: Quick Start (Using Python Proxy)

1. Open a terminal in this directory
2. Run the proxy server:

   ./proxy-server.py --host 192.168.0.102

   Or with authentication:

   ./proxy-server.py --host 192.168.0.102 --username docker --password docker

3. Open your browser to: http://localhost:3000/

That's it! You should see the terminal with live syslog updates. The TN3270 terminal will also be available automatically.

Note: The following URLs all serve the same interface:

• http://localhost:3000/
• http://localhost:3000/hercconsole.html
• http://localhost:3000/server/hercconsole

TN3270 Terminal

The included TN3270 terminal emulator requires a WebSocket proxy (browsers cannot make direct TCP connections). The included proxy-server.py automatically provides this proxy.

Using the included proxy (recommended):

./proxy-server.py --host 10.10.10.10

The proxy server will automatically:

• Start HTTP proxy on port 3000 (configurable with --port)
• Start WebSocket proxy on port 3271 (configurable with --ws-port)
• Proxy TN3270 connections to port 3270 on the Hercules host (configurable with --tn3270-port)

Advanced proxy options:

# Custom ports
./proxy-server.py --host 10.10.10.10 --hercules-port 8888 --tn3270-port 3270 --ws-port 3271

# Separate TN3270 host
./proxy-server.py --host 10.10.10.10 --tn3270-host mainframe.local --tn3270-port 3270

Using Docker (websockify) alternative:

docker run -d -p 3271:3271 solsson/websockify 3271 10.10.10.10:3270

Connecting from the browser:

1. Click the "Terminal" tab
2. Enter WebSocket proxy host (e.g., localhost) and port (e.g., 3271)
3. Select terminal model and click "Connect"

Environment Variables: The proxy server supports configuration via environment variables:

• HERC_HOST - Hercules server hostname
• HERC_PORT - Hercules API port (default: 8888)
• HERC_USERNAME - Hercules API username
• HERC_PASSWORD - Hercules API password
• HERC_TN3270_HOST - TN3270 server hostname (defaults to HERC_HOST)
• HERC_TN3270_PORT - TN3270 telnet port (default: 3270)
• HERC_API_PATH - API path (default: /cgi-bin/api/v1)
• PROXY_PORT - Local HTTP proxy port (default: 3000)
• WS_HOST - WebSocket bind address (default: 0.0.0.0)
• WS_PORT - WebSocket port (default: 3271)

Run ./proxy-server.py --help for complete details.

INSTALL: Serve from Hercules Directly

You can serve the HercOnline interface directly from your Hercules web server instead of using the proxy server.

Step 1: Copy Files to Hercules

Copy the application files to the hercules share folder. This folder depends on how you built and run hercules:

• Hercules Helper: herc4x/share/hercules
• Hercules: /usr/share/hercules

# Copy main files
cp hercconsole.html hercconsole.css hercconsole.js /usr/share/hercules/
cp tn3270.js 3270-Regular.ttf /usr/share/hercules/

# Copy images
cp -r images /usr/share/hercules/

Note: Your Hercules server must send proper CORS headers for API calls to work.

Step 2: Set Up WebSocket Proxy for TN3270

Important: The TN3270 terminal emulator requires a WebSocket proxy to work. Web browsers cannot make direct TCP connections to the TN3270 telnet port (3270) for security reasons. You must run a WebSocket-to-TCP proxy that bridges browser connections to the Hercules TN3270 port.

The WebSocket proxy should run on the same host as Hercules (or be network-accessible to both your browser and Hercules).

Option 1: Using websockify (Recommended)

Install and run websockify on the Hercules host:

# Using pip
pip install websockify
websockify 0.0.0.0:3271 localhost:3270

# Or using Docker
docker run -d \
  --name tn3270-proxy \
  --network host \
  solsson/websockify \
  3271 localhost:3270

Option 2: Using the Python Proxy Script

If you have the proxy-server.py script on your Hercules host, you can use it for WebSocket proxying:

# Run on the Hercules host
./proxy-server.py --host localhost --ws-host 0.0.0.0 --ws-port 3271

This will start the WebSocket proxy on port 3271 without running the HTTP server.

Step 3: Access the Interface

1. Open your browser to your Hercules web server: http://10.10.10.10:8888/hercconsole.html
2. To use the TN3270 terminal:
   • Click the "Terminal" tab
   • Enter WebSocket proxy host (e.g., 10.10.10.10 or your Hercules hostname)
   • Enter WebSocket port (e.g., 3271)
   • Select terminal model and click "Connect"

Network Configuration:

• If accessing from the same machine: Use localhost:3271 for WebSocket
• If accessing remotely: Use the Hercules server IP/hostname (e.g., 10.10.10.10:3271)
• Ensure firewall allows access to port 3271

Features

• Live Updates: Syslog refreshes every 2 seconds
• Command Input: Send commands to Hercules console
• Terminal Style: Classic green-on-black terminal look
• Auto-scroll: Automatically shows latest messages
• TN3270 Terminal Emulator: Full-featured 3270 terminal with multiple models, color support, and mouse interaction (requires WebSocket proxy)

Screenshots

Console interface with live updates

Built-in TN3270 terminal emulator

Device management interface

Storage configuration

CPU registers and PSW monitoring

Theme customization options

Configuration options

About page