Categories: ADMIN GUIDE CLOUD

Creating your own Step Agent images

That page aims to guide through the process of creating your own Step Agent images. Currently, only Linux systems are supported, so below explanation / examples assumes your base Docker image is a Linux based one, such as Debian.

Requirements (Step Chart 1.2.0 and above)

If you would like to build a custom image to be used by your main container and so use it with the new Agent binary copy mode behaviour, below requirements has to be met:

  • Java 11 to Java 21 (preferably the JDK) must be downloaded and installed in the image
  • optionally, below packages could be installed in your images (see in below example):
    • xvfb and xauth, to simplify eventual headless Web Browser tests configuration
    • any other required package for your usage, in the apt-get install command line (such as chromium and chromium-driver for web browser testing)

For instance, a Dockerfile based on Debian 12 could look like: 

FROM debian:12-slim
RUN apt-get update && \
  apt-get -y install curl && \
  rm -rf /var/lib/apt/lists/*
ENV JAVA_HOME=/usr/java/jdk-21
RUN curl --output /tmp/jdk.tgz https://download.oracle.com/java/21/latest/jdk-21_linux-x64_bin.tar.gz && \
  mkdir -p "$JAVA_HOME" && \
  tar --extract --file /tmp/jdk.tgz --directory "$JAVA_HOME" --strip-components 1

Along with Step 27, Exense also provides a basic Agent runtime image containing Java 21 and NodeJS 20 (used as default Agent runtime image in the corresponding Helm Chart), as per below: 

docker.exense.ch/step-enterprise/base:21-debian-12-slim

Requirements (Step Chart 1.1.4 and below)

If you would like to build your own Step Agent images, below requirements have to be met:

  • Java 17 (preferably the JDK) must be downloaded and installed in the image
  • An “agent” user must exist, and its home directory to be “/home/agent”
  • optionally, below packages could be installed in your images (see in below example):
    • wget and unzip, to support downloading external dependencies at runtime
    • sudo, if the Agent needs to perform root impersonated operations
    • xvfb and xauth, to simplify eventual headless Web Browser tests configuration
    • any other required package for your usage, in the apt-get install command line (such as chromium and chromium-driver for web browser testing)

For instance, a Dockerfile based on Debian 12 could look like: 

FROM debian:12-slim
RUN apt-get update && \
  apt-get -y install unzip curl openjdk-17-jdk  && \
  rm -rf /var/lib/apt/lists/*
RUN useradd -s /bin/bash -m -U -u 1000 agent
USER agent
RUN cd /home/agent && curl -Lo step-agent.zip https://github.com/exense/step-distribution/releases/download/3.25.3/step-agent-3.25.3.zip && \
  unzip step-agent.zip -d /home/agent && rm -f step-agent.zip
RUN chmod +x /home/agent/bin/startAgent.sh
WORKDIR /home/agent/bin/
CMD  ./startAgent.sh

Docker build command

Assuming your Dockerfile name is “step-agent.dockerfile” and stored under the current repository, below command could be used to build the image:

docker build -f step-agent.dockerfile -t your.docker.repository/step-enterprise/agent:3.25.3-java-17 .

See Also