Tools and software

Using the Image Builder tool

Overview

Refer to this page to download the image builder tool and familiarize yourself with its basic functionality.

Note that to create a default container image compatible with SPS from a UE project in most case scenarios, you simply need to authenticate with the target registry using auth command, and then create the image using create command and specifying the location of your UE project alongside its desired tag name.

This page covers advanced Image Builder Tool flags and their usage. You can add -h or --help flags to any command to view the list of its subcommands and flags, for example image-builder -h or image builder auth --help.

Authentication using image-builder auth

This command with its respective flags is used to authenticate to the target container registry.

-r, --registry

Target container registry.

-u, --username

Username used to authenticate to the container registry.

-p, --password

Password used to authenticate to the container registry.

An example command to authenticate with Docker would look like this:

image-builder auth --username "your_username" --password "your_password" --registry "https://index.docker.io/v1/"

Note that users can be authorised to multiple registries in the same environment, however, this is limited to one set of user/password credentials per registry by docker. Authorizing new credentials on an already existing registry will overwrite the previous set of credentials.

--password-stdin

Use this flag to pipe the password from standard input instead of supplying it via --password.

Create image using image-builder create

Use this command to build a container image from your UE project compatible with SPS and push it to the target registry.

-p, --package

Point the IBT to the location of your compiled UE project.

-t, --tag

Use this flag to overwrite an existing container tag.

These two flags substitute the minimum required command to create an image, for example:

image-builder create --package "/path/to/YourUnrealProjectFolder/Windows/" --tag "index.docker.io/yourdockerusername/yourrepository:desiredtagname"

--entrypointFile

When the IBT is pointed at a folder, it will automatically scan it to find an executable file for your project to use an entry point. Use this flag to manually specify the entry point, for example, if a custom UE launcher is being used.

--base-container-override

Add this flag to use a custom base image, for example, if your project has specific dependencies. Note that if the custom base container is stored on a private repository, the IBT has to be authorized with that repository, as well as with the registry where the new tag will be created:

image-builder create --package "/path/to/YourUnrealProjectFolder/Windows/" --base-container-override "docker.io/my-user/my-repository:custom-base-image" --tag "index.docker.io/yourdockerusername/yourrepository:desiredtagname"

--insecure

Skip registry certificate checks and push the container into it anyway, for example, when used on a self-hosted registry.

--os-type

Specify which OS type of the container to create: Windows or Linux. This flag can be used if the target folder contains builds for both Linux and Windows. If no platform is specified, the tool will first search for a Linux entry point, and if it can’t find one, only then it will search for Windows binaries.

--skip-building

Skip creating the tarball and instead push the image from an already existing tarball. The tool will look for a tarball in the .temp folder inside the IBT tool folder itself, which is where tarballs are created by default. It can’t look inside another directory and will use the first tarball it finds alphabetically.

-n, --temp-file

A custom filename to use for the tarball, where the default name is “project.tar.gz”.

-d, --temp-folder

A custom folder to use for storing the tarball.