Running HERCULES 4.X Hyperion in a Docker Container

… when two worlds come together

Hercules is actively developed under the project Hercules Hyperion, and the current release, 4.5 is available on GitHub. I tried to compile it on my macOS but had some trouble with the software not being available, so I decided to give Docker a chance and carry this cute little Dinosaur. And it was actually relatively easy. (Attention: This approach is only tested on x86 architectures. I tried a build on a Raspberry Pi 4 with 64Bit, and it failed due to missing external libraries. I’m working on it)

First, I cloned the GitHub repository on a local directory.

git clone https://github.com/SDL-Hercules-390/hyperion.git

Then, you will have the whole project on your local drive. The installation instructions in the project documentation are straightforward, so I followed them up in a Dockerfile. (Copy this Dockerfile into the project directory.)

#
# Start building hercules-hyperion docker image from a debian base
# since it does not need many stuff the slim image should be sufficient
#
# The extra software is installed with apt.
#
FROM debian:stable-slim AS env

RUN mkdir /opt/build &&\
    apt-get update &&\
    apt-get -y install git wget time &&\
    apt-get -y install build-essential cmake flex gawk m4 autoconf automake libtool-bin libltdl-dev &&\
    apt-get -y install libbz2-dev zlib1g-dev &&\
    apt-get -y install libcap2-bin

# No the environment is set and the build can Start
# copy all the project files into the build directory and Start
# building it.
#
FROM env AS build

WORKDIR /opt/build

COPY . /opt/build

RUN ./configure &&\
    mkdir /opt/hercules &&\
    make &&\
    make install &&\
    /sbin/ldconfig -v

#
# With the hercules hyperion build it is no easy to Start
# hercules.
#
# The docker image expects a working area mounted to /opt/hercules
# and in that directory there must be the configuratio under conf/herculues.cnf
# The start script inside the hercules console has to be under scripts/ipl.rc
#
#  <DirecotryMountedUnder/opt/hercules>
#   .
#   +--conf/hercules.cnf
#   +--scripts/ipl.rc
#
FROM build AS hercules-hyperion
WORKDIR /opt/build
VOlUME /opt/hercules

CMD ["/bin/bash", "/opt/build/container-start"]

The Dockerfile has three stages. The first stage starts from the Debian-slim image and follows the installation instructions of the project documentation. It leaves a stage env to use in the next stage.

The stage build copies the entire project into the working directory of the image and follows the make instructions of the project documentation. This leads to a new stage build with a compiled and installed Hercules inside. I only needed to add the /sbin/ldconfig -v command to make the Hercules libraries accessible in the image.

The third stage is the final one, which builds the final image and makes Hercules run in a docker container. It uses a little bash script:

#!/bin/bash

(
cd /opt/hercules
export HERCULES_RC=scripts/ipl.rc
hercules -f conf/hercules.cnf -d >3033.log
)

The script changes to a directory /opt/Hercules sets the environment variable HERCULES_RC to scripts/ipl.rc, and starts the Hercules emulator. As you can see, this script implies some setups from the user. You have to mount a directory with your own Hercules environment under /opt/Hercules, and in that environment, you have to store the configuration under conf/Hercules.cnf and the startup script under scripts/ipl.rc

Starting Hercules is one thing. But installing the software and bringing it all together is a much more difficult task. At least for me as a Java developer. There are some readily defined distributions with all devices, dasds, configs, and start scripts needed available, and you surely want to use them. Like the TK-4 distribution mentioned in the other articles. This distribution has the configuration under conf/tk4-.cnf. Copy it to conf/Hercules.cnf and you are fine. The start script is under scripts/ipl.rc as the container script requires.

docker build -t hercules-hyperion .

When you start the docker build like:

Docker will create the image. To start the image, use this command:

docker run -v /<YOUR HERCULES ENVIRONMENT DIRECTORY>:/opt/hercules \
    -p 3270:3270 \
    -p 3278:3278 \
    -p 8038:8038 \
    --name hercules \
    hercules-hyperion

Now you have a running Hercules 4.5 Hyperion instance in docker. The ports are exposed to 3270 (3270-Terminal emulation), 3278 (Telnet port), and 8038 (Web-Server)