Skip to content
Ezra Buckingham edited this page Jun 24, 2022 · 6 revisions

Disclaimer

Before adding to Terry, you must read and understand all the design paradigms that went into building Terry as some of them will directly impact how you add to the project. You must also already have accounts / API credentials with the cloud providers you want to use.

Getting Started & Warnings

Warning: Since the computer / server that runs Terry will dynamically generate SSH Keys / Certificates / etc, that computer or server MUST BE SECURE. If you are not comfortable with that, stop what you are doing, clap your hands 4 times, and sing Happy Birthday in a southern accent. No just kidding, but you have been warned.

To get started, you have 2 options: Manual Setup, Automated Setup (coming soon, maybe). The Automated setup will set everything up for you (by using Ansible) as long as you are running Debian-based Linux. Also, only run the Automated setup if it is your first time using Terry, as it could mess up previous configuration files (if you have set up Terry in the past). If you are not using Debian-based Linux, that is ok, you will just need to run through the Manual Setup.

Manual Setup

  1. Install all python dependencies by running:
pip install -r requirements.txt
  1. Copy the config_example.yml file to config.yml (as Terry will default to looking for the config at that location, but you can put it elsewhere and ust the -c / --config flag to point Terry to a different location)
cp config_example.yml config.yml
  1. Copy the ./configurations/container_mappings_example.yml file to ./configurations/container_mappings.yml and update it by follwowing the Adding a Container documentation (if you plan to build your resources with containers using the -cT flag)
cp configurations/container_mappings_example.yml configurations/container_mappings.yml
  1. Install Terraform (for the system you are on) or download the Terraform binary (if you download only the binary, make sure you add the path to the config.yml file)
  2. Install Ansible (for the system you are on) or download the Ansible binary (if you download only the binary, make sure you add the path to the config.yml file)
  3. Install Nebula (for the system you are on) or download the Nebula binary (if you download only the binary, make sure you add the path to the config.yml file). If you will not use Nebula for your builds, ignore this step.

Once all of this is done, you are ready to get started! Check out the Usage Page to learn how to Terry can help you!

Development Paradigms

When developing Terry, I took the liberty of defining the following design paradigms:

  • All sensitive credential values will be set as environment variables for downstream dependencies to access, like Terraform and Ansible (even if erroneously defined in the configuration file, cuz the user hates security)
  • Variables/naming of files must be consistently named across the entire project.
  • Terraform should not do any host configuration. The sole purpose of Terraform is to build a specific resource using a provider (of which can be an ssh key, domain record, serverless function, server, etc).
  • Terry can and should be able to read sensitive values from either command line arguments, environment variables, the configuration file, or from standard input (In that order of precendence). The choice of which to use should be up to the operator.
  • Since all cloud providers have similar offerings, resources should be abstracted from the provider.
    • For example, AWS has EC2 for creating virtual machines in the cloud, but at the core, it is just a server. Terry will expect that you call it a server and not a ec2 when creating the resource file for that provider.
  • Each resource class that is instantiated should validate itself.
    • For Example, a Terraform object should validate that it has a Terraform template to render

Deployed Resource Design Paradigms

When deploying repeatable infrastructure, I took the liberty of defining the following deployment paradigms:

  • Hosts are firewalled using UFW as a host-based firewall (so that we are abstracted away from the cloud's implementation of a firewall)
  • Ansible playbooks assume you are running a recent version of Debian
  • All Software installed directly on the host system is installed at /opt/<software_name>
  • Installed software that normally needs to be started manually via the command line is installed as a Service
    • For example, a DNS redirector uses socat for redirection. To make life easier, Terry will create a dns-redirector service so that socat can run in the background
  • All Containers are deployed to /opt/<container>/<container_name>