Building and Using Docker Images¶

The previous version of this document focused on Ubuntu 22.04 images. It can be found here.

• Building and Using Docker Images
  • Base Images
    • Under the Hood
      • base_ubuntu_24.04
      • basedev_ubuntu_24.04
      • base_ubuntu_24.04_pg14 through base_ubuntu_24.04_pg17
      • basedev_ubuntu_24.04_pg14 through basedev_ubuntu_24.04_pg17
    • Base Image Creation
  • FWD Images
    • Under the Hood
      • Dockerfile details
    • FWD Image Creation
      • Examples
  • dbash.sh - Docker bash
    • Special Cases for dbash.sh

This document outlines how to create and use the current Ubuntu 24.04 Docker images for FWD. The container project contains the tooling for the base images, while the FWD project contains tools/docker/docker_build.sh for packaging FWD distributions into runtime and development images.

The only Docker configuration required beyond the defaults is that buildkit should be enabled in /etc/docker/daemon.json:

{
  "features": {
    "buildkit": true
  }
}

If you make that change, restart the Docker daemon: sudo systemctl restart docker.service

To get the container project:

bzr co sftp://<user>@xfer.goldencode.com/opt/fwd/container/
cd container/

Base Images¶

• base_ubuntu_24.04

• basedev_ubuntu_24.04 extends it with the development toolchain.
• PostgreSQL variants extend it with full PostgreSQL server and client support:
  • base_ubuntu_24.04_pg14
  • base_ubuntu_24.04_pg15
  • base_ubuntu_24.04_pg16
  • base_ubuntu_24.04_pg17

• basedev_ubuntu_24.04_pg14
• basedev_ubuntu_24.04_pg15
• basedev_ubuntu_24.04_pg16
• basedev_ubuntu_24.04_pg17

The plain base images do not install PostgreSQL. The PostgreSQL variants install the full PostgreSQL server and client for the selected version.

  build_base_ubuntu_24.04.sh
  └── ubuntu:24.04
      ├── base_ubuntu_24.04
      │   ├── base_ubuntu_24.04_pg14
      │   ├── base_ubuntu_24.04_pg15
      │   ├── base_ubuntu_24.04_pg16
      │   └── base_ubuntu_24.04_pg17
      └── basedev_ubuntu_24.04
          ├── basedev_ubuntu_24.04_pg14
          ├── basedev_ubuntu_24.04_pg15
          ├── basedev_ubuntu_24.04_pg16
          └── basedev_ubuntu_24.04_pg17

The steps for creating these images are outlined in the Base Image Creation section below.

Under the Hood¶

This section summarizes the major contents of the current base Dockerfiles.

base_ubuntu_24.04¶

The root image is:

FROM ubuntu:24.04

• Locale support is installed and custom FWD locales are copied in and generated.
• Timezone defaults to America/New_York but can be overridden.
• OpenSSH is installed with tighter default security settings.
• JDK 17, 21 and 25 are installed, and switch-java.sh selects the default using JDK_VERSION.
• Runtime support files such as ncurses/terminfo patching, entrypoint handling, and service-account setup are included.
• show_image_version.sh is installed in /usr/local/bin/.
• Version metadata is copied to /etc/version.properties and installed with mode 0644.

The image metadata file can be viewed inside the container with:

/usr/local/bin/show_image_version.sh

basedev_ubuntu_24.04¶

• compiler and build utilities
• Breezy/Bazaar client tooling
• Paramiko
• networking and diagnostic packages
• the same JDK set inherited from the base image

base_ubuntu_24.04_pg14 through base_ubuntu_24.04_pg17¶

• postgresql-${PG_VERSION}
• postgresql-client-${PG_VERSION}

In other words, these are full PostgreSQL server images, not client-only images.

basedev_ubuntu_24.04_pg14 through basedev_ubuntu_24.04_pg17¶

These images are also built with base_ubuntu_24.04_pg_Dockerfile, but with FROM_IMAGE set to basedev_ubuntu_24.04. They combine the development toolchain with full PostgreSQL server support for the selected version.

Base Image Creation¶

The build_base_ubuntu_24.04.sh script creates the Ubuntu 24.04 base image family:

