From 6f663996599c488fd3805da623d81c4d2aa2dc2b Mon Sep 17 00:00:00 2001 From: oguzkaganozt Date: Wed, 6 Mar 2024 20:13:25 +0300 Subject: [PATCH] docs(installation): update the installation instructions (#516) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Oguz Signed-off-by: M. Fatih Cırıt --- .../autoware/docker-installation-devel.md | 152 --------------- .../autoware/docker-installation-prebuilt.md | 35 ---- .../autoware/docker-installation.md | 175 +++++++++++------- .../autoware/source-installation.md | 21 +-- docs/installation/index.md | 19 +- 5 files changed, 132 insertions(+), 270 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..308f8f56e11 100644 --- a/docs/installation/autoware/docker-installation.md +++ b/docs/installation/autoware/docker-installation.md @@ -1,106 +1,155 @@ -# Docker installation +# Open AD Kit: containerized workloads for Autoware -!!! info +Open AD Kit offers two types of Docker image to let you get started with Autoware quickly: `devel` and `runtime`. - Since this page explains Docker-specific information, it is recommended to see [Source installation](./source-installation.md) as well if you need detailed information. +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. -Here are two ways to install Autoware by docker: +!!! info -- 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 + 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. -- The second way is to start Autoware with `devel image`, which supports developing and running Autoware using docker +## Prerequisites -## Docker installation for quick start +- Docker +- NVIDIA Container Toolkit (preferred) +- NVIDIA CUDA 12 compatible GPU Driver (preferred) -[docker installation for quick start](./docker-installation-prebuilt.md) +The [setup script](https://github.com/autowarefoundation/autoware/blob/main/setup-dev-env.sh) will install all required dependencies with the setup script: -![type:video](https://youtube.com/embed/3KUhEFkEbI8) +```bash +./setup-dev-env.sh -y docker +``` -## Docker installation for development +To install without **NVIDIA GPU** support: -[docker installation for development](./docker-installation-devel.md) +```bash +./setup-dev-env.sh -y --no-nvidia docker +``` -![type:video](https://youtube.com/embed/UrSF-VwncGQ) +!!! info -## Troubleshooting + 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). -Here are solutions for a few specific errors: +## Usage -### cuda error: forward compatibility was attempted on non supported hw +### Runtime setup -When starting Docker with GPU support enabled for NVIDIA graphics, you may sometimes receive the following error: +You can use `run.sh` to run the Autoware runtime container with the map data: ```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 ``` -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. - -To fix this, restart your system after installing the new NVIDIA driver. +!!! info -### Docker with NVIDIA gpu fails to start Autoware on arm64 devices + 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 on arm64 devices, e.g. NVIDIA jetson AGX xavier, you may receive the following error: +For more launch options you can edit the launch command with `--launch-cmd` option: ```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 --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 error exists in current version of rocker tool, which relates to the os_detection function of rocker. +#### Run the Autoware tutorials + +Inside the container, you can run the Autoware tutorials by following these links: -To fix this error, temporary modification of rocker source code is required, which is not recommended. +[Planning Simulation](../../tutorials/ad-hoc-simulation/planning-simulation.md) -At current stage, it is recommended to run docker without NVIDIA gpu enabled for arm64 devices: +[Rosbag Replay Simulation](../../tutorials/ad-hoc-simulation/rosbag-replay-simulation.md). + +### Development setup ```bash -rocker -e LIBGL_ALWAYS_SOFTWARE=1 --x11 --user --volume $HOME/autoware -- ghcr.io/autowarefoundation/autoware-universe:latest-cuda +./docker/run.sh --devel ``` -This tutorial will be updated after official fix from rocker. +!!! info + + 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`. + +#### How to set up a workspace + +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 + ``` -## Tips +3. Build the workspace. -### Non-native arm64 System + ```bash + colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release + ``` -This section describes a process to run `arm64` systems on `amd64` systems using [`qemu-user-static`](https://github.com/multiarch/qemu-user-static). + If there is any build issue, refer to [Troubleshooting](../../support/troubleshooting/index.md#build-issues). -Initially, your system is usually incompatible with `arm64` systems. -To check that: +> **To Update the Workspace** +> +> ```bash +> cd autoware +> git pull +> vcs import src < autoware.repos +> vcs pull src +> ``` -```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 +#### 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 NVIDIA GPU support, you can change this by deleting these lines within `.devcontainer/devcontainer.json`: + +!!! warning + + Under Construction + +## Building Docker images from scratch + +If you want to build these images locally for development purposes, run the following command: + +```bash +cd autoware/ +./docker/build.sh ``` -Installing `qemu-user-static` enables us to run `arm64` images on `amd64` systems. +To build without CUDA, use the `--no-cuda` 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 --no-cuda ``` -To run Autoware's Docker images of `arm64` architecture, add the suffix `-arm64`. +To build only development image, use the `--devel-only` 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 --devel-only ``` + +To specify the platform, use the `--platform` option: + +```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/autoware/source-installation.md b/docs/installation/autoware/source-installation.md index be77bc31d74..374e6e19857 100644 --- a/docs/installation/autoware/source-installation.md +++ b/docs/installation/autoware/source-installation.md @@ -20,7 +20,7 @@ sudo apt-get -y update sudo apt-get -y install git ``` -> Note: If you wish to use ROS 2 Galactic on Ubuntu 20.04, refer to installation instruction from [galactic](https://autowarefoundation.github.io/autoware-documentation/galactic/installation/autoware/source-installation/) branch, but be aware that Galactic version of Autoware might not have latest features. +> Note: If you wish to use ROS 2 Galactic on Ubuntu 20.04, refer to installation instruction from [galactic](https://autowarefoundation.github.io/autoware-documentation/galactic/installation/autoware/source-installation/) branch, but be aware that Galactic version of Autoware might not have the latest features. ## How to set up a development environment @@ -51,17 +51,16 @@ sudo apt-get -y install git The following items will be automatically installed. If the ansible script doesn't work or if you already have different versions of dependent libraries installed, please install the following items manually. + - [Install Build Tools](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/build_tools#manual-installation) + - [Install Dev Tools](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/dev_tools#manual-installation) + - [Install gdown](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/gdown#manual-installation) + - [Install geographiclib](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/geographiclib#manual-installation) + - [Install pacmod](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/pacmod#manual-installation) + - [Install the RMW Implementation](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/rmw_implementation#manual-installation) - [Install ROS 2](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/ros2#manual-installation) - [Install ROS 2 Dev Tools](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/ros2_dev_tools#manual-installation) - - [Install the RMW Implementation](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/rmw_implementation#manual-installation) - - [Install pacmod](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/pacmod#manual-installation) - - [Install Autoware Core dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/autoware_core#manual-installation) - - [Install Autoware Universe dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/autoware_universe#manual-installation) - - [Install pre-commit dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/pre_commit#manual-installation) - - [Install Nvidia CUDA](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/cuda#manual-installation) - [Install Nvidia cuDNN and TensorRT](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/tensorrt#manual-installation) - - If you didn't use ansible script you will need to download some package artifacts as explained in [Manual loading of artifacts](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/artifacts). Otherwise some packages (mostly from perception) will not be able to run as they need these artifacts for the inference. + - [Download the Artifacts](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/artifacts) (for perception inference) ## How to set up a workspace @@ -145,7 +144,7 @@ sudo apt-get -y install git In addition to the traditional command-line methods of building Autoware packages, developers and users can leverage the Autoware Build GUI for a more streamlined and user-friendly experience. This GUI application simplifies the process of building and managing Autoware packages. -### Integration with Autoware Source Installation +### Integration with Autoware source installation When using the Autoware Build GUI in conjunction with the traditional source installation process: @@ -154,7 +153,7 @@ When using the Autoware Build GUI in conjunction with the traditional source ins This integration offers a more accessible approach to building and managing Autoware packages, catering to both new users and experienced developers. -### Getting Started with Autoware Build GUI +### Getting started with Autoware Build GUI 1. **Installation:** Ensure you have installed the Autoware Build GUI. [Installation instructions](https://github.com/autowarefoundation/autoware-build-gui#installation). 2. **Launching the App**: Once installed, launch the Autoware Build GUI. diff --git a/docs/installation/index.md b/docs/installation/index.md index 7b99b35577f..b8f6aa1b9dc 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 @@ -39,10 +38,12 @@ If any issues occur during installation, refer to the [Support page](../support) ### 1. Docker installation -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. +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). + +[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