Quick start

Get up and running quickly with geodesic



All examples are based on use cases provided in Agenda

Creating a New Module

Name New Module

Geodesic new module should have a name. We recommend to follow this pattern ${stage}.${base_host}. Set the name to $CLUSTER_NAME environment variable.

Example: staging.example.com - where ${stage} = staging and ${base_host} = example.com

Generate Scaffolding

This will create a new module in your current working directory called $CLUSTER_NAME, complete with Dockerfile and Makefile.

export CLUSTER_NAME=staging.example.com

docker run -e CLUSTER_NAME \
           -e DOCKER_IMAGE=cloudposse/${CLUSTER_NAME} \
           -e DOCKER_TAG=dev \
              cloudposse/geodesic:latest -c new-project | tar -xv -C .

Configure Project

Customize module files as necessary. Edit the Dockerfile to reflect your settings. The files are installed to the $CLUSTER_NAME/ folder.

We recommend creating a GitHub repo for each organization to store this configuration.


Build & Install

Initialize the Build Harness

make init

Build the docker container

make docker/build

Install the module as shell

docker run $image | bash -s $tag

Replace $image which the image of the docker image built, and $tag with the corresponding tag of that image.


Do not pass -it when running docker as this will add carriage returns (\r), which breaks the installer script.

Run the shell

The shell can now be easily started any time by simply running the $CLUSTER_NAME script, which is a shell script that gets installed to /usr/local/bin/.


  • Make sure this path is in your PATH environment variable.

Authorize on AWS

Config AWS credentials and roles following Authorization


By default, Geodesic uses AWS Vault to authorize on AWS so ensure you add source profile name to AWS Vault

Set default profile in Geodesic Module

Add to you module Dockerfile :

### Default AWS Profile name
ENV AWS_DEFAULT_PROFILE="example-staging-admin"

Run make docker/build to rebuild module container


You can install it on local to do the same for development purpose. See AWS Vault setup.