Usage: ./build_base_ubuntu_24.04.sh [-qpdl] [-i <image>] [-c<context_dir>] [-f<fwd_dir>] [-n<ncurses_path>] [-t<image_tag>] [--target_repo=<target_repo>] [--from_repo=<from_repo>] [--jdk_version_def=<jdk_default>] [--language=<language>] [--encoding=<encoding>] [--tzdata_area=<area>] [--tzdata_zone=<zone>] [--code_url=<code_url>] [--base_tools=<base_tools>] [--dev_tools=<dev_tools>] [--fwd_uid=<fwd_uid>] [--fwd_gid=<fwd_gid>] [--pg_uid=<pg_uid>] [--pg_gid=<pg_gid>] [--runtime] [--progress_plain] [--bzrrepo] [--sshkey=<keypath>] [--no_cache]

Build the base 24.04 Ubuntu images with/without PostgreSQL support, JDK 17, 21 and 25 support and optionally push.

Option Details
q Suppress image builds. This is mainly useful when you only want to retag or push existing images.
-p Push images to the repository.
-d Dry-run mode. Commands are displayed but not executed.
-l If a nonlatest tag is passed with -t, also create the latest tags.
-c Override the context directory.
-f Point to an FWD checkout for copying locale files and helper scripts into the context.
-n Override the setup_ncurses6x.sh source path.
-t Use a specific image tag instead of latest.
--target_repo Repository to push to instead of goldencode.
--from_repo Repository to pull parent images from. Use . for local images.
--jdk_version_def Select the default JDK for the created image family. The installed JDK set remains 17, 21 and 25.
--language / --encoding Override the default locale.
--tzdata_area / --tzdata_zone Override the default timezone.
--base_tools Override the runtime/base package list.
--dev_tools Override the development package list.
--fwd_uid / --fwd_gid Override the fwd account numeric IDs.
--pg_uid / --pg_gid Override the PostgreSQL account numeric IDs.
--runtime Build only the runtime-oriented image family and skip the development image family.
--progress_plain Use plain Docker build progress output.
--bzrrepo Force rebuild of Bazaar repository layers.
--sshkey SSH key used for repository access where needed.
--no_cache Disable Docker layer cache usage.

During the build, the script generates a version.properties file per image build and places it in the Docker context. The resulting image stores this metadata at /etc/version.properties and exposes it via /usr/local/bin/show_image_version.sh.

A simple example:

./build_base_ubuntu_24.04.sh -f ~/projects/fwd/p2j

FWD Images¶

FWD images are created by tools/docker/docker_build.sh from a built FWD distribution. This is the backend packaging step that layers the FWD deploy artifacts onto the Ubuntu 24.04 base images.

• a plain client runtime image and a plain runtime/server image from base_ubuntu_24.04
• client runtime images that install only the PostgreSQL client for the requested version(s)
• full PostgreSQL runtime images from base_ubuntu_24.04_pg14 through base_ubuntu_24.04_pg17
• optional development images from basedev_ubuntu_24.04 and basedev_ubuntu_24.04_pg14 through basedev_ubuntu_24.04_pg17

The relationships are:

  tools/docker/docker_build.sh
  ├── from base_ubuntu_24.04
  │   ├── fwd_4.0_ubuntu_24.04_client_jdk17
  │   ├── fwd_4.0_ubuntu_24.04_jdk17
  │   ├── fwd_4.0_ubuntu_24.04_client_pg14_jdk17
  │   ├── fwd_4.0_ubuntu_24.04_client_pg15_jdk17
  │   ├── fwd_4.0_ubuntu_24.04_client_pg16_jdk17
  │   └── fwd_4.0_ubuntu_24.04_client_pg17_jdk17
  ├── from basedev_ubuntu_24.04
  │   └── fwddev_4.0_ubuntu_24.04_jdk17
  ├── from base_ubuntu_24.04_pg14
  │   └── fwd_4.0_ubuntu_24.04_pg14_jdk17
  ├── from basedev_ubuntu_24.04_pg14
  │   └── fwddev_4.0_ubuntu_24.04_pg14_jdk17
  ├── from base_ubuntu_24.04_pg15
  │   └── fwd_4.0_ubuntu_24.04_pg15_jdk17
  ├── from basedev_ubuntu_24.04_pg15
  │   └── fwddev_4.0_ubuntu_24.04_pg15_jdk17
  ├── from base_ubuntu_24.04_pg16
  │   └── fwd_4.0_ubuntu_24.04_pg16_jdk17
  ├── from basedev_ubuntu_24.04_pg16
  │   └── fwddev_4.0_ubuntu_24.04_pg16_jdk17
  ├── from base_ubuntu_24.04_pg17
  │   └── fwd_4.0_ubuntu_24.04_pg17_jdk17
  └── from basedev_ubuntu_24.04_pg17
      └── fwddev_4.0_ubuntu_24.04_pg17_jdk17

