Skip to content

USAGE.md

Latest commit

 

History

History
116 lines (85 loc) · 6.02 KB

USAGE.md

File metadata and controls

116 lines (85 loc) · 6.02 KB

Usage Guide

This repository provides a starter kit for deploying the FilmDrop AWS infrastructure via Terraform. It includes pre-configured CI/CD workflows, security best practices, and automated infrastructure deployment patterns.

FilmDrop Documentation:

Overview

FilmDrop is a cloud-native geospatial data platform built on AWS. This starter kit simplifies the deployment process by providing:

  • Pre-configured Terraform modules for FilmDrop infrastructure
  • GitHub Actions workflows for automated planning and deployment
  • OIDC-based authentication with AWS (no long-lived credentials)
  • Multi-environment support (dev, staging, prod)
  • Security scanning and validation with pre-commit hooks

Quick Start

Note: This starter kit is configured for a dev environment deployment. After successfully deploying dev, you can extend the setup for additional environments (staging, prod, etc.) as needed.

  1. Clone this repository as a template for your deployment
  2. Choose a project name (8 characters or less) - this will be used consistently across all resources and bootstrap activities
  3. Follow the Bootstrap Guide to set up AWS infrastructure and CI/CD (use the same project name)
  4. Configure your infrastructure by updating Terraform variables in inputs/<environment>/ following the filmdrop-aws-tf-modules configuration guide and main.tf
  5. Open a pull request to see planned infrastructure changes
  6. Merge to main to deploy to your dev environment

Repository Structure

.
├── bootstrap/              # One-time setup for AWS and CI/CD
│   ├── cloudformation/     # CloudFormation templates for OIDC and state bucket
│   └── README.md           # Step-by-step bootstrap instructions
├── .github/
│   └── workflows/          # CI/CD workflows for automated deployments
├── backends/               # Terraform backend configurations per environment
├── inputs/                 # Environment-specific inputs and variable files
│   └── dev/
│       └── shared.tfvars
├── scripts/                # Helper scripts for deployment
├── main.tf                 # Terraform infrastructure definitions
├── variables.tf            # Input variable declarations
└── outputs.tf              # Output value definitions

Getting Started

Prerequisites

  • AWS account(s) for each environment you plan to deploy
  • GitHub repository (private recommended for security)
  • AWS CLI installed and configured locally
  • Terraform CLI installed locally (optional, for local development)

Setup Steps

  1. Use this repository as a template

    • Click "Use this template" in GitHub, or clone and push to your own repository
    • Consider keeping the repository private until you can ensure it meets your security posture

  2. Customize organizational files (if needed)

  3. Choose your project name

    • Select a project name that is 8 characters or less
    • This name will be used as a prefix for all AWS resources and during bootstrap
    • Use lowercase letters
    • Use this same project name in all bootstrap commands (below)

  4. Complete the bootstrap process

  5. Configure your FilmDrop infrastructure

    • Update main.tf with your desired FilmDrop AWS Terraform Modules version
    • Create an environment-specific configuration directory in inputs/<environment>/
    • Important: See the FilmDrop AWS Terraform Modules Configuration Guide for detailed instructions on how to customize the FilmDrop input variables file

  6. Test the deployment

    • Create a feature branch with your changes
    • Open a pull request to trigger a Terraform plan
    • Review the planned changes in the workflow output
    • Merge to main to deploy to dev environment
    • Update configuration and repeat as needed

CI/CD Workflows

This repository includes simple starter GitHub workflows that automate your deployment process:

  • Pre-commit validation: Runs terraform fmt, validate, tflint, and security scans automatically before commits
  • Terraform plan: Generates an infrastructure change preview on pull requests, allowing you to review changes before merging
  • Terraform apply: Deploys changes automatically when you merge to the main branch

These workflows are designed to be sufficient for getting started. See .github/workflows/ for implementation details.

Workflow Behavior

  • Pull Requests: Trigger plan only (no infrastructure changes)
  • Merge to Main: Triggers both plan and apply (deploys changes if detected)
  • Authentication: Uses OIDC with AWS (no long-lived credentials stored in GitHub)

Next Steps

After successfully deploying your dev environment, consider:

  • Add additional environments: Replicate the bootstrap and workflow configurations for staging, production, or other environments
  • Customize CI/CD workflows: Modify workflows in .github/workflows/ to match your team's deployment practices (add approval gates, notifications, integration with Slack/email, etc.)
  • Refine configuration: Adjust Terraform variables and module configurations based on your infrastructure requirements, adding complementary AWS resources as needed (CloudWatch alarms, backup policies, etc.)

Support