Tooling Setup

Last updated on 2026-07-30 | Edit this page

Overview

Questions

  • What tools do I need installed to work with this infrastructure?
  • How do the three repositories fit together on my local machine?
  • How do I configure AWS credentials for the correct profile?

Objectives

  • Install and verify Terraform, Ansible, AWS CLI, and Make.
  • Configure an AWS credentials profile named ucla-library-dsc.
  • Clone all three repositories and orient yourself in each.
  • Run terraform init and confirm Ansible can reach a target host.

What you need

Five tools are required before you can work with this infrastructure:

Tool Purpose Version
Terraform Provision AWS resources >= 1.5
Ansible Configure the EC2 instance >= 2.14
AWS CLI Authenticate to AWS, access S3 >= 2.x
Make Run Makefile targets system
uv Python package manager, runs the integration test suite latest

Installation instructions are on the Setup page.

AWS credentials

All AWS calls go through the ucla-library-dsc named profile. This includes:

  • Terraform, which creates and destroys resources
  • The baseline scripts, which read S3 object counts
  • Any direct aws CLI commands you run

Set the profile with an environment variable:

BASH 

export AWS_PROFILE=ucla-library-dsc

The Makefile and scripts default to ucla-library-dsc if AWS_PROFILE is not set, but setting it explicitly avoids surprises when running commands outside the Makefile.

To verify your credentials are working:

BASH 

aws sts get-caller-identity --profile ucla-library-dsc

A successful response shows your IAM user or role ARN, account ID, and user ID.

Callout

Jamie’s profile may differ

Jamie’s AWS profile may use a different name than ucla-library-dsc. The Makefile reads from ${AWS_PROFILE:-ucla-library-dsc}, so setting AWS_PROFILE in your shell before running any make target is the safest approach for both operators.

Cloning the repositories

dataverse-infrastructure is the orchestration repo – clone it first, then let it clone the other two as children of itself. It has a bootstrap target for exactly this:

BASH 

git clone https://github.com/ucla-data-science-center/dataverse-infrastructure
cd dataverse-infrastructure
make bootstrap

make bootstrap clones terraform-dataverse and dataverse-ansible into the dataverse-infrastructure directory (not as siblings next to it) and wires up an upstream remote on dataverse-ansible pointing at the generic gdcc/dataverse-ansible role this one is forked from. The Makefile’s paths (terraform-dataverse/environments/$(ENV), dataverse-ansible) all assume this nested layout – if you clone the child repos somewhere else, nothing in the Makefile will find them.

Initializing Terraform

From inside your operator environment directory:

BASH 

cd terraform-dataverse/environments/tim   # or jamie
terraform init

terraform init does three things:

  • Downloads the AWS provider plugin
  • Configures the remote state backend (an S3 bucket where Terraform stores its state file)
  • Validates the configuration syntax

After init, run:

BASH 

terraform plan

This shows what Terraform would create, change, or destroy – without making any changes. Read the plan output before running terraform apply. A plan that shows unexpected deletions is worth pausing on.

Setting up Ansible Vault

Secrets in group_vars (database passwords, admin passwords, API tokens) are encrypted with Ansible Vault. Before Ansible can decrypt them, you need a local vault password file:

BASH 

cd dataverse-ansible
openssl rand -base64 24 > .vault-password

.vault-password is gitignored – it never gets committed, and if you lose it the vault-encrypted secrets in group_vars are unrecoverable. Save its contents somewhere durable (a password manager, not just your laptop) before doing anything else. Without this file, ansible-playbook fails the moment it hits a vaulted variable.

Verifying Ansible

Ansible runs against an inventory file generated by Terraform. After terraform apply, Terraform writes an inventory file to a path the Makefile knows about.

To check Ansible can reach the host:

BASH 

ansible -i <inventory-file> all -m ping

A successful response: dataverse | SUCCESS => {"ping": "pong"}

If this fails, the most common causes are:

  • SSH key not loaded (ssh-add ~/.ssh/your-key)
  • Security group not open on port 22 (check in AWS console or Terraform config)
  • EC2 instance not yet fully booted (wait 60 seconds and retry)
Challenge

Credentials check

Run the AWS identity check and terraform init commands above. If either fails, note the error message and check the Setup troubleshooting section. The most common issues are a missing profile in ~/.aws/credentials or a role without sufficient IAM permissions.

Challenge

Two ways to fail before you even start

Without checking the episode, answer from memory:

  1. You clone dataverse-infrastructure and run git clone on the other two repos yourself, as siblings next to it. Then you run make rebuild ENV=tim. What happens, and why?
  2. You have all three repos cloned correctly and terraform apply succeeds. Then ansible-playbook fails immediately on a vaulted variable. What file is missing, and what command creates it?
  1. The Makefile can’t find terraform-dataverse or dataverse-ansible – it expects them cloned inside dataverse-infrastructure (via make bootstrap), not as sibling directories next to it. Targets fail with missing-path errors.
  2. dataverse-ansible/.vault-password is missing. Create it with openssl rand -base64 24 > .vault-password from inside dataverse-ansible, and save a copy somewhere durable – if it’s lost, the vaulted secrets can’t be recovered.
Key Points
  • Five tools required: Terraform, Ansible, AWS CLI, Make, uv.
  • AWS profile is ucla-library-dsc – set AWS_PROFILE in your shell before running anything.
  • Clone dataverse-infrastructure first, then run make bootstrap – it nests the other two repos inside it. They are not siblings.
  • Ansible Vault needs a local .vault-password file (openssl rand -base64 24 > .vault-password in dataverse-ansible) before any vaulted group_vars can be decrypted.
  • terraform init must succeed before any other Terraform command will work.
  • terraform plan is always safe – it shows changes without making them.