The actual JDK suffix is derived from the built distribution and can currently be jdk17, jdk21 or jdk25.

• client runtime images from base_ubuntu_24.04 with only the PostgreSQL client added
• full PostgreSQL runtime images from the matching base_ubuntu_24.04_pg* images
• matching development images if --build-dev is also specified

Under the Hood¶

This section summarizes the important behaviors of tools/docker/fwd_4.0_ubuntu_Dockerfile.

Dockerfile details¶

BASE_UBUNTU build-arg
This identifies the base image to layer on top of. It defaults to base_ubuntu_24.04.

ARG BASE_UBUNTU=base_ubuntu_24.04
FROM ${BASE_UBUNTU}

FWD_DIR build-arg
The built FWD distribution files are copied from this directory within the Docker context.

ARG FWD_DIR

DEPLOY_LIST build-arg
This controls which FWD deployable parts are installed into /opt/fwd-deploy.

ARG DEPLOY_LIST=all

Optional PostgreSQL client install
The runtime client images use INSTALL_PG_CLIENT=true and PG_VERSION=<version> so only the client package is added on top of base_ubuntu_24.04.

ARG INSTALL_PG_CLIENT=false
ARG PG_VERSION=17

DEPLOY_TYPE build-arg
This controls which deployed subtree is linked to /opt/fwd. For example, client-only runtime images set:

--build-arg DEPLOY_TYPE=client

Deploying the FWD artifacts
The build copies the distribution files into a temporary repo location and runs deploy_fwd.sh to install them under /opt/fwd-deploy.

FWD_LIB link
The image creates /opt/fwd as a symbolic link to the selected deploy type under /opt/fwd-deploy/.

FWD Image Creation¶

The tools/docker/docker_build.sh script is the current tool for building the Ubuntu 24.04 FWD image family from an existing FWD distribution:

Usage: ./docker/docker_build.sh [-d <dist>] [-pt] [--latest] [--build-dev] [--target_repo=<target_repo>] [--from_repo=<from_repo>] [--from_tag=<from_tag>] [--pg=<14|15|16|17|all|comma-list>] [--progress_plain] [--no_cache]

Build the FWD Docker runtime images from the dist images. Tag appropriately, and optionally push.

Option Details
-d <dist> Path to the distribution ZIP files. By default this is ../dist relative to the FWD checkout.
-p Push images to the repository.
-t Dry-run mode. Commands are displayed but not executed.
--latest Also tag the generated image family as latest or <branch>_latest.
--build-dev Add development image builds. Runtime images are always built; this option is additive.
--target_repo Repository to push to instead of goldencode.
--from_repo Repository from which to pull base images. Use . for local images.
--from_tag Select the tag of the parent base images. The default is latest.
--pg Build PostgreSQL-related images for one or more versions. This may be a single version, a comma-separated list, or all.
--progress_plain Use plain Docker build progress output.
--no_cache Disable Docker layer cache usage.

The script determines the FWD branch, revision and JDK level from the distribution ZIP files and version.properties. It then tags the generated images using <branch>_<revision>, with optional latest or <branch>_latest aliases.

Examples¶

To build the plain non-PostgreSQL image family locally from the current distribution:

./docker/docker_build.sh

To build runtime and development images for all supported PostgreSQL versions:

./docker/docker_build.sh --build-dev --pg=all

To build against base images in the goldencode repository:

./docker/docker_build.sh --from_repo=goldencode

To tag the resulting image family as latest as well:

./docker/docker_build.sh --latest

dbash.sh - Docker bash¶

Some helpful scripts that are part of the GCD base image, as well included in the mgmt project, are dbash.sh and fbash.sh. They can be downloaded from in the gcd_systems and mgmt projects.

It will create a development environment which has all of the necessary utilities to access the Bazaar resources and build the application. Show UsageHide Usage

Usage: /home/rfb/usrbin/dbash.sh [-dlwf] [-v <volume>] [--port-gui] [--port-debug] [--port-jmx] [--port-pg=<port>] [--tag=<tag>] [--pg<14|15|16|17>] [--pgport=<port>] [--host] [--manual_port=<hport:cport>[,<hport:cport>...]] [--manual_mount=<ext_vol:int_vol>[,<ext_vol:int_vol>...]] [--startup_hook=<startup_file>] [--jdk<21|25>] [--detach] [--app=<appdir>] [--fwd_lib=<fwd_lib>] [-c <cmd_line>]

