- Key considerations
- Implementation guidelines
- Related media
On Linux host systems that satisfy the requirements listed at the top of this page, it is possible to run packaged Unreal projects from inside a container with full GPU acceleration and have rendered output displayed on the host system. This is particularly useful when deploying multiple instances of a project to a coordinated set of machines, such as when using the nDisplay system to display output on an LED wall or a CAVE.
nDisplay information coming soon!
This page currently includes only basic information about running packaged Unreal Engine projects in containers and displaying the rendered output on host system displays. Linux support for the Unreal Engine’s nDisplay system is slated for introduction in Unreal Engine 4.27 and the contents of this page will be expanded to include information related to using nDisplay in containers once this new version is released.
This approach only works on machines that satisfy the hardware and software requirements for running GPU accelerated Linux containers. For orchestration purposes, it is often convenient if these machines are also registered as worker nodes in a Kubernetes cluster, which requires additional configuration.
Because this approach makes use of a bind-mounted X11 socket, an X11 server must be running on each host system. Linux distributions that ship with an alternative display server protocol enabled by default (e.g. Wayland) will require additional configuration to enable an X11 user session.
Runtime container images must include the X11 runtime libraries in order for the Unreal Engine to recognise the bind-mounted X11 socket. If your container images do not include the relevant libraries then the Engine will default to offscreen rendering and no output will be displayed.
Running a container with Docker
To run an interactive container locally with Docker, use the following command (replace
unreal-project:latest with the tag for your container image):
The individual arguments to the docker run command are explained below:
--rm: Removes the container when it stops.
-ti: Starts an interactive session.
--gpus=all: Enables GPU access via the NVIDIA Container Toolkit.
-v/tmp/.X11-unix:/tmp/.X11-unix:rw: Bind-mounts the X11 socket from the host system.
-e DISPLAY: Propagates the
DISPLAYenvironment variable from the host system.
"unreal-project:latest": Replace this with the tag for your container image.
# <args>: Replace this with any command-line arguments to pass to your packaged Unreal project, such as flags for resolution.
Your packaged Unreal project should start running and displaying output on the host system’s display. If the project does not start automatically and an interactive bash shell starts instead then you will need to ensure you set the project’s startup script as the container image’s ENTRYPOINT and rebuild the image.
Deploying containers with Kubernetes
When deploying a set of containers with Kubernetes, be sure to include the following in the Pod spec template:
Depending on the configuration of the Kubernetes cluster to which the containers will be deployed, it may also be necessary to specify node selectors or resource requests for GPUs.
Using container images from the ue4-runtime project
The base images from the ue4-runtime project whose tags are suffixed with
-virtualgl include the X11 runtime libraries required in order to display rendered output on a host system. Once you have built a container image that extends one of these base images with the files for your packaged Unreal project then you can run containers using the commands from the Implementation-agnostic commands section.
Using container images built from custom Dockerfiles
Check out the Tips for working with the NVIDIA Container Toolkit section of the custom Dockerfile guide for instructions on enabling X11 support in your own container images. Once you have built your container images then you can run them using the commands from the Implementation-agnostic commands section.
This content is landing soon!
Be sure to check out the Unreal Containers Twitter feed for news about content updates.