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 "https://github.com/atom/atom/releases/download/${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 env.sh _opt_atom/.env.sh
   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, env.sh 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 .env.sh:

     cp env.sh _opt_atom/.env.sh
     

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."
   fi
   

   • 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.

1

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="
   <base_image>:<tag>
   <volume_image_name>:<tag>
"

For more information, see The .aderc File