TK4-Hercules

A Docker containerized IBM MVS 3.8j mainframe emulator featuring the TK4- system for educational mainframe computing and historical preservation.

Quick Start

Quick Start (TK4-)

# Start TK4-
make start

Using GitHub Container Registry (Recommended)

# Pull and run TK4-
docker run -d \
  --name tk4-hercules \
  -p 3270:3270 \
  -p 8038:8038 \
  ghcr.io/skunklabz/tk4-hercules:latest

Connect to the Mainframe

# Connect via telnet (3270 terminal)
telnet localhost 3270

# Or access the web console
open http://localhost:8038

Architecture Support

This project is optimized for AMD64/x86_64 architecture. For ARM64 systems, the emulator will run through emulation with potentially reduced performance.

# Force AMD64 platform for ARM64 systems
PLATFORM=linux/amd64 docker compose up -d

# Or set environment variable
export PLATFORM=linux/amd64
make start

About TK4-

Features

• IBM MVS 3.8j: Complete mainframe operating system from 1981
• Hercules Emulator: Industry-standard mainframe emulation
• 3270 Terminal Support: Authentic mainframe terminal experience
• Web Console: Modern web interface for system monitoring
• Educational Tools: Pre-loaded with learning materials and examples
• Persistent Storage: 8 volumes for TK4-

System Specifications

• OS: IBM MVS 3.8j Service Level 8505
• Emulator: Hercules 4.4.1 (TK4-)
• Base Image: Ubuntu 22.04
• Architecture: Multi-platform (x86_64, ARM64) (emulating System/370)
• Memory: Configurable (default: 1-2GB)
• Storage: 8 volumes (TK4-)

Available Images

GitHub Container Registry (GHCR)

• TK4- Latest: ghcr.io/skunklabz/tk4-hercules:latest

Development

Prerequisites

• Docker and Docker Compose
• Git
• Make (optional, for convenience commands)

Building Locally

# Clone the repository
git clone https://github.com/skunklabz/tk4-hercules.git
cd tk4-hercules

# Build the image
make build

# Start the container
make start

ARM64 Support

TK4-Hercules now supports ARM64 architecture, including Apple Silicon Macs and ARM-based servers. The image automatically detects your platform and uses the appropriate Hercules binary.

Note: ARM64 support currently uses x86_64 emulation due to limitations in the TK4- distribution. Native ARM64 binaries are planned for future releases.

# Build multi-platform images (AMD64 + ARM64)
make build-multi

# Test ARM64 support
make test-arm64

# Build for your current platform
make build-platform

For detailed ARM64 documentation, see docs/ARM64_SUPPORT.md.

Git Hooks (Quality Assurance)

This repository includes Git hooks to ensure code quality before pushing:

Pre-Push Hook (Default)

Automatically runs before each git push:

• Quick validation checks
• Exercise content validation
• Docker build test

Enable: Already enabled by default

Comprehensive Pre-Push Hook (Optional)

Runs full test suite including container startup and connectivity tests:

# Enable comprehensive pre-push checks
ln -sf .git/hooks/pre-push-comprehensive .git/hooks/pre-push

# Disable (back to default)
ln -sf .git/hooks/pre-push .git/hooks/pre-push

Note: Comprehensive tests take 2-3 minutes but catch more issues before they reach CI.

Automated Releases

The project uses automated releases triggered by pushes to the main branch:

• Push to main: Automatically creates a new release
• Version bump: Patch version is incremented (1.1.0 → 1.1.1)
• Docker build: Multi-platform image is built and pushed to GHCR
• GitHub release: Release is created with changelog notes

For major or minor version bumps, use the manual workflow in GitHub Actions.

Development Commands

# Build and push to GHCR
make push-ghcr

# Run tests
make test

# Clean up
make clean

# Show all available commands
make help

Documentation

• Learning Guide: Educational content and tutorials
• Registry Setup: GitHub Container Registry configuration
• Testing Guide: Testing procedures and validation
• Project Structure: Repository organization
• Contributing: How to contribute to the project

Examples and Exercises

The examples/ directory contains educational materials:

• Getting Started: First steps with the mainframe
• File Systems: Understanding MVS file systems
• JCL Jobs: Job Control Language examples
• Challenges: Advanced exercises and projects

Ports and Services

• 3270: Mainframe terminal protocol (telnet)
• 8038: Web console interface (HTTP)

Volume Mounts

The container uses 8 persistent volume mounts:

• /tk4-/conf: Master configuration
• /tk4-/local_conf: Initialization scripts
• /tk4-/local_scripts: User modifications
• /tk4-/prt: Line printer output
• /tk4-/pch: Card punch output
• /tk4-/dasd: Disk volumes
• /tk4-/jcl: Job control files
• /tk4-/log: System logs

Security

• Non-root user execution (where possible)
• Resource limits for CPU and memory
• Security options enabled
• Regular base image updates

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/ directory

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• TK4-: The original Turnkey 4- system by Jürgen Winkelmann
• Hercules: The mainframe emulator by Jay Maynard and contributors
• IBM: For the original MVS 3.8j operating system
• Mainframe Community: For preserving and sharing mainframe knowledge

Version History

See CHANGELOG.md for detailed version history and changes.

---

Note: This is an educational project for learning mainframe computing concepts. The MVS 3.8j system is a historical artifact and should be used for educational purposes only.