ue4-docker

Building Images

Advanced build options

Contents

General options

Performing a dry run

If you would like to see what docker build commands will be run without actually building anything, you can specify the --dry-run flag when invoking the ue4-docker build command. Execution will proceed as normal, but no Git credentials will be requested and all docker build commands will be printed to standard output instead of being executed as child processes.

Specifying a custom namespace for the image tags

If you would like to override the default adamrehn/ prefix that is used when generating the tags for all built images, you can do so by specifying a custom value using the UE4DOCKER_TAG_NAMESPACE environment variable. Note that this setting does not effect the ue4-build-prerequisites image, which always retains its default name in order to maintain compatibility with the prebuilt version from Docker Hub.

Specifying Git credentials

The ue4-docker build command supports three methods for specifying the credentials that will be used to clone the UE4 Git repository:

  • Command-line arguments: the -username and -password command-line arguments can be used to specify the username and password, respectively.

  • Environment variables: the UE4DOCKER_USERNAME and UE4DOCKER_PASSWORD environment variables can be used to specify the username and password, respectively. Note that credentials specified via command-line arguments will take precedence over values defined in environment variables.

  • Standard input: if either the username or password has not been specified via a command-line argument or environment variable then the build command will prompt the user to enter the credential(s) for which values have not already been specified.

Note that the username and password are handled independently, which means you can use different methods to specify the two credentials (e.g. username specified via command-line argument and password supplied via standard input.)

Users who have enabled Two-Factor Authentication (2FA) for their GitHub account will need to generate a personal access token and use that in place of their password.

Building a custom version of the Unreal Engine

If you would like to build a custom version of UE4 rather than one of the official releases from Epic, you can specify “custom” as the release string and specify the Git repository and branch/tag that should be cloned. When building a custom Engine version, both the repository URL and branch/tag must be specified:

ue4-docker build custom -repo=https://github.com/MyUser/UnrealEngine.git -branch=MyBranch

This will produce images tagged adamrehn/ue4-source:custom, adamrehn/ue4-engine:custom, etc.

If you are performing multiple custom builds and wish to differentiate between them, it is recommended to also specify a name for the custom build:

ue4-docker build custom:my-custom-build -repo=https://github.com/MyUser/UnrealEngine.git -branch=MyBranch

This will produce images tagged adamrehn/ue4-source:my-custom-build, adamrehn/ue4-engine:my-custom-build, etc.

Pulling a prebuilt version of the ue4-build-prerequisites image

If you would like to pull the prebuilt version of the ue4-build-prerequisites image from Docker Hub instead of building it locally, simply specify the --pull-prerequisites flag when invoking the ue4-docker build command. This is primarily useful when building images under versions of Windows Server Core prior to Windows Server 2019, since using the prebuilt image allows you to avoid copying the required DLL files from Windows 10. Note however that prebuilt versions of the image are available only for LTSC versions of Windows, not for SAC versions.

Excluding Engine components to reduce the final image size

Starting in ue4-docker version 0.0.30, you can use the --exclude flag when running the ue4-docker build command to specify that certain Engine components should be excluded from the ue4-minimal and ue4-full images. The following components can be excluded:

  • ddc: disables building the DDC for the Engine. This significantly speeds up building the Engine itself but results in far longer cook times when subsequently packaging Unreal projects.

  • debug: removes all debug symbols from the built images. (When building Windows containers the files are actually truncated instead of removed, so they still exist but have a size of zero bytes. This is done for compatibility reasons.)

  • templates: removes the template projects and samples that ship with the Engine.

You can specify the --exclude flag multiple times to exclude as many components as you like. For example:

# Excludes both debug symbols and template projects
ue4-docker build 4.21.2 --exclude debug --exclude templates

Enabling system resource monitoring during builds

Starting in ue4-docker version 0.0.46, you can use the --monitor flag to enable a background thread that will log information about system resource usage (available disk space and memory, CPU usage, etc.) at intervals during the build. You can also use the -interval flag to override the default interval of 20 seconds:

# Logs system resource levels every 20 seconds
ue4-docker build 4.24.2 --monitor

