Use Cases:

Continuous Integration and Deployment (CI/CD)

Use reproducible environments to build and deploy Unreal Engine projects and plugins.

Here's what you'll need:

Contents

Overview

One of the most common uses of Unreal Engine containers is to provide reproducible environments within which automated builds of Unreal projects and plugins can be performed. These environments can be used with any existing CI system that supports Docker containers, allowing developers to utilise their preferred infrastructure and leverage existing CI/CD workflows. These workflows can also be extended to produce container images that can then be used to run packaged Unreal projects in the cloud, facilitating other use cases such as cloud rendering and building microservices powered by the Unreal Engine. The built container images can also be deployed and scaled with standard container orchestration technologies, allowing developers to comply with existing best practices for running containerised applications.

Key considerations

Implementation guidelines

Using the tools that ship with the Engine

Building and packaging

The primary method of building and packaging Unreal projects and plugins via the command-line is using commands provided by the Unreal Automation Tool (UAT):

These commands can be invoked by using the RunUAT helper script, which is located under the Engine/Build/BatchFiles subdirectory of the Unreal Engine installation root. The same commands that are used to package projects and plugins on a host system can be used to package projects and plugins within any Unreal Engine container that includes the Engine Tools.

Copying packaged files

Once a project or plugin has been built and packaged there are a number of available mechanisms that can be used to copy the packaged files to the desired location:

Running tests

Prior to Unreal Engine version 4.21, the only testing mechanism exposed via the command-line was the Automation System, which can be accessed via the automation console command, either by invoking the Editor directly or via the BuildCookRun command provided by UAT. The command to run automation tests through the Editor directly looks like this:

# Starts the game, runs the specified automation tests, and then exits
# (Note the use of the `-nullrhi` flag to disable rendering, which allows this to work in containers without GPU access)
UE4Editor "/path/to/project.uproject" -game -buildmachine -stdout -unattended -nopause -nullrhi -nosplash -ExecCmds="automation RunTests <TEST1>+<TEST2>+<TESTN>;quit"

The command to run automation tests through UAT looks like this:

# Starts the game, runs the specified automation tests, and then exits
# (Note the use of the `-nullrhi` flag to disable rendering, which allows this to work in containers without GPU access)
RunUAT BuildCookRun -project="/path/to/project.uproject" -noP4 -buildmachine -unattended -nullrhi -run "-RunAutomationTest=<TEST1>+<TEST2>+<TESTN>"

Unreal Engine 4.21.0 introduced the Gauntlet Automation Framework, which allows developers to specify tests using C# scripts that are then run by the RunUnreal command provided by UAT. However, at the time of writing there is very little available documentation for Gauntlet and the authors of this documentation have not tested the use of Gauntlet within Unreal Engine containers.

Using third-party infrastructure and abstractions

There are a number of infrastructure projects maintained by the community that abstract the process of building and packaging Unreal projects and plugins. These infrastructure projects typically automate the process of generating the appropriate arguments for the BuildCookRun command or BuildPlugin command and invoking UAT. Some example projects are listed below:

In order to use any given infrastructure project it will need to be included in your container images. Unless your Unreal Engine container images already contain these components you will need to write a Dockerfile that extends an existing Unreal Engine container image and installs the desired infrastructure.

Building container images for deployment

In a scenario where you’re packaging a project for distribution via traditional mechanisms you will most likely start a container using an existing image and run a series of build commands inside that container. However, if you’re deploying a packaged project using Docker containers, the entire build process can actually take place within a docker build command that uses Docker multi-stage builds to copy the packaged files into a new container image at the end of the process. (In a dual-distribution scenario you can also copy the packaged files from the filesystem of the newly-built container image to the host filesystem and then deploy those files using traditional mechanisms.)

Writing a Dockerfile for a multi-stage build is quite straightforward:

An example Dockerfile is provided below that builds and packages a project in the ue4-full container image from the ue4-docker project and copies the packaged files into the adamrehn/ue4-runtime runtime image.

# Perform the build in an Unreal Engine container image that includes the Engine Tools
FROM adamrehn/ue4-full:4.21.2 AS builder

# Clone the source code for our Unreal project
RUN git clone --progress --depth 1 https://github.com/adamrehn/ue4-sample-project.git /tmp/project

# Build and package our Unreal project
# (We're using ue4cli for brevity here, but we could just as easily be calling RunUAT directly)
WORKDIR /tmp/project
RUN ue4 package

# Copy the packaged files into a container image that doesn't include any Unreal Engine components
FROM adamrehn/ue4-runtime:latest
COPY --from=builder --chown=ue4:ue4 /tmp/project/dist/LinuxNoEditor /home/ue4/project

This content is landing soon!

Be sure to check out the Unreal Containers Twitter feed for news about content updates.