eclipse-sumo · Menkalian · Jan 8, 2025 · Jan 14, 2025 · Jan 14, 2025 · Jan 14, 2025
diff --git a/build_config/docker/Dockerfile.ubuntu.git b/build_config/docker/Dockerfile.ubuntu.git
@@ -7,7 +7,8 @@
 # This Dockerfile installs everything for a full fledged SUMO with all tools runnable.
 # If you don't need certain features and rather have a smaller container you can comment the unneeded parts below
 
-FROM ubuntu:jammy
+# We are dividing the build into multiple stages to reduce the size of the resulting image
+FROM ubuntu:jammy as build
 
 ENV SUMO_HOME=/usr/share/sumo
 ARG DEBIAN_FRONTEND=noninteractive
@@ -27,12 +28,48 @@ RUN apt-get -y install $(cat /opt/sumo/build_config/tools_req_deb.txt)
 
 # JuPedSim
 RUN cd /opt; git clone -b $JUPEDSIM_VERSION https://github.com/PedestrianDynamics/jupedsim
-RUN cd /opt; cmake -B jupedsim-build -D CMAKE_INSTALL_PREFIX=jupedsim-install jupedsim; \
- cmake --build jupedsim-build -j4 --config Release; cmake --install jupedsim-build --config Release; rm -rf jupedsim-build
+RUN cd /opt; cmake -B jupedsim-build -D CMAKE_INSTALL_PREFIX=/install/usr jupedsim; \
+ cmake --build jupedsim-build -j4 --config Release; cmake --install jupedsim-build --config Release
 
 # python packages needed for the tools (the ones where we do not have ubuntu packages)
 RUN pip3 install -r /opt/sumo/tools/requirements.txt
 # python packages needed for the docs (the ones where we do not have ubuntu packages)
 RUN pip3 install -r /opt/sumo/docs/web/requirements.txt