# Logs system resource levels every 5 seconds
ue4-docker build 4.24.2 --monitor -interval=5

Windows-specific options

Specifying the Windows Server Core base image tag

The -basetag flag controls how the ue4-build-prerequisites image is built and tagged, which has a flow-on effect to all of the other images. If you are building multiple related images over separate invocations of the build command (e.g. building the ue4-source image in one command and then subsequently building the ue4-minimal image in another command), be sure to specify the same -basetag flag each time to avoid unintentionally building two sets of unrelated images with different configurations.

By default, Windows container images are based on the Windows Server Core release that best matches the version of the host operating system. However, Windows containers cannot run a newer kernel version than that of the host operating system, rendering the latest images unusable under older versions of Windows 10 and Windows Server. (See the Windows Container Version Compatibility page for a table detailing which configurations are supported.)

If you are building images with the intention of subsequently running them under an older version of Windows 10 or Windows Server, you will need to build images based on the same kernel version as the target system (or older.) The kernel version can be specified by providing the appropriate base OS image tag via the -basetag=TAG flag when invoking the build command:

ue4-docker build 4.19.2 -basetag=ltsc2016  # Uses Windows Server 2016 (Long Term Support Channel)

For a list of supported base image tags, see the Windows Server Core base image on Docker Hub.

Specifying the isolation mode under Windows

The isolation mode can be explicitly specified via the -isolation=MODE flag when invoking the build command. Valid values are process (supported under Windows Server and Windows 10 version 1809 or newer) or hyperv (supported under both Windows 10 and Windows Server.) If you do not explicitly specify an isolation mode then the appropriate default for the host system will be used.

Specifying the directory from which to copy required Windows DLL files

By default, DLL files are copied from %SystemRoot%\System32. However, when building container images with an older kernel version than the host, the copied DLL files will be too new and the container OS will refuse to load them. A custom directory containing the correct DLL files for the container kernel version can be specified via the -dlldir=DIR flag when invoking the build command.

Keeping or excluding Installed Build debug symbols under Windows

Excluding debug symbols is necessary under some versions of Docker as a workaround for a bug that limits the amount of data that a COPY directive can process to 8GB. See this section of the Troubleshooting Build Issues page for further details on this issue.

Prior to version 0.0.30, ue4-docker defaulted to truncating all .pdb files when building the Installed Build for the ue4-minimal Windows image. This was done primarily to address the bug described in the warning alert above, and also had the benefit of reducing the overall size of the built container images. However, if you required the debug symbols for producing debuggable builds, you had to opt to retain all .pdb files by specifying the --keep-debug flag when invoking the build command. (This flag was removed in ue4-docker version 0.0.30, when the default behaviour was changed and replaced with a more generic, cross-platform approach.)

Since ue4-docker version 0.0.30, debug symbols are kept intact by default, and can be removed by using the --exclude debug flag as described in the section Excluding Engine components to reduce the final image size.

Building Linux container images under Windows

By default, Windows container images are built when running the build command under Windows. To build Linux container images instead, simply specify the --linux flag when invoking the build command.

Linux-specific options

Enabling CUDA support for GPU-enabled Linux images

The --cuda flag controls how the ue4-build-prerequisites image is built and tagged, which has a flow-on effect to all of the other images. If you are building multiple related images over separate invocations of the build command (e.g. building the ue4-source image in one command and then subsequently building the ue4-minimal image in another command), be sure to specify the same --cuda flag each time to avoid unintentionally building two sets of unrelated images with different configurations.

By default, the Linux images built by ue4-docker support hardware-accelerated OpenGL when run via the NVIDIA Container Toolkit. If you would like CUDA support in addition to OpenGL support, simply specify the --cuda flag when invoking the build command.

You can also control the version of the CUDA base image that is used by appending a version number when specifying the --cuda flag, as demonstrated below:

# Uses the default CUDA base image (currently CUDA 9.2)
ue4-docker build RELEASE --cuda

# Uses the CUDA 10.0 base image
ue4-docker build RELEASE --cuda=10.0

For a list of supported CUDA versions, see the list of Ubuntu 18.04 image tags for the nvidia/cudagl base image.