Skip to content

Latest commit

 

History

History
196 lines (145 loc) · 9.4 KB

customization.md

File metadata and controls

196 lines (145 loc) · 9.4 KB
title author date
Customization(5) | Geodesic
Nuru
January 2025

NAME

Customization - How to customize Geodesic at launch time

SYNOPSIS

Several features of Geodesic can be customized at launch time (rather than during the build of the Docker image) so that people can share an image yet still have things set up the way they like. This document describes how to configure the customization.

DESCRIPTION

A great deal of customization can be implemented by placing shell scripts on the host computer, to be read either at the start of bash profile script processing or at the end of it. These shell scripts can set up environment variables, command aliases, shell functions, etc. and through setting environment variables, can cause Geodesic to enable or disable certain features.

Configuration via Shell Environment Variables and Command Line Options

Nearly all configuration of Geodesic is ultimately done via shell environment variables. See environment(5) for a list of all the environment variables that Geodesic uses. Nearly all of them have corresponding command-line options. For the most part, this document will only refer to the environment variables, and only mention the command-line options when they are different from or have no corresponding environment variable. Here we explain how to derive the command-line options from the environment variables.

In all cases, the command line options relating to environment variables must be introduced with double dashes and be set via =. Boolean options can be set =true with no argument on the command line. Command line options are lower case with words separated by dashes, while environment variables are upper case with words separated by underscores.

Valid:

geodesic --env-file=~/.geodesic/extra-envs
ENV_FILE=~/.geodesic/extra_envs geodesic
geodesic --geodesic-host-bindfs-enabled

Not valid:

geodesic --env-file ~/.geodesic/extra-envs  # would set ENV_FILE to "true" and pass the next argument to Geodesic to run
env-file=~/.geodesic/extra-envs             # not a valid environment variable name
ENV-FILE=~/.geodesic/extra-envs             # not a valid environment variable name

At the moment, underscores are accepted instead of dashes in command line arguments, but this behavior should not be relied on:

Works, but not officially supported:

geodesic --env_file=~/.geodesic/extra_envs

Phases of Configuration

Geodesic configuration is done in two phases:

  1. In phase 1, an installed bash script, referred to as the wrapper(7), configures the docker run command (extensively) and starts the Geodesic container. Command line options, exported shell environment variables, and launch-options.sh files configure the wrapper and the launching of the Geodesic Docker container.
  2. Once the container is running, Geodesic uses some of the same environment variables, plus many others, and reads a series of configuration files to set up the shell environment.

Geodesic's default configuration is fine for casual users, but most power users will want to store their preferences in configuration files on the host machine.

Configuration File Locations

Configuration files can be in several places, with different levels of specificity and priority. However, the first order of business is determining the host machine root directory for configuration files.

Root directory for configuration files

All configuration files (and shell history files generated by Geodesic shells) are stored under the root directory designated by $GEODESIC_CONFIG_HOME. Prior to Geodesic version 4, the default was $HOME/.geodesic. Starting with Geodesic version 4, the default directory is $XDG_CONFIG_HOME/geodesic, which defaults to $HOME/.config/geodesic, per the XDG Base Directory Specification If that default directory does not exist, Geodesic will fall back to $HOME/.geodesic.

Configuration File Types

There are currently 4 file types used for configuration:

  1. launch-options.sh which configure the launching of the Geodesic Docker container. These are read by the Geodesic wrapper script and thus are the first set to be read.
  2. Preferences, which are shell scripts sourced very early in the launch of the Geodesic shell. This is where you configure preferences that affect the behavior of the Geodesic shell.
  3. Overrides, which are shell scripts sourced very late in the launch of the Geodesic shell. This is where you can override settings made by Geodesic or by the preferences files that you were not able to influence earlier or that require the results of the initialization.
  4. bash history files, which store bash command line history so that it persists between shell sessions. Only the last one found is used. If no history file is found, Geodesic will create and use ${GEODESIC_CONFIG_HOME}/history.

For preferences and overrides, you can either provide a file with that name or a directory with that name plus .d, e.g. preferences.d. If a directory, the visible files in the directory will be sourced, unless they match the GEODESIC_AUTO_LOAD_EXCLUSIONS regex, which defaults to (~|.bak|.log|.old|.orig|.txt|.md|.disabled|#)$. This regex is bash Extended Regular Expressions syntax.

You can also configure Geodesic via command line options.

Configuration Directories File Loading Order

Several directories are searched for configuration files, based on the Docker image name. File loaded later override earlier files. Files within a directory are loaded in lexical sort order.

An image name like ghcr.io/cloudposse/geodesic:latest generates the following parts (these are not the actual variable names used):

  • COMPANY=cloudposse
  • STAGE=geodesic
  • DOCKER_IMAGE=cloudposse/geodesic

The directories are searched in the following order:

  1. $GEODESIC_CONFIG_HOME/defaults - the most general configuration files
  2. $GEODESIC_CONFIG_HOME/$COMPANY - company-specific configuration files
  3. $GEODESIC_CONFIG_HOME/$STAGE - stage-specific configuration files
  4. $GEODESIC_CONFIG_HOME/$DOCKER_IMAGE - container-specific configuration files

Prior to Geodesic version 4, $GEODESIC_CONFIG_HOME/ itself would be searched in step 1 if $GEODESIC_CONFIG_HOME/defaults did not exist. As of v4, this is no longer the case, and those files (except for history) will be ignored.

For history files only, if no history file is found in the above directories, Geodesic will create and use ${GEODESIC_CONFIG_HOME}/history. In order to use a different history file, you must create an empty file with that name in the appropriate directory.

Cleanup on Exit

Geodesic, by default, can run multiple shells per container. When a shell exits, Geodesic will run the command specified by ON_SHELL_EXIT, which defaults to geodesic_on_exit. (Prior to Geodesic version 4, the command name was hard-coded.) This is intended to be a command that you write and install to do whatever cleanup you want. For example, change the window title. Note that another way to accomplish nearly the same thing is to use the trap command in your preferences file to run a command when the shell exits.

Starting with Geodesic version 4, there is a similar command ON_CONTAINER_EXIT, that runs when the Geodesic container exits.

The caveat here is that these scripts are run when the wrapper exits, not necessarily when the shell or container exits. This means that if you detach from a shell, the wrapper will run $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 script.

For these reasons, you may prefer to install a command via your preferences file and then set that command to run on shell exit via the trap command:

trap 'geodesic_on_exit' EXIT

The caveat here is that if the shell is killed with kill -9, the trap command will not run. That is less of a problem with Geodesic v4, which is generally able to terminate shells politely (via SIGTERM), but will still be a problem if the container is killed with docker kill.

WARNING

One of the key benefits of Geodesic is that it provides a consistent environment for all users regardless of their local machine. It eliminates the "it works on my machine" excuse. While these customization options can be great productivity enhancements as well as provide the opportunity to install new features to try them out before committing to installing them permanently, they can also create the kind of divergence in environments that brings back the "it works on my machine" problem.

Therefore, we have included an option to disable the customization the preferences and the overrides. You can use the command-line option --no-custom (or --no-customization) to disable them. Alternately, you can set and export the host environment variable $GEODESIC_CUSTOMIZATION_DISABLED to any value other than "false" before launching Geodesic. This can be set in launch-options.sh as launch options themselves are not disabled either way.

TROUBLESHOOTING

If customizations are not being found or are not working as expected, you can use the command line option --trace and a trace of the customization process will be output to the console. Alternatively, you can set the host environment variable $GEODESIC_TRACE to "custom" before launching Geodesic.