Geodesic v4.0.0 Release Notes (draft)
Highlights
Better Shell Management
A much requested feature, Geodesic no longer exits the container when the first shell exits.
Instead, the container runs until all shells have exited. This means you can now run multiple shells
inside the container, and exit them in any order; you no longer have to keep track of which
shell was the first one launched. Unfortunately, this also means that you can no longer
detach and reattach to a shell.
However, Geodesic now supports another much requested feature: launching a new container
each time you run Geodesic. This is done by setting the ONE_SHELL environment variable to “true”
or passing --one-shell on the command line. This allows you to run multiple versions of Geodesic,
and also allows you to detach from a shell and reattach to it later.
Not a new feature, but one that many people were not aware of: you can kill the running
Geodesic container with the command geodesic stop. This will stop the container, and it
will be automatically removed (assuming you started it with geodesic). Now, however,
there is the possibility you will have several running containers. If this is the case
geodesic stop will list the running containers by name. You can then pass the
name as an argument to geodesic stop and it will stop that one.
Another old feature few people knew about: you can have Geodesic automatically
run a command when a shell exits. This was done by creating an executable command named
geodesic_on_exit and putting it in your $PATH. This feature has been enhanced
in 2 ways:
- Now, you can set the name of the command to run when the shell exits via
ON_SHELL_EXIT
(defaults to geodesic_on_exit). Also new: the ON_SHELL_EXIT command will have available to it the short ID of the container in which it was running, via the
environment variable GEODESIC_CONTAINER_EXITING. - You can use the new environment variable
ON_CONTAINER_EXIT to configure a different
command to run only when the container exits.
Be aware that the commands are called on a best-effort basis when the Geodesic
launch wrapper exits. If you detach from a shell, the wrapper will run then and
call ON_SHELL_EXIT. If you reattach to the shell, the wrapper is not involved,
so quitting the shell or container will not run the cleanup command.
Alternately, if you quit 2 shells at nearly the same time, the ON_CONTAINER_EXIT
command may be called twice. This is because the wrapper does not know which shell
is the last one to exit; it calls the command when the container has stopped
before shell exit processing has finished.
Better Configuration Management
Geodesic now supports configuration files for customizing the launch of the Geodesic container.
Although Geodesic has for a while been customizable,
the customization you could configure via files were limited to customizations of the
running Docker container. Previously, customizations regarding how Geodesic is launched were difficult to manage.
Now, you can create a launch-options.sh file in the Geodesic configuration directories
to customize the launch of the Geodesic container. The directory search path and the
priority of the files are the same as for the other Geodesic customization files.
Better File System Layout
Geodesic no longer mounts the entire host user’s home directory into the container.
This had been a performance problem and was explicitly discouraged by Docker. Now,
Geodesic mounts only specific directories from the host to the container, and you
have full control over which directories are mounted where (with sensible defaults).
Inspired by the Dev Container, the /localhost directory
has been removed, and the host’s git root directory is mounted to /workspace in the container.
This is all configurable, and some configuration for each project will make it easier to
use multiple projects with Geodesic.
Among other things, this means that your project source directory no longer has to be
under your home directory. You are free to locate it on another drive if you like.
For reasons lost to history, Geodesic set the container user’s home directory to /conf.
This caused some problems for people who wanted to run Geodesic as a non-root user.
The /conf directory has been removed, and the container user’s home directory
(as specified in /etc/passwd) is now honored. By default, Geodesic launches as the
root user, so the default $HOME is /root.
As before, the host user’s home directory path is available in the container as
$LOCAL_HOME, and mounted files and directories are available at the same paths
in the container as on the host.
Breaking Changes
• Previously, $HOME was set to /conf in the container. This is no longer the case.
$HOME is now set to the shell user’s home directory. By default, this is /root.
If you launch Geodesic as a non-root user, $HOME will be set to that user’s home directory,
provided you have properly created the user with adduser. By default, the
container user will share configuration with the host user by mounting the host user’s
configuration directories into the container user’s home directory, allowing
bidirectional updates.
• The /conf directory no longer exists. Generally, what used to be in /conf
is now in /root if it was created in the Geodesic Dockerfile.debian, or in
$HOME (also /root by default) if it was created in the Geodesic startup scripts.
• /conf/.kube/config has been moved to /etc/kubeconfig. It is installed as
/root/.kube/config, but this is now expected to be hidden by mounting the
host user’s $HOME/.kube directory over /root/.kube.
• Previously, if you exited the shell that launched Geodesic, the container would exit,
killing any other running shells. Now, the container will not exit until all shells have exited.
As a side effect, you can no longer reattach to a shell that you have detached from.
You can get something closer to the old behavior by setting ONE_SHELL=true.
See New Default Behavior for Multiple Shells below
for more details.
• Previously, the entire host user’s home directory was mounted into the container under /localhost,
making everything in the host user’s home directory available to the container.
Now, only specific directories are mounted, and they are mounted in the container user’s
$HOME directory. The default directories are .aws, .config, .emacs.d,
.geodesic, .kube, .ssh, and .terraform.d. You can add additional directories by setting
the HOMEDIR_ADDITIONAL_MOUNTS environment variable. See The Home Directory below
for more details.
• Previously, environment variables inside the container could be set in the ~/.geodesic/env file,
which was passed to Docker via --env-file. This file is now ignored. Instead, you should
set environment variables in the customization preferences and overrides.
• The /localhost directory no longer exists. This used to be the single mount point
for the host filesystem, and the host user’s entire $HOME directory was mounted there.
Now, we no longer mount the entire $HOME directory tree into the container. Instead,
we mount specific directories from the host to the container.
• Configuration directories directly under the host user’s $HOME directory
(such as .aws or .config) are mounted to the container user’s $HOME
directory.
• The git repository root directory for the project is mounted to the container’s /workspace directory.
• Additional directories …
