diff --git a/build_config/docker/Dockerfile.ubuntu.git b/build_config/docker/Dockerfile.ubuntu.git index 0a1085c281df..83f1861d2f43 100644 --- 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 " \ + 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 index 241bace5503f..014ee4e657bb 100644 --- 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).
When building this image, the latest version of SUMO from the repository is used.
This image is built nightly and uploaded to the container registry.
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).
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.
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 index 8e6cdb116e28..638ad9a2fc55 100644 --- 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 index f26231f1e5fd..f32db00f30e4 100644 --- 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 new file mode 100644 index 000000000000..841123312c45 --- /dev/null +++ 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 + + + + + + + + + + + + + + + + + + + + + + +``` + +#### `hello.rou.xml` + +```xml + + + + + +``` + +#### `hello.sumocfg` + +```xml + + + + + + + + +``` + +## 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 index 2a1445a0bc54..dada7d77ea20 100644 --- 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.