-RUN cd /opt/sumo; cmake -B cmake-build -DCMAKE_INSTALL_PREFIX=/usr -DSUMO_UTILS=TRUE; \
- cd cmake-build; make -j8 all examples doc install; cd ..; rm -rf cmake-build
+
+RUN cd /opt/sumo; cmake -B cmake-build -DCMAKE_INSTALL_PREFIX=/install/usr -DSUMO_UTILS=TRUE; \
+ cd cmake-build; make -j8 all examples doc install
+
+# Now create actual image
+FROM ubuntu:jammy
+
+# Add metadata
+LABEL org.opencontainers.image.authors="SUMO Developers <sumo-dev@eclipse.org>" \
+      org.opencontainers.image.url="https://ghcr.io/eclipse-sumo/sumo" \
+      org.opencontainers.image.source="https://github.com/eclipse-sumo/sumo/blob/main/build_config/docker/Dockerfile.ubuntu.git" \
+      org.opencontainers.image.documentation="https://sumo.dlr.de/docs/Developer/Docker.html" \
+      org.opencontainers.image.licenses="EPL-2.0 OR GPL-2.0-or-later"
+
+# Setup environment
+ENV SUMO_HOME=/usr/share/sumo
+ARG DEBIAN_FRONTEND=noninteractive
+
+# Getting build artifacts
+COPY --from=build /install/usr /usr
+# Get dependency lists
+COPY --from=build /opt/sumo/build_config/build_req_deb.txt /tmp/build_req_deb.txt
+COPY --from=build /opt/sumo/build_config/tools_req_deb.txt /tmp/tools_req_deb.txt
+COPY --from=build /opt/sumo/tools/requirements.txt /tmp/requirements.txt
+
+# Installing runtime dependencies (for simplicity we use the build dependencies. Possibility for optimization in the future)
+RUN apt-get -qq update; \
+    apt-get -qq -y install $(cat /tmp/build_req_deb.txt) $(cat /tmp/tools_req_deb.txt) \
+                           libavformat58 libopenscenegraph161 libswscale5; \
+    apt-get -qq clean autoclean; \
+    apt-get -qq -y autoremove; \
+    rm -rf /var/lib/apt/lists/*
+
+# Installing tools dependencies for python
+RUN pip3 install --no-cache-dir -r /tmp/requirements.txt
+
+CMD ["/bin/bash", "-c"]
+
diff --git a/docs/web/docs/Developer/Docker.md b/docs/web/docs/Developer/Docker.md
@@ -4,54 +4,69 @@ title: Docker
 
 ## Dockerized SUMO
 
-Building and installing SUMO from source is not an easy task for
-beginner users. Docker is a popular tool to solve this issue. Searching
-"SUMO" at [Docker Hub](https://hub.docker.com) will give several results
-from attempts to Dockerize SUMO. We list a few of these attempts
-beginning with standalone SUMO to SUMO with other packages.
-
-### SUMO, SUMO GUI, and TraCI
-
-The solution given at
-[docker-sumo](https://github.com/bogaotory/docker-sumo) contains only
-standard SUMO and tools. It demonstrates how to Dockerize SUMO version
-0.30.0 on top of Ubuntu 16.04. As well as sumo and TraCI,
-[docker-sumo](https://github.com/bogaotory/docker-sumo) also shows the
-user how to access the graphical interface of a Dockerized SUMO, i.e.
-**sumo-gui**, which is unique compared to other attempts at Dockerising
-SUMO.
-
-![Docker-sumo-demo1.gif](../images/Docker-sumo-demo1.gif "Docker-sumo-demo1.gif")
-**sumo-gui** in action from [docker-sumo](https://github.com/bogaotory/docker-sumo)
-
-### SUMO and TraCI4J
-
-The [sumo-docker](https://hub.docker.com/r/similitude/sumo-docker/)
-project demonstrates how to Dockerize SUMO version 0.25.0 on top of
-Apache Maven 3 with [TraCI4J](https://github.com/egueli/TraCI4J).
-
-### SUMO and JuPedSim
-
-The
-[hybrid_sumo_jps](https://hub.docker.com/r/grgrlmml/hybrid_sumo_jps/)
-project aims on providing an easy to use docker image for running a
-hybrid simulation that couples SUMO with
-[JuPedSim](https://www.jupedsim.org). SUMO is a mighty simulator for all
-kinds of transport problems that focuses mainly on motorized traffic.
-While SUMO also provides a pedestrian model for simulating pedestrians
-on sidewalks, crossings or the like, it lacks of the capability to model
-pedestrians in true 2d space (e.g. in buildings, on squares, at train
-stations). Instead of reinventing the wheel we decided to team up with
-JuPedSim and develop a hybrid coupling approach that combines the power
-of both frameworks. The coupling is realized using google's [protocol
-buffers](https://github.com/google/protobuf) over
-[gRPC](https://github.com/grpc), a library for \*remote procedure
-calls\*. Currently this coupling approach is provided as a Docker image.
-Moreover, also the Docker image is not intended to replace the common
-SUMO installation (e.g. hybrid_sumo_jps does not provided a graphical
-interface, i.e. no sumo-gui), you may also use the hybrid_sumo_jps
-image to run ordinary SUMO scenarios.
-
-Details on how to run hybrid_sumo_jps can be found at the
-corresponding [hybrid_sumo_jps's Docker
-Hub](https://hub.docker.com/r/grgrlmml/hybrid_sumo_jps/) page.
+Building and installing SUMO from source is not an easy task for beginner users.
+Docker is a popular tool to solve this issue.
+SUMO provides [Dockerfiles](https://github.com/eclipse-sumo/sumo/blob/main/build_config/docker) and [prebuilt Docker images](https://github.com/eclipse-sumo/sumo/pkgs/container/sumo/versions) to use.
+
+### Available Dockerfiles
+
+There are several Dockerfiles available in the SUMO repository.
+To build them, check out [the SUMO repository](https://github.com/eclipse-sumo/sumo) and use the following command while in the `build_config/docker` directory of the repository:
+
+```shell
+    docker build -f {NAME_OF_DOCKERFILE} .
+```
+
+!!! note
+    Ensure to include the dot at the end of the command.
+
+The following Dockerfiles containing SUMO are available:
+
+| Dockerfile                 | description                                                                                                                                                                                                                                                                                                                                                                              |
+|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `Dockerfile.ubuntu.git`    | An image containing a complete SUMO installation (binaries, documentation, TraCI, ...) and [JuPedSim](https://www.jupedsim.org) based on Ubuntu Jammy (22.04). <br> When building this image, the latest version of SUMO from the repository is used. <br> This image is built nightly and uploaded to the container registry. <br> It is also built and tagged for each stable release. |
+| `Dockerfile.fedora`        | An image with a SUMO installation based on the current Fedora development version (rawhide). <br> When building this image, the latest version of SUMO from the repository is used.                                                                                                                                                                                                      |
+| `Dockerfile.ubuntu.latest` | An image based on Ubuntu Jammy (22.04) with SUMO installed from the APT package manager. <br> This image does not build SUMO from source, so it will always use a stable version.                                                                                                                                                                                                            |
+
+The following Dockerfiles provide build environments:
+
+| Dockerfile                 | Description                                                                                                                                 |
+|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| `Dockerfile.jenkins-build` | Environment for building SUMO on Jenkins. Installs all packages required to build SUMO, but does not contain any SUMO binaries.             |
+| `Dockerfile.manylinux2014` | Build environment for creating [manylinux](https://github.com/pypa/manylinux) python wheels, adapted with additional preinstalled packages. |
+
+### Available Images in the registry
+
+SUMO publishes images to the [GitHub container registry](https://ghcr.io/eclipse-sumo/sumo), which can be pulled and
+used immediately.
+The published images are built from the `Dockerfile.ubuntu.git` Dockerfile.
+
+To use any of the uploaded images, reference `ghcr.io/eclipse-sumo/sumo:${TAG}` (e.g. `docker pull ghcr.io/eclipse-sumo/sumo:main`).
+
+The following tags are available:
+
+| Tag                       | Description                                                                                                    |
+|---------------------------|----------------------------------------------------------------------------------------------------------------|
+| `main` `nightly`          | Nightly build containing the current version of SUMO from the repository.                                      |
+| `vX_Y_Z` (e.g. `v1_21_0`) | A version of the image created alongside the respective release. Contains SUMO in the matching stable version. |
+| `latest`                  | References the image of the latest stable release (e.g. `v1_21_0`)                                             |
+
+### How to use dockerized SUMO
+
+A complete example is available in [the tutorial on containerized SUMO](../Tutorials/Containerized_SUMO.md).
+
+A quick example for running a prepared simulation looks like this:
+
+```shell
+   docker run \
+      -v /path/to/your/simulation/data:/data \
+      ghcr.io/eclipse-sumo/sumo:main \
+      sumo /data/simulation.sumocfg
+```
+
+A use-case for this could be preparing the simulation data on a computer with SUMO installed and then running the simulation on a server without needing to install SUMO.
+
+The container images also contains the graphical applications.
+However, configuring them for use depends on your operating system and graphical environment (e.g., X11, Wayland).
+For guidance, consult Docker's documentation on GUI application forwarding.
+Therefore, we cannot provide specific instructions here.
diff --git a/docs/web/docs/Developer/index.md b/docs/web/docs/Developer/index.md
@@ -55,7 +55,7 @@ title: Developer
 - [How To add more car-following models](Implementation_Notes/Vehicle_Models.md)
 - [Progress on implementing an XML validation](XML_Validation.md)
 - [HowToRelease](HowToRelease.md) - how to do a release
-- [Docker](Docker.md) - projects using Dockerised SUMO
+- [Docker](Docker.md) - how to use containerized SUMO
 - [How To create a CI Test with GitHub Actions](Github_Actions_CI_Test.md) - projects depending on SUMO
 - [Git](GitStuff.md)
 - [Profiling](Profiling.md)

diff --git a/docs/web/docs/Installing/index.md b/docs/web/docs/Installing/index.md
@@ -158,14 +158,7 @@ you need several additional python modules. The easiest way to install them is t
 
 # via Docker
 
-Building and installing SUMO from source is not an easy task for
-beginner users. Docker is a popular tool to solve this issue. Searching
-"SUMO" at [Docker Hub](https://hub.docker.com) will give several results
-from existing attempts at Dockerising SUMO.
-
-The solution given at
-[docker-sumo](https://github.com/bogaotory/docker-sumo) demonstrates how
-to Dockerise SUMO version 0.30.0 on top of Ubuntu 16.04. As well as
-**sumo** and **traci**, the use of **sumo-gui** is also demonstrated by
-[docker-sumo](https://github.com/bogaotory/docker-sumo) so that the
-users have access to the graphical interface of a Dockerised SUMO.
+Building and installing SUMO from source is not an easy task for beginner users.
+Docker is a popular tool to solve this issue.
+SUMO provides [Dockerfiles](https://github.com/eclipse-sumo/sumo/blob/main/build_config/docker) and [prebuilt Docker images](https://github.com/eclipse-sumo/sumo/pkgs/container/sumo/versions) to use.
+For more details check out [the documentation on dockerized SUMO](../Developer/Docker.md) or [the tutorial on dockerized SUMO](../Tutorials/Containerized_SUMO.md).
diff --git a/docs/web/docs/Tutorials/Containerized_SUMO.md b/docs/web/docs/Tutorials/Containerized_SUMO.md
@@ -0,0 +1,114 @@
+---
+title: Containerized SUMO
+---
+
+This tutorial shows how to use SUMO to run simulations inside a docker container.
+
+## Introduction
+
+This tutorial demonstrates how to use SUMO for running simulations without installing the software on your local machine.
+
+It is also possible to run the GUI applications from the docker container.
+The way to do this is highly dependent on your individual setup, so we will not provide the required configuration or commands.
+
+## Getting the docker image
+
+You can either get the latest docker image from the SUMO docker registry by using
+
+```shell
+  docker pull ghcr.io/eclipse-sumo/sumo:main
+```
+
+or build your own local version of the image by checking out the [SUMO repository](https://github.com/eclipse-sumo/sumo) and executing:
+
+```shell
+  cd build_config/docker
+  docker build -t ghcr.io/eclipse-sumo/sumo:main -f Dockerfile.ubuntu.git .
+```
+
+## Creating simulation files
+
+For this tutorial we use the simulation files from the [Hello SUMO Tutorial](Hello_SUMO.md).
+Check out that tutorial to learn about the purpose of the files.
+
+Create a directory called `hello_sumo_docker` and in it create 3 files:
+
+#### `hello.net.xml`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<net version="1.20" junctionCornerDetail="5" limitTurnSpeed="5.50" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+     xsi:noNamespaceSchemaLocation="http://sumo.dlr.de/xsd/net_file.xsd">
+    <location netOffset="250.00,0.00" convBoundary="0.00,0.00,501.00,0.00" origBoundary="-250.00,0.00,251.00,0.00"
+              projParameter="!"/>
+    <edge id=":2_0" function="internal">
+        <lane id=":2_0_0" index="0" speed="13.89" length="0.10" shape="500.00,-1.60 500.00,-1.60"/>
+    </edge>
+    <edge id="1to2" from="1" to="2" priority="-1">
+        <lane id="1to2_0" index="0" speed="13.89" length="500.00" shape="0.00,-1.60 500.00,-1.60"/>
+    </edge>
+    <edge id="out" from="2" to="3" priority="-1">
+        <lane id="out_0" index="0" speed="13.89" length="1.00" shape="500.00,-1.60 501.00,-1.60"/>
+    </edge>
+
+    <junction id="1" type="dead_end" x="0.00" y="0.00" incLanes="" intLanes="" shape="0.00,0.00 0.00,-3.20"/>
+    <junction id="2" type="priority" x="500.00" y="0.00" incLanes="1to2_0" intLanes=":2_0_0"
+              shape="500.00,0.00 500.00,-3.20 500.00,0.00">
+        <request index="0" response="0" foes="0" cont="0"/>
+    </junction>
+    <junction id="3" type="dead_end" x="501.00" y="0.00" incLanes="out_0" intLanes="" shape="501.00,-3.20 501.00,0.00"/>
+
+    <connection from="1to2" to="out" fromLane="0" toLane="0" via=":2_0_0" dir="s" state="M"/>
+    <connection from=":2_0" to="out" fromLane="0" toLane="0" dir="s" state="M"/>
+</net>
+```
+
+#### `hello.rou.xml`
+
+```xml
+<routes>
+    <vType accel="1.0" decel="5.0" id="Car" length="2.0" maxSpeed="100.0" sigma="0.0"/>
+    <route id="route0" edges="1to2 out"/>
+    <vehicle depart="1" id="veh0" route="route0" type="Car"/>
+</routes>
+```
+
+#### `hello.sumocfg`
+
+```xml
+
+<configuration>
+    <input>
+        <net-file value="hello.net.xml"/>
+        <route-files value="hello.rou.xml"/>
+    </input>
+    <time>
+        <begin value="0"/>
+        <end value="10000"/>
+    </time>
+</configuration>
+```
+
+## Running the simulation
+
+To run the simulation start a new container from the image and mount the directory in there with the `-v`-Option.
+Add `--full-output result.xml` to the SUMO command to get the result of the simulation.
+The command to start the container might look like this:
+
+```shell
+  # Replace this with the location where your simulation files are located.
+  export SIMULATION_FILES_DIR=$PWD
+
+  docker run \
+      --rm \
+      -v $SIMULATION_FILES_DIR:$SIMULATION_FILES_DIR \
+      ghcr.io/eclipse-sumo/sumo:main \
+      sumo --configuration-file $SIMULATION_FILES_DIR/hello.sumocfg --full-output $SIMULATION_FILES_DIR/result.xml
+```
+
+This will run the simulation specified in `hello.sumocfg`.
+After that, a file named `result.xml` will have been created, which contains the output of the simulation.
+
+## Further Reading
+
+You can try more of the [Tutorials](index.md) with the docker image.
diff --git a/docs/web/docs/Tutorials/index.md b/docs/web/docs/Tutorials/index.md
@@ -62,6 +62,7 @@ The SUMO User Conference is an annual event organized by the German Aerospace Ce
 * [PT from OpenStreetMap](PT_from_OpenStreetMap.md) - Creating a runnable public transit scenario entirely from [OpenStreetMap](https://www.openstreetmap.org/)
 * [Importing GTFS](GTFS.md) - Importing public transport schedules from public sources using the General Transit Feed Specification
 * [Port](port.md) - Creating a scenario that simulates the port logistics of an arbitrary port from [OpenStreetMap](https://www.openstreetmap.org/)
+* [Containerized SUMO](Containerized_SUMO.md) - Using SUMO to run a simulation inside a docker container
 
 # TraCI Tutorials
 These tutorials use the [Python-TraCI Library](../TraCI/Interfacing_TraCI_from_Python.md) for interfacing a python script with a running [sumo](../sumo.md) simulation.