Usage

The goal of this section is to explain how to use ADE on a project that provides and ADE configuration. See Setup for more information.

ADE Home

ADE needs a directory on the host which will be mounted as the user’s home directory within the container. It will be populated with dotfiles and must be different than the user’s home directory on the host. In case you use ADE for multiple projects it is recommended to use dedicated ADE home directories for each project.

ADE will look for a directory containing a file named .adehome starting with the current working directory and continuing with the parent directories to identify the ADE home directory to be mounted.

mkdir adehome
cd adehome
touch .adehome

Quick start

To start ade, an .aderc file is needed. For an example, see the Autoware.Auto project. For instructions to create an .aderc file for a project, see Setup.

When ade is run for the first time, it will first prompt for an authentication token, and then download all the Docker images configured in the .aderc file

$ cd adehome/path/to/.aderc
$ ade start --update
...
ADE startup completed.
$ ade enter
ade$ <= Note that the prompt changes

CLI

ade

ADE Development Environment.

ade [OPTIONS] COMMAND [ARGS]...

Options

--version
--rc <rc>

Specify a different ADE configuration file. The file should be in adehome or its subdirectories. [default: .aderc]

start

Start environment from within ADE project.

See ade --help for global options (e.g. how to set a non-default aderc)

ADDARGS are directly passed to docker run. To pass options, separate them with -- from the preceding ade options.

See https://docs.docker.com/engine/reference/commandline/run/ and Custom docker run arguments for more information.

ade start [OPTIONS] [ADDARGS]...

Options

--update, --no-update

Pull docker registries for updates. Using –update will imply –force.

--enter, --no-enter

Enter environment after starting.

-f, --force, --no-force

Force restart of running environment.

--select <select>

Select image tags to be used instead of configured defaults. Valid image tags are git tags and branches. To select one for a specific image use IMAGE:TAG (e.g. ade:ftr123) and only TAG to select it for all images for which it exists (e.g. release-42).

Arguments

ADDARGS

Optional argument(s)

enter

Enter environment, running optional command.

ade enter [OPTIONS] [CMD]

Options

-u, --user <user>

Enter ade as given user (e.g. root) instead of default

Arguments

CMD

Optional argument

Environment variables

ADE_ENTER_CMD

Provide a default for CMD

stop

Stop ade environment.

ade stop [OPTIONS]

save

Save configuration and images of running ADE into DIRECTORY.

ade save [OPTIONS] DIRECTORY

Arguments

DIRECTORY

Required argument

load

Load images from DIRECTORY.

ade load [OPTIONS] DIRECTORY

Arguments

DIRECTORY

Required argument

update-cli

Update ade command-line interface.

ade update-cli [OPTIONS]

Options

--finish-update <finish_update>

Used internally by update mechanism

Environment Variables

It is also possible to configure the default behavior of ade using environment variables and the .aderc file. For more information, see Configuring ADE with environment variables and The .aderc File.

Cleanup

Over time, unused Docker images, containers, and volumes will clutter the machine’s hard drive. ADE does not store anything valuable inside the Docker containers, so it is possible to use native Docker commands to clean up. Anything valuable that needs to persist should be placed in ade-home, which is stored on the host and mounted in ADE.

To get an overview of Docker’s disk usage, run:

$ docker system df
TYPE                TOTAL               ACTIVE              SIZE                RECLAIMABLE
Images              13                  11                  14.03GB             916.9MB (6%)
Containers          11                  0                   2.311MB             2.311MB (100%)
Local Volumes       17                  15                  5.411GB             17.8MB (0%)
Build Cache         0                   0                   0B                  0B

Docker provides a cleanup command that will remove everything that is unused. To properly determine what is unused, make sure that all Docker containers you want to keep are running. To avoid having to re-download ADE images, run ade start. Once you are certain that everything you want to keep is in use, run:

$ docker system prune -a --volumes

Debugging

To see the native Docker commands and other commands ade is executing, set the ECHO variable before running ade, e.g.

$ ECHO=1 ade start

Starting multiple ADE instances

When working on multiple projects with ADE configurations, it is desired to keep an instance of ADE running for each project. To run multiple instance, use the ADE_NAME environment variable to switch between the two instances. e.g.

Let’s say that there are two project minimal-ade and AutowareAuto, cloned in ade-home:

Note

It is recommended to keep separate ADE homes for each project; however, nothing prevents using the same ADE home for two projects.

Start the ADE instance for minimal-ade:

$ cd ~/ade-home/minimal-ade
$ export ADE_NAME=minimal
$ ade start

Then start the ADE instance for AutowareAuto:

$ cd ~/ade-home/AutowareAuto
$ export ADE_NAME=aw
$ ade start

Now, in a new terminal, it is possible to select the ADE instance by setting ADE_NAME:

$ cd ~/ade-home
$ export ADE_NAME=minimal
$ ade enter
minimal$ # Inside minimal ADE prompt
Note

The hostname in the ADE container will match ADE_NAME, indicating the current ADE instance

Similarly, specifc ADE instances can be stopped:

$ cd ~/ade-home
$ export ADE_NAME=aw
$ ade stop
Stopping aw
...

Limitations

Starting multiple ADE works well when using the default network configuration; however, ADE instances may conflict if they use custom network configurations: