> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastfoundation.nimble.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Repository Setup & Usage Example

> Manage Fast Foundation configurations and parameters across accounts

<Warning>
  **AWS Single Sign-On (SSO) Required**: This guide assumes your AWS Identity Center (formerly AWS SSO) is already configured. If not, complete the [AWS SSO Setup guide](/aws-sso/1-getting-started-with-aws-single-sign-on-sso) first.
</Warning>

# Repository Setup & Usage Example

<Steps>
  <Step title="Clone the Infrastructure Repository">
    Begin by cloning your organization's Fast Foundation infrastructure repository:

    ```bash theme={null}
    git clone <your-fast-foundation-repo-url>
    cd <fast-foundation-infrastructure-folder>
    ```

    <Note>
      Replace `<your-fast-foundation-repo-url>` with the actual repository URL provided by your team.
    </Note>
  </Step>

  <Step title="Configure Provider Plugin Cache (required)">
    Fast Foundation modules are sourced from a dedicated git repository. Each `terragrunt init` clones the modules and downloads provider plugins. Without caching, the AWS provider alone (\~762MB) gets duplicated in every unit's `.terraform/` directory — with 40+ units this adds up to **tens of gigabytes** of wasted disk space.

    The provider plugin cache stores provider binaries once and hardlinks them into each unit, reducing per-unit storage overhead to effectively **zero**.

    More information can be found in the [official terraform documentation.](https://developer.hashicorp.com/terraform/cli/config/config-file#provider-plugin-cache)

    **Step 1:** Create the cache directory:

    ```bash theme={null}
    mkdir -p ~/.terraform.d/plugin-cache
    ```

    **Step 2:** Create or edit `~/.terraformrc` with these two lines:

    ```hcl theme={null}
    plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"
    plugin_cache_may_break_dependency_lock_file = true
    ```

    <Warning>
      Both lines are required. Without `plugin_cache_may_break_dependency_lock_file`, Terraform copies provider binaries instead of hardlinking them, negating the disk savings.
    </Warning>
  </Step>

  <Step title="Initialize Terragrunt">
    If you have admin permissions to the entire organization, you can initialize the entire repository from the root directory. If not, run this from an account or region folder. Initialize Terragrunt:

    ```bash theme={null}
    terragrunt run --all init --provider-cache
    ```

    <Note>
      The initialization process can take some minutes to finish.
    </Note>

    **What happens here:**

    * Terragrunt initializes the backend for all the units.

    **Expected output:**

    * For each unit that is initialized, you should see:

    ```
    Terraform has been successfully initialized!

    You may now begin working with Terragrunt. Try running "terragrunt plan" inside a terragrunt unit to see any changes that are required for your infrastructure. All Terraform commands should now work.
    If you ever set or change modules or backend configuration for Terragrunt, run this command again to reinitialize your working directory. If you forget, other commands will detect it and remind you to do so if necessary.
    ```
  </Step>

  <Step title="Plan before applying changes">
    Review planned infrastructure changes.
    Move into the **workload-core-development** account directory, we will use the clusters VPC as an example:

    ```bash theme={null}
    cd Workloads/Development/workload-core-development/development/<region>/networking/vpc/clusters
    terragrunt plan
    ```
  </Step>

  <Step title="Apply changes">
    Apply the configuration:

    ```bash theme={null}
    terragrunt apply
    ```

    <Check>
      Your infrastructure changes have been applied successfully.
    </Check>
  </Step>
</Steps>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Permission Errors">
    **Symptoms**: `Access Denied` errors during Terragrunt operations.

    **Possible causes:**

    * SSO (AWS IAM Identity Center) session expired.
    * Misconfigured AWS profile.
    * Missing IAM permissions.

    **Solutions:**

    1. Verify your session: `aws sso login --sso-session fast-foundation`
    2. Check your profile in `~/.aws/config`
    3. Ensure your user/role has the required IAM permissions.
  </Accordion>

  <Accordion title="State Lock Conflicts">
    ### State lock issues

    Terragrunt and Terraform use **DynamoDB locks** to prevent multiple people from applying changes at the same time on the same unit. If you see a state lock error, it usually means someone else is already running a deployment.

    **What to do:**

    * ⏳ Wait for the other deployment to finish.
    * ✅ Verify you’re not overwriting someone else’s changes.
    * 🚀 Apply your changes once you’re sure everything is okay.
  </Accordion>

  <Accordion title="Module Not Found">
    **Symptoms**: Terraform module cannot be downloaded or located.

    **Solutions:**

    1. Run `terragrunt init` again to refresh modules.
    2. Check internet connectivity for module downloads.
    3. Verify module source paths in configuration files.
  </Accordion>
</AccordionGroup>

***

## Want to dive deeper?

Ready to explore these concepts in more detail? Check out our hands-on workshops:

<CardGroup cols={2}>
  <Card title="Deploy an EC2 instance" icon="cube" href="/workshops/1-deploy-ec2-instance">
    Learn step-by-step how to create an EC2 instance with external modules.
  </Card>

  <Card title="Deploy a custom module" icon="cube" href="/workshops/2-deploy-custom-module">
    Learn step-by-step how to create and deploy a custom wrapper module.
  </Card>
</CardGroup>