Using Docker For ML-Agents
We currently offer a solution for Windows and Mac users who would like to do
training or inference using Docker. This option may be appealing to those who
would like to avoid installing Python and TensorFlow themselves. The current
setup forces both TensorFlow and Unity to only rely on the CPU for
computations. Consequently, our Docker simulation does not use a GPU and uses
Xvfb to do visual rendering.
Xvfb is a
utility that enables
ML-Agents (or any other application) to do rendering
virtually i.e. it does not assume that the machine running
ML-Agents has a GPU
or a display attached to it. This means that rich environments which involve
agents using camera-based visual observations might be slower.
- Unity Linux Build Support Component
Download the Unity Installer and add the Linux Build Support Component
Download and install Docker if you don't have it setup on your machine.
Since Docker runs a container in an environment that is isolated from the host machine, a mounted directory in your host machine is used to share data, e.g. the trainer configuration file, Unity executable, curriculum files and TensorFlow graph. For convenience, we created an empty
unity-volumedirectory at the root of the repository for this purpose, but feel free to use any other directory. The remainder of this guide assumes that the
unity-volumedirectory is the one used.
Using Docker for ML-Agents involves three steps: building the Unity environment with specific flags, building a Docker container and, finally, running the container. If you are not familiar with building a Unity environment for ML-Agents, please read through our Getting Started with the 3D Balance Ball Example guide first.
Build the Environment (Optional)
If you want to used the Editor to perform training, you can skip this step.
Since Docker typically runs a container sharing a (linux) kernel with the host machine, the Unity environment has to be built for the linux platform. When building a Unity environment, please select the following options from the the Build Settings window:
- Set the Target Platform to
- Set the Architecture to
- If the environment does not contain visual observations, you can select the
Build, pick an environment name (e.g.
3DBall) and set the output
unity-volume. After building, ensure that the file
<environment-name>.x86_64 and subdirectory
Build the Docker Container
First, make sure the Docker engine is running on your machine. Then build the Docker container by calling the following command at the top-level of the repository:
docker build -t <image-name> .
<image-name> with a name for the Docker image, e.g.
Run the Docker Container
Run the Docker container by calling the following command at the top-level of the repository:
docker run --name <container-name> \ --mount type=bind,source="$(pwd)"/unity-volume,target=/unity-volume \ -p 5005:5005 \ <image-name>:latest \ --docker-target-name=unity-volume \ <trainer-config-file> \ --env=<environment-name> \ --train \ --run-id=<run-id>
Notes on argument values:
<container-name>is used to identify the container (in case you want to interrupt and terminate it). This is optional and Docker will generate a random name if this is not set. Note that this must be unique for every run of a Docker image.
<image-name>references the image name used when building the container.
<environment-name>(Optional): If you are training with a linux executable, this is the name of the executable. If you are training in the Editor, do not pass a
<environment-name>argument and press the
▶️button in Unity when the message "Start training by pressing the Play button in the Unity Editor" is displayed on the screen.
source: Reference to the path in your host OS where you will store the Unity executable.
target: Tells Docker to mount the
sourcepath as a disk with this name.
docker-target-name: Tells the ML-Agents Python package what the name of the disk where it can read the Unity executable and store the graph. This should therefore be identical to
run-id: ML-Agents arguments passed to
trainer-config-fileis the filename of the trainer config file,
traintrains the algorithm, and
run-idis used to tag each experiment with a unique identifier. We recommend placing the trainer-config file inside
unity-volumeso that the container has access to the file.
To train with a
3DBall environment executable, the command would be:
docker run --name 3DBallContainer.first.trial \ --mount type=bind,source="$(pwd)"/unity-volume,target=/unity-volume \ -p 5005:5005 \ balance.ball.v0.1:latest 3DBall \ --docker-target-name=unity-volume \ trainer_config.yaml \ --env=3DBall --train \ --run-id=3dball_first_trial
For more detail on Docker mounts, check out these docs from Docker.
Stopping Container and Saving State
If you are satisfied with the training progress, you can stop the Docker
container while saving state by either using
⌘+C (Mac) or by using
the following command:
docker kill --signal=SIGINT <container-name>
<container-name> is the name of the container specified in the earlier
docker run command. If you didn't specify one, you can find the randomly generated
identifier by running
docker container ls.