Prerequisites

Before provisioning infrastructure, make sure you have the necessary cloud access and that your local workstation has the required software installed.

1 Obtain Cloud Access

If you're working within an existing organization, ensure you have sufficient access to the accounts you'll be managing.

If you're provisioning the infrastructure from scratch, you'll need the AWS root account credentials as part of the bootstrapping process before AWS Single Sign-On is set up.

• AWS SSO Access (talk to your AWS administrator)
• Ensure you can log in to AWS. See How to Use Leapp to Authenticate with AWS to get started.

2 Setup Your Workstation

Prerequisites for your local host computer:

• Docker installed (to run our tools)
• Slack installed (to communicate with our team)
• make installed, preferably GNU Make
• git installed
• Leapp for authentication

macOS

Homebrew Users

We typically ship a Brewfile with a list of local dependencies. Make sure you have Homebrew and use brew bundle to install dependencies from the Brewfile

1. First, make sure you’ve cloned the infrastructure repository for your organization.

2. Just run brew bundle install to install all localhost dependencies. Here's an example Brewfile we typically include in the infrastructure repository.

   brew "atmos"
   brew "coreutils"
   brew "pre-commit"
   brew "terraform-docs"
   brew "opentofu"
   brew "tflint"

3. Next, you'll need docker set up. There are a variety of ways to do this. Review the Docker for Desktop installation guide for macOS.

Windows

Docker on Windows

Setting up containers on Windows

1. Install Docker Desktop or install Rancher Desktop and configure it to use docker instead of nerdctl.
2. If you picked Docker Desktop, follow instructions on WSL setup, otherwise follow Rancher's setup docs.

Using Ubuntu on Windows

1. First, setup WSL2 and then configure WSL to use version 2 by default with this command: wsl --set-default-version 2
2. Install Ubuntu for Windows
3. Install Windows terminal
4. Launch Ubuntu shell from Windows Terminal
5. Add user to Docker
6. If you chose to use Rancher, just install docker. If you chose to use Docker Desktop, you'll need to go into settings and enable your Ubuntu distro. Once applied, you'll see docker available in your Ubuntu shell PATH.

Running Geodesic on Windows

1. You'll need an editor that supports WSL2. VSCode and most JetBrains IDEs support WSL2 using remote development plugins.
2. Clone this repo into your WSL2 environment
3. Install curl and build-essential with apt-get
4. Launch your editor's remote development mode and open the repo
5. You should now be able to run make all and have it build the container and launch a shell inside it

Linux

Docker on Linux Systems

You should be able to use docker as normal. Launch docker before running the Makefile.

Linux users should run Docker in "rootless" mode. In this mode, the Docker daemon runs as the host user (rather than as root) and files created by the root user in Geodesic are owned by the host user on the host. Not only does this configuration solve this issue, but it provides much better system security overall.

3 Clone Infrastructure Repository

The infrastructure is where you'll find all the code to provision the reference architecture. You'll need to clone this repository to your local workstation.

git clone https://github.com/$org/$repo.git

4 Build the Geodesic Toolbox Container

Geodesic is a toolbox container that provides an interactive and consistent environment for executing infrastructure commands, similar to a devcontainer. It includes essential tools like terraform, atmos, and AWS CLI.

Build this container before provisioning infrastructure.

make all

This will build the container and launch a shell inside it. You can now start provisioning infrastructure.

What comes next?

With your repository set up and toolbox container.

Next Step