From 668838b46b820f178ce45864e1b28855e49e2944 Mon Sep 17 00:00:00 2001 From: Oguz Ozturk Date: Mon, 5 Feb 2024 03:24:49 +0300 Subject: [PATCH] Update Docker installation instructions --- .../autoware/docker-installation-devel.md | 152 --------------- .../autoware/docker-installation-prebuilt.md | 35 ---- .../autoware/docker-installation.md | 178 ++++++++++++------ docs/installation/index.md | 18 +- 4 files changed, 125 insertions(+), 258 deletions(-) delete mode 100644 docs/installation/autoware/docker-installation-devel.md delete mode 100644 docs/installation/autoware/docker-installation-prebuilt.md diff --git a/docs/installation/autoware/docker-installation-devel.md b/docs/installation/autoware/docker-installation-devel.md deleted file mode 100644 index 0dd77b04a2f..00000000000 --- a/docs/installation/autoware/docker-installation-devel.md +++ /dev/null @@ -1,152 +0,0 @@ -# Docker installation for development - -## Prerequisites - -- [Git](https://git-scm.com/) - -- For NVIDIA Jetson devices, install [JetPack](https://docs.nvidia.com/jetson/jetpack/install-jetpack/index.html#how-to-install-jetpack) >= 5.0 - -## How to set up a development environment - -1. Clone `autowarefoundation/autoware` and move to the directory. - - ```bash - git clone https://github.com/autowarefoundation/autoware.git - cd autoware - ``` - -2. You can install the dependencies either manually or using the provided Ansible script. - -> Note: Before installing NVIDIA libraries, confirm and agree with the licenses. - -- [CUDA](https://docs.nvidia.com/cuda/eula/index.html) - -### Installing dependencies manually - -- [Install Nvidia CUDA](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/cuda#manual-installation) -- [Install Docker Engine](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/docker_engine#manual-installation) -- [Install NVIDIA Container Toolkit](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/nvidia_docker#manual-installation) -- [Install rocker](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/rocker#manual-installation) - -### Installing dependencies using Ansible - -Be very careful with this method. Make sure you read and confirmed all the steps in the Ansible configuration before using it. - -If you've manually installed the dependencies, you can skip this section. - -```bash -./setup-dev-env.sh docker -``` - -You might need to log out and log back to make the current user able to use docker. - -## How to set up a workspace - -!!! warning - - Before proceeding, confirm and agree with the [NVIDIA Deep Learning Container license](https://developer.nvidia.com/ngc/nvidia-deep-learning-container-license). - By pulling and using the Autoware Universe images, you accept the terms and conditions of the license. - -1. Create the `autoware_map` directory for map data later. - - ```bash - mkdir ~/autoware_map - ``` - -2. Pull the Docker image - - ```bash - docker pull ghcr.io/autowarefoundation/autoware-universe:latest-cuda - ``` - -3. Launch a Docker container. - - - For amd64 architecture computers with NVIDIA GPU: - - ```bash - rocker --nvidia --x11 --user --volume $HOME/autoware --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda - ``` - - - If you want to run container without using NVIDIA GPU, or for arm64 architecture computers: - - ```bash - rocker -e LIBGL_ALWAYS_SOFTWARE=1 --x11 --user --volume $HOME/autoware --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda - ``` - - For detailed reason could be found [here](./docker-installation.md#docker-with-nvidia-gpu-fails-to-start-autoware-on-arm64-devices) - - For more advanced usage, see [here](https://github.com/autowarefoundation/autoware/tree/main/docker/README.md). - - After that, move to the workspace in the container: - - ```bash - cd autoware - ``` - -4. Create the `src` directory and clone repositories into it. - - ```bash - mkdir src - vcs import src < autoware.repos - ``` - -5. Update dependent ROS packages. - - The dependency of Autoware may change after the Docker image was created. - In that case, you need to run the following commands to update the dependency. - - ```bash - sudo apt update - rosdep update - rosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO - ``` - -6. Build the workspace. - - ```bash - colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release - ``` - - If there is any build issue, refer to [Troubleshooting](../../support/troubleshooting/index.md#build-issues). - -## How to update a workspace - -1. Update the Docker image. - - ```bash - docker pull ghcr.io/autowarefoundation/autoware-universe:latest-cuda - ``` - -2. Launch a Docker container. - - - For amd64 architecture computers: - - ```bash - rocker --nvidia --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda - ``` - - - If you want to run container without using NVIDIA GPU, or for arm64 architecture computers: - - ```bash - rocker -e LIBGL_ALWAYS_SOFTWARE=1 --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda - ``` - -3. Update the `.repos` file. - - ```bash - cd autoware - git pull - ``` - -4. Update the repositories. - - ```bash - vcs import src < autoware.repos - vcs pull src - ``` - -5. Build the workspace. - - ```bash - colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release - ``` diff --git a/docs/installation/autoware/docker-installation-prebuilt.md b/docs/installation/autoware/docker-installation-prebuilt.md deleted file mode 100644 index 40d4700d9b1..00000000000 --- a/docs/installation/autoware/docker-installation-prebuilt.md +++ /dev/null @@ -1,35 +0,0 @@ -# Docker installation for quick start - -## How to set up a development environment - -1. Installing dependencies manually - - - [Install Docker Engine](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/docker_engine#manual-installation) - - - [Install NVIDIA Container Toolkit](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/nvidia_docker#manual-installation) - - - [Install rocker](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/rocker#manual-installation) - -## How to set up a workspace - -1. Create the `autoware_map` directory for map data later. - - ```bash - mkdir ~/autoware_map - ``` - -2. Launch a Docker container. - - ```bash - rocker --nvidia --x11 --user --volume $HOME/autoware_map -- ghcr.io/autowarefoundation/autoware-universe:humble-latest-prebuilt - ``` - - For more advanced usage, see [here](https://github.com/autowarefoundation/autoware/tree/main/docker/README.md). - -3. Run Autoware simulator - - Inside the container, you can run the Autoware simulation by following this tutorial: - - [planning simulation](../../tutorials/ad-hoc-simulation/planning-simulation.md) - - [rosbag replay simulation](../../tutorials/ad-hoc-simulation/rosbag-replay-simulation.md). diff --git a/docs/installation/autoware/docker-installation.md b/docs/installation/autoware/docker-installation.md index eae63229ff5..82521da9892 100644 --- a/docs/installation/autoware/docker-installation.md +++ b/docs/installation/autoware/docker-installation.md @@ -1,106 +1,160 @@ -# Docker installation +# Open AD Kit: Containerized Workloads for the Autoware + +Open AD Kit offers two types of Docker image to let you get started with the Autoware quickly: `devel` and `runtime`. + +1. The `devel` image enables you to develop Autoware without setting up the local development environment. +2. The `runtime` image contains only runtime executables and enables you to try out Autoware quickly. !!! info - Since this page explains Docker-specific information, it is recommended to see [Source installation](./source-installation.md) as well if you need detailed information. + Before proceeding, confirm and agree with the [NVIDIA Deep Learning Container license](https://developer.nvidia.com/ngc/nvidia-deep-learning-container-license). By pulling and using the Autoware Open AD Kit images, you accept the terms and conditions of the license. -Here are two ways to install Autoware by docker: +## Prerequisites -- The first way is to start Autoware with `prebuilt image`, this is a quick start, this way you can only run Autoware simulator and not develop Autoware, it is only suitable for beginners +- Docker +- NVIDIA Container Toolkit (preferred) +- NVIDIA CUDA 12 compatible GPU Driver (preferred) -- The second way is to start Autoware with `devel image`, which supports developing and running Autoware using docker +The [setup script](../setup-dev-env.sh) will install all required dependencies with the setup script: -## Docker installation for quick start +```bash +./setup-dev-env.sh -y docker +``` -[docker installation for quick start](./docker-installation-prebuilt.md) +To install without **NVIDIA GPU** support: -![type:video](https://youtube.com/embed/3KUhEFkEbI8) +```bash +./setup-dev-env.sh -y --no-nvidia docker +``` +!!! info -## Docker installation for development + GPU acceleration is required for some features such as object detection and traffic light detection/classification. For details of how to enable these features without a GPU, refer to the [Running Autoware without CUDA](../how-to-guides/others/running-autoware-without-cuda.md). -[docker installation for development](./docker-installation-devel.md) +## Usage -![type:video](https://youtube.com/embed/UrSF-VwncGQ) +### Runtime Setup -## Troubleshooting +You can use `run.sh` to run the Autoware runtime container with the map data: + +```bash +./docker/run.sh --map-path path_to_map_data +``` -Here are solutions for a few specific errors: +!!! info -### cuda error: forward compatibility was attempted on non supported hw + You can use `--no-nvidia` to run without NVIDIA GPU support, and `--headless` to run without display that means no RViz visualization. -When starting Docker with GPU support enabled for NVIDIA graphics, you may sometimes receive the following error: +For more launch options you can edit the launch command with `--launch-cmd` option: ```bash -docker: Error response from daemon: OCI runtime create failed: container_linux.go:349: starting container process caused "process_linux.go:449: container init caused \"process_linux.go:432: running prestart hook 0 caused \\\"error running hook: exit status 1, stdout: , stderr: nvidia-container-cli: initialization error: cuda error: forward compatibility was attempted on non supported hw\\\\n\\\"\"": unknown. -ERROR: Command return non-zero exit code (see above): 125 +./docker/run.sh --map-path path_to_map_data --launch-cmd "ros2 launch autoware_launch autoware.launch.xml map_path:=/autoware_map vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit" ``` -This usually indicates that a new NVIDIA graphics driver has been installed (usually via `apt`) but the system has not yet been restarted. A similar message may appear if the graphics driver is not available, for example because of resuming after suspend. +#### Run Autoware simulator + + Inside the container, you can run the Autoware simulation by following these tutorials: -To fix this, restart your system after installing the new NVIDIA driver. + [Planning Simulation](../../tutorials/ad-hoc-simulation/planning-simulation.md) -### Docker with NVIDIA gpu fails to start Autoware on arm64 devices + [Rosbag Replay Simulation](../../tutorials/ad-hoc-simulation/rosbag-replay-simulation.md). -When starting Docker with GPU support enabled for NVIDIA graphics on arm64 devices, e.g. NVIDIA jetson AGX xavier, you may receive the following error: +### Development Setup ```bash -nvidia@xavier:~$ rocker --nvidia --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:humble-latest-cuda-arm64 -... - -Collecting staticx==0.12.3 -Downloading https://files.pythonhosted.org/packages/92/ff/d9960ea1f9db48d6044a24ee0f3d78d07bcaddf96eb0c0e8806f941fb7d3/staticx-0.12.3.tar.gz (68kB) -Complete output from command python setup.py egg_info: -Traceback (most recent call last): -File "", line 1, in -File "/tmp/pip-install-m_nm8mya/staticx/setup.py", line 4, in -from wheel.bdist_wheel import bdist_wheel -ModuleNotFoundError: No module named 'wheel' - -Command "python setup.py egg_info" failed with error code 1 in /tmp/pip-install-m_nm8mya/staticx/ -... +./docker/run.sh --devel ``` -This error exists in current version of rocker tool, which relates to the os_detection function of rocker. +!!! info -To fix this error, temporary modification of rocker source code is required, which is not recommended. + By default workspace mounted on the container will be current directory, you can change the workspace path by `--workspace path_to_workspace`. For development environments without NVIDIA GPU support use `--no-nvidia`. -At current stage, it is recommended to run docker without NVIDIA gpu enabled for arm64 devices: +#### How to Setup a Workspace -```bash -rocker -e LIBGL_ALWAYS_SOFTWARE=1 --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda +1. Create the `src` directory and clone repositories into it. + + ```bash + mkdir src + vcs import src < autoware.repos + ``` + +2. Update dependent ROS packages. + + The dependency of Autoware may change after the Docker image was created. + In that case, you need to run the following commands to update the dependency. + + ```bash + sudo apt update + rosdep update + rosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO + ``` + +3. Build the workspace. + + ```bash + colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release + ``` + + If there is any build issue, refer to [Troubleshooting](../../support/troubleshooting/index.md#build-issues). + +> **To Update the Workspace** +> +> ```bash +> cd autoware +> git pull +> vcs import src < autoware.repos +> vcs pull src +> ``` + +#### Using VS Code Remote Containers for Development + +Using the [Visual Studio Code](https://code.visualstudio.com/) with the [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension, you can develop Autoware in the containerized environment with ease. + +Get the Visual Studio Code's [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension. +And reopen the workspace in the container by selecting `Remote-Containers: Reopen in Container` from the Command Palette (`F1`). + +By default devcontainer assumes NIVIDA GPU support, you can change this by deleting these lines within `.devcontainer/devcontainer.json`: + +```json + "hostRequirements": { + "gpu": true + }, ``` -This tutorial will be updated after official fix from rocker. +```json + "--gpus", "all" +``` -## Tips +## Building Docker images from scratch -### Non-native arm64 System +If you want to build these images locally for development purposes, run the following command: -This section describes a process to run `arm64` systems on `amd64` systems using [`qemu-user-static`](https://github.com/multiarch/qemu-user-static). +```bash +cd autoware/ +./docker/build.sh +``` -Initially, your system is usually incompatible with `arm64` systems. -To check that: +To build without CUDA, use the `--no-cuda` option: -```sh-session -$ docker run --rm -t arm64v8/ubuntu uname -m -WARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64) and no specific platform was requested -standard_init_linux.go:228: exec user process caused: exec format error +```bash +./docker/build.sh --no-cuda ``` -Installing `qemu-user-static` enables us to run `arm64` images on `amd64` systems. +To build only development image, use the `--devel-only` option: -```sh-session -$ sudo apt-get install qemu-user-static -$ docker run --rm --privileged multiarch/qemu-user-static --reset -p yes -$ docker run --rm -t arm64v8/ubuntu uname -m -WARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64) and no specific platform was requested -aarch64 +```bash +./docker/build.sh --devel-only ``` -To run Autoware's Docker images of `arm64` architecture, add the suffix `-arm64`. +To specify the platform, use the `--platform` option: -```sh-session -$ docker run --rm -it ghcr.io/autowarefoundation/autoware-universe:humble-latest-cuda-arm64 -WARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64) and no specific platform was requested -root@5b71391ad50f:/autoware# +```bash +./docker/build.sh --platform linux/amd64 +./docker/build.sh --platform linux/arm64 ``` + +### Using Docker images other than `latest` + +There are also images versioned based on the `date` or `release tag`. +Use them when you need a fixed version of the image. + +The list of versions can be found [here](https://github.com/autowarefoundation/autoware/packages). diff --git a/docs/installation/index.md b/docs/installation/index.md index 7b99b35577f..c7d05f6b822 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -19,16 +19,15 @@ The Autoware Foundation provides no support on other platforms than those listed The minimum hardware requirements given below are just a general recommendation. However, performance will be improved with more cores, RAM and a higher-spec graphics card or GPU core. + Although GPU is not required to run basic functionality, it is mandatory to enable the following neural network related functions: + - LiDAR based object detection + - Camera based object detection + - Traffic light detection and classification + - CPU with 8 cores - 16GB RAM - [Optional] NVIDIA GPU (4GB RAM) -> Although GPU is not required to run basic functionality, it is mandatory to enable the following neural network related functions: -> -> - LiDAR based object detection -> - Camera based object detection -> - Traffic light detection and classification - For details of how to enable object detection and traffic light detection/classification without a GPU, refer to the [Running Autoware without CUDA](../how-to-guides/others/running-autoware-without-cuda.md). ## Installing Autoware @@ -38,11 +37,12 @@ There are two ways to set up Autoware. Choose one according to your preference. If any issues occur during installation, refer to the [Support page](../support). ### 1. Docker installation +Autoware's Open AD Kit containers enables you to +run Autoware easily on your host machine ensuring same environment for all deployments without installing any dependencies. Full Guide on [Docker Installation Setup](autoware/docker-installation.md). -Docker can ensure that all developers in a project have a common, consistent development environment. -It is recommended for beginners, casual users, people who are unfamiliar with Ubuntu. +[Open AD Kit](https://autoware.org/open-ad-kit/) is also the First [SOAFEE Blueprint](https://www.soafee.io/about/charter) for autonomous driving that offers extensible modular containers for making it easier to run Autoware's AD stack on distributed systems. Full Guide on [Open AD Kit Setup](https://autowarefoundation.github.io/open-ad-kit-docs/openadkit_v3/version-3.0/). -For more information, refer to the [Docker installation guide](autoware/docker-installation.md). +Developer containers are also available for developers making it easier to build Autoware from source and ensuring same environment for all developers. ### 2. Source installation