Creating a custom volume

Writing the Dockerfile

ADE volumes are a way to minimize the size of the base image by loading different resources from a different Docker image. ADE volumes can be used to provide third-party libraries, IDEs, and proprietary programs.

Let’s look at how a volume for Atom can be created 1:

  1. A generic Docker file:

    FROM alpine
    COPY _opt /opt/atom
    VOLUME /opt/atom
    CMD ["/bin/sh", "-c", "trap 'exit 147' TERM; tail -f /dev/null & wait ${!}"]
    • Note the CMD, which is meant to keep the container running even if no one is attached

  2. A script to create /opt/atom:

    #!/usr/bin/env bash
    # Copyright 2018 Apex.AI, Inc.
    # SPDX-License-Identifier: Apache-2.0
    set -xe
    cd "$(dirname "$(realpath "$0")")"
    ADE_VERSION="$1"; shift
    # Download and install Atom
    curl -LO "${ADE_VERSION}/atom-amd64.tar.gz"
    tar xfz atom-amd64.tar.gz
    mv atom-*-amd64 _opt_atom
    chown root:root _opt_atom -R
    mkdir -p _opt_atom/bin
    ln -s ../atom _opt_atom/bin/
    ln -s ../resources/app/apm/bin/apm _opt_atom/bin/
    rm atom-amd64.tar.gz
    # Environment Setup
    cp _opt_atom/
    cp adeinit _opt_atom/.adeinit
    # Use _opt_atom for readability, rename to _opt b/c it's expected by Dockerfile
    mv _opt_atom _opt
    • Usage: ./build-opt 1.35.0

    • This is where the bulk of the work happens:
      • Using the version number provided, the script downloads Atom and installs it into a directory that will become /opt/atom in the Dockerfile:

      COPY _opt /opt/atom
  3. A script to set up the environment on ade enter:

    export PATH="$PATH:/opt/atom/bin"
    export ATOM_HOME="$HOME/.atom"
    export BROWSER='chromium-browser --no-sandbox'
    • At a minimum, needs to add the executable to PATH

    • In this case it sets the location where Atom will store it’s configuration such that they will persiste between restarts of ADE

    • Note that build-opt takes care of copying this file into /opt/atom and naming it

      cp _opt_atom/
  4. A script of commands that should be run during ade start:

    #!/usr/bin/env bash
    if [[ ! -d "${ATOM_HOME}" ]]; then
        echo "Doing initial install of atom plugins:"
        /etc/atom/atom-install-our-plugins || true
        echo "Initial install of atom plugins done."
    • Note that build-opt takes care of copying this file into /opt/atom and naming it .adeinit:

      cp adeinit _opt_atom/.adeinit
    • Note also that .adeinit must be executable (chmod +x .adeinit)

Placing these four files in a Gitlab project and adding a CI script to automate the docker build command, makes it simple to generate new images on demand by creating a git tag for the desired version

For a more complex example, where the software is developed in the same repository, see the AutowareAuto project. AutowareAuto generates ADE volumes which can be used to deploy a pre-built AutowareAuto build in another machine.


The code for this example is kept in this Gitlab project

Building the volume locally

Note: It is recommended to build the image as part of a CI script; nevertheless, the following instructions can be used to test the build steps locally. Make sure to run any setup scripts (e.g. see build-opt above) before building the image.

Build the image by running docker build in the directory that contains the Dockerfile and other necessary resources (e.g. the _opt directory generated by build-opt in the example above):

docker build -t <volume_image_name>:<tag> .

Add --label ade_image_commit_sha=<git-hash> and/or --label ade_image_commit_tag=<git-tag> to embed VCS information in the Docker image:

docker build \
  --label ade_image_commit_sha=<git-hash> \
  --label ade_image_commit_tag=<git-tag> \
  -t <volume_image_name>:<tag> .

For more information, see the docker build documentation

Using the volume

To use the image, add it to the .aderc file after the base image entry in ADE_IMAGES. The order of the volumes does not matter as long as the base image is first:

export ADE_IMAGES="

For more information, see The .aderc File