ccees/utopia repository overview

⁠Utopia

• Project website: utopia-project.org⁠
• Repository: gitlab.com/utopia-project/utopia⁠
• Documentation: docs.utopia-project.org⁠

⁠Overview

This image contains a ready-to-run instance of Utopia⁠ with all its models. It is built on top of the ccees/utopia-base image⁠.

For further information and usage guides, have a look at the Utopia documentation⁠. For the source code, visit the project page⁠. Please open issues there, if you detect any problems with this docker image.

⁠Supported Tags

Only the latest tag is maintained for this docker image. It refers to the most recent version of Utopia and is updated upon each merge into the master branch of the source code repository⁠. The corresponding Dockerfile can be found here⁠.

⁠Using the Utopia Image

1. Choose a suitable directory on your host system and enter it.
2. Pull the desired container, e.g. with the latest tag

   docker pull ccees/utopia:latest
   

   Copy
3. Run the container by executing

   docker run -v $PWD:/home/utopia/io -it ccees/utopia:latest
   

   Copy
   This will mount your current directory ($PWD; in Windows PowerShell you will need to use ${PWD} instead!) into the Docker container at /home/utopia/io. By default, all output of Utopia will be placed into /home/utopia/io/output/. Therefore, the output directory will be persistently available on your host system via the file mount. Inversely, you can place configuration files into the mounted directory on your host system to use them inside the container.
   Note: You might have to give Docker the permission to mount those directories; you can do so via the Docker Preferences.
4. You are now inside the container. (If you ever desire to leave, you may do so by running exit)
5. In there, Utopia is controlled via the utopia command line interface, which is made available upon starting a container of this image. For example, to run a model with its default settings, execute

   utopia run {model_name}
   

   Copy
   You can find a list of available models in the documentation⁠. For a full overview of available commands and options, use

   utopia --help
   

   Copy

⁠Working interactively

You can also use your container to work interactively with Utopia. The image already includes the latest installation of IPython⁠ and Jupyter Notebook⁠. The following steps will show how you can setup a notebook server running inside the docker container and then attach to it on your host machine:

1. Add a port-mapping to the docker run command: As the notebook is by default hosted on port 8888, we want to map that port through from the container to your host:

   docker run -v $PWD:/home/utopia/io -p 8888:8888 -it ccees/utopia:latest
   

   Copy
2. Now inside the container, start a notebook server that listens to all incoming traffic on that port:

   jupyter notebook --ip 0.0.0.0 --port=8888 --no-browser
   

   Copy
   • Note: If you want to run several notebook servers at once, make sure that they use different ports. We're sticking with the default port here, 8888.
3. Some log output will appear and instruct you on the address you have to open, something like http://localhost:8888/?token=.... Copy that address and use the browser of your host machine to navigate there.
   • Don't forget copying the token. The token is needed to authenticate you with the notebook.
   • If you see an address starting with http://(container_name or 127.0.0.1):8888/..., where container name are some random alphanumeric characters, don't despair. This just gives you options on how to open the container. The only viable option from outside the container is localhost, which is the same as 127.0.0.1.
4. You should now see the content of the /home/utopia/io directory and can create a notebook there. Congratulations! :)

For more information on how to work with models inside the notebook, have a look at the corresponding documentation⁠.

⁠Troubleshooting

⁠Permission Denied on Linux hosts

If you get a Permission Denied error when running a simulation, the mounted directory probably does not have proper access rights; this frequently happens when the host system is a Linux distribution.

To resolve this, you can allow global write access via chmod -R 777 path/to/mounted/directory, which allows the container to write data. Alternatively, consult the docker run documentation⁠ regarding how to align the user ID within the container with the user ID on your host system.

⁠Cannot install additional software via apt install

To install packages, first update the package index by running:

apt update

After this, you can install packages as usual, e.g. apt install vim.

⁠Developing Utopia Models using this Docker Image

You can also use this docker image to develop Utopia models. This can be useful if you are not working on a system that Utopia can be installed on from source.

The basic idea is:

• Utopia is installed inside the docker image
• The additional models repository is mounted to a directory on your host system
• You can modify the source code on your host system, using your existing editor or IDE
• For compiling and running code, you use the docker container

Effectively, the docker container serves as an Utopia-specific development environment. This also pertains to custom repositories that hold further Utopia models.

Note: These procedures are not suitable for development of the Utopia framework itself.

⁠Mounting Directories

For development, we suggest the following folder structure. The table shows the equivalent paths on host and container side.

The ~/utopia/MyModels directory is the cloned git repository you want to make source code changes on. Throughout this guide, MyModels is a place holder; replace it by the name of the repository you want to work on.

⁠Creating and Entering a Container

Enter the ~/utopia directory or the corresponding directory on your host system. To create and enter a new container, the command is as follows (make sure to adjust the MyModels place holder):

docker run -v $PWD/io:/home/utopia/io -v $PWD/MyModels:/home/utopia/MyModels --name MyUtopiaModels -it ccees/utopia:latest

By specifying a container name, you can later run the existing container again using the following command:

docker start -ia MyUtopiaModels

Remarks:

• If a container already exists, you will have to either remove the container (careful here!) or choose a different name.
• You can also omit the container name, in which case docker will provide a random name.

⁠Making Source Code Changes

After entering the container with the above command, you can make changes to the source code in the mounted directories. You can perform these changes both from within the container or on your host system; the mounted directories are mirrored between the two.

⁠Compiling Code

To compile code, first enter the docker container using one of the ways described above. Inside the container, navigate to the build directory of the project you made changes to and invoke the respective configuration and build commands. For more information on available commands, refer to the Utopia README⁠.

cd /utopia/build
cmake ..
make dummy

⁠Updating an Existing Container

To update the source code of an existing container, you can use the same procedure as you would outside the container:

cd /home/utopia/MyModels
git checkout master
git pull
cd build
cmake ..

To update the Utopia framework, navigate to the /utopia directory and use the same commands.

Note: If there are significant changes to the Utopia framework (i.e. the ccees/utopia image the containers are based on), the more advisable approach is to docker pull the updated image and create a new container using the procedure described above.

Important: Before removing a container, make sure that you have any source code changes committed and pushed or otherwise stored! Via the directory mounts, the data in io and MyModels will persist; for the framework repository at /utopia that is not the case.