---
title: Customization(5) | Geodesic
author:
- Nuru
date: 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)](https://github.com/cloudposse/geodesic/blob/main/docs/environment.md)
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:
```bash
geodesic --env-file=~/.geodesic/extra-envs
ENV_FILE=~/.geodesic/extra_envs geodesic
geodesic --geodesic-host-bindfs-enabled
```

Not valid:
```bash
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:

```bash
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)](wrapper.md),
   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](https://specifications.freedesktop.org/basedir-spec/latest/)
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:

```bash
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.