Create a container based off the "basedev_ubuntu_24.04" Docker image

Where:
       -d = dryrun (just display commands)
       -l = local image. Don't use goldencode/ repository.
       -w = Use fwd account instead of mapping in rfb account.
       -f = Include FWD in the container. Specify a tag with --tag=<tag>, if desired. (default=latest).
       -v = Volume for database to mount to /opt/db (if PostgreSQL included).
       --port-gui = Open typical GUI ports (7443 and 7449-7459)
       --port-debug = Open typical debug ports (2080 and 5000)
       --port-jmx = Open JMX 22100 port
       --port-pg=<port> = Open <port> (usually 5432) to the PGPORT (override container port 5432 with --pgport=<port>)
       --tag=<tag> = Use given tag for FWD included in the image (default=latest).
       --pg<14|15|16|17> = Include given PostgreSQL in the container. The default is no PostgreSQL.
       --pgport=<port> Use this port for PostgreSQL. The default is 5432. It will export PGPORT=<port>.
       --pgdata=<pgdata> Startup PostgreSQL using this cluster. It will export PGDATA=/opt/db/<pgdata>
       --host = Use host's network.
       --manual_port=<hport:cport>[,<hport:cport>...] include one or more port openings with "-p hport:cport".
       --manual_mount=<ext_vol:int_vol>[,<ext_vol:int_vol>...] include one or more mountpoints with "-v ext_vol:int_vol" 
       --startup_hook=<startup_file> the base_entrypoint.sh will hook <startup_file> for an installation instead of the default "./docker/startup_hook.sh"" 
       --jdk<21|25> = Use given JDK as the default for the container. The default is JDK17.
       --app=<appdir> = Set /opt/app directory in container to give <appdir> directory on host, typically the deploy directory.
       --fwd_lib=<fwd_lib> = Set FWD_LIB environment variable to <fwd_lib> path. This allows scripts to find FWD.
       --detach = Run the container detached. Use "docker attach ..." to attach and "CTRL-p CTRL-q" to detach again.
       -c <cmd_line> = Pass a command line to the Docker container.

 -? or -h or --help = show usage.

Typical usage is dbash.sh -f or more simply fbash.sh, which utilizes the FWD Docker development image tagged latest. This opens a bash shell and maps the current user information into the container so that you should have access to files in your homespace.

You can also pass command lines into the container for execution and have it exit when the command completes. For example, to determine the configured FWD version:
fbash.sh -c "java -jar /opt/fwd/build/lib/p2j.jar"

Special Cases for dbash.sh¶

There may be situations where additional ports need to be opened up or additional volumes mapped from the bash shell that dbash.sh creates. The basic docker run command created with fbash.sh is:

docker run -e DBASH=true --name fwddev_40_ubuntu_2404_jdk17_latest_container -h fwddev_40_ubuntu_2404_jdk17_latest_container --user root --rm -it -v $HOME:$HOME -v /etc/passwd:/etc/passwd:ro -v /etc/group:/etc/group:ro -v /etc/shadow:/etc/shadow:ro -v /etc/sudoers:/etc/sudoers:ro --pull always -e JDK_VERSION=17 -e HOST_UID=$(id -u) -e HOST_GID=$(id -g) -e HOME=$HOME -e USER=$USER -w $PWD goldencode/fwddev_4.0_ubuntu_24.04_jdk17:latest $USER -- bash

You can always display the generated docker run command by including -d so that a dry-run is performed and the command is displayed instead of executed.

• The -v <host_directory>:<container_directory> option allows the <host_directory> to be available as <container_directory> inside the started container. For example, -v /mnt/wsl/winshare:${HOME}/secure would make ~/secure available inside the container.
• The -p <host_port>:<container_port> option allows for opening ports so that the container's port <container_port> is available as <host_port>. For example: -p 9443:9443 would allow the container's port 9443 to be available to the host as port 9443. Be cautious when exposing ports on an Internet-reachable environment.

These are just examples. Any valid use of docker run against goldencode/fwddev_4.0_ubuntu_24.04_jdk17:latest or related Docker images is fine. The dbash.sh script is simply for usability.

© 2023-2026 Golden Code Development Corporation. ALL RIGHTS RESERVED.