Usage¶
The goal of this section is to explain how to use ADE on a project that provides an 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 [GLOBAL_OPTIONS] COMMAND [OPTIONS] -- [ARGS]...
Options
-
--version
¶
-
--rc
<rc>
¶ Specify a different ADE configuration file. The file should be in adehome or its subdirectories. [default: .aderc]
-
--name
<name>
¶ Specify a custome name for the ADE instance [default: ade]
start¶
Start environment from within ADE project.
DOCKER_RUN_ARGS are passed directly to docker run. See https://docs.docker.com/engine/reference/commandline/run/ and Custom docker run/exec arguments for more information.
ade start [OPTIONS] -- DOCKER_RUN_ARGS
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 onlyTAG
to select it for all images for which it exists (e.g.release-42
).
Arguments
-
--
DOCKER_RUN_ARGS
¶ Optional argument(s)
enter¶
Enter environment, running optional command CMD.
DOCKER_EXEC_ARGS are passed directly to docker exec. See https://docs.docker.com/engine/reference/commandline/exec/ and Custom docker run/exec arguments for more information.
To enter a specific ADE instance, set the ADE_NAME
environment variable or the
global option --name
. By default, ade enter
will enter the ade
environment.
If the specified environment is not running, select among the available environments from an interactive prompt.
ade enter [OPTIONS] [CMD] -- DOCKER_EXEC_ARGS
Options
-
-u
,
--user
<user>
¶ Enter ade as given user (e.g. root) instead of default
Arguments
-
CMD
¶
Optional argument
-
--
DOCKER_EXEC_ARGS
¶ Optional argument(s)
Environment variables
-
ADE_ENTER_CMD
Provide a default for
CMD
save¶
Save configuration and images of running ADE into DIRECTORY.
ade save [OPTIONS] DIRECTORY
Arguments
-
DIRECTORY
¶
Required argument
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.
Option Precedence¶
The value of each ade
option is taken from the following sources in order of highest
to lowest precedence:
Command line options (CLI)
Values in The .aderc File
Default values (if any)
For example::
$ export ADE_RC=/path/to/rc
$ ade --rc /path/to/other_rc start # --rc overrides ADE_RC
$ export ADE_NAME="ade2"
$ ade start # starts 'ade2' with configurations from /path/to/rc
$ ade --rc /path/to/other_rc start # starts 'ade2' with configurations from /path/to/other_rc
Note that in the last command the ADE_NAME
environment variable takes precedence over the
ADE_NAME
specified in the aderc
file, because even though the aderc
file is specified
via the command line, the --rc
option only becomes relevant after checking options directly
specified in command line options or via an environemnt variables.
For example::
$ ADE_NAME='envvar' ade --name 'ade_opt' --rc /path/to/rc start # starts 'ade_opt'
$ ADE_NAME='envvar' ade --rc /path/to/rc start # starts 'envvar'
$ ade --rc /path/to/rc start # starts 'ADE_NAME' from '/path/to/rc'
$ ade start # starts 'ade'
Note that arguments to the ADE commands are additive. Specifically, arguments passed to
ade start
will be appended to the values in ADE_DOCKER_RUN_ARGS
, and arguments passed
to ade enter
will be appended to the values in ADE_DOCKER_EXEC_ARGS
.
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.
Let’s say that there are two projects 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=autoware
$ 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$ # minimal ADE prompt
If ADE_NAME
is not defined, the default name ade
is used for a new environment.
In case the specified ADE is not found, ade enter
offers an interactive
prompt to select among the running environments. Press Enter
to select the
environment offered in brackets, or type minimal
and press Enter
to
choose the other option:
$ cd ~/ade-home
$ ade enter
ERROR: An ADE instance named ade is not running.
Select one of {'autoware, minimal'} [autoware]:
Set ADE_NAME to suppress this prompt.
Entering autoware with following images:
...
- Note
The host name in the ADE container will match
ADE_NAME
, indicating the current ADE instance
Similarly, specific ADE instances can be stopped:
$ cd ~/ade-home
$ export ADE_NAME=autoware
$ ade stop
Stopping autoware
...
Limitations¶
Starting multiple ADE works well when using the default network configuration; however, ADE instances may conflict if they use custom network configurations:
If one ADE instance binds to a port (see Custom docker run/exec arguments), a second instance will not be able to bind to the same port.
If one instance uses a Macvlan network (see Starting ADE with macvlan network configuration), a second Macvlan network must be created for the second instance.