# Develop Terraform Locally

Use this guide when you need to run `terraform plan` or `tofu plan` locally against infrastructure managed by Bluebricks, for debugging or state inspection.

{% hint style="info" %}
For background on how Bluebricks manages Terraform state and artifacts, see [Terraform/OpenTofu](https://docs.bluebricks.co/bluebricks-documentation/core-concepts/packages/artifacts-overview/terraform-open-tofu) in the main documentation.
{% endhint %}

## Before you begin

* At least one blueprint is deployed to a Bluebricks environment. If you haven't deployed one yet, follow the [Quick Start](https://docs.bluebricks.co/bluebricks-documentation/getting-started/quick-start) tutorial
* The Bricks CLI is installed and authenticated (`bricks whoami` returns your user)
* You have access to the git repository containing the Terraform or OpenTofu source code

{% hint style="warning" %}
This procedure works against your **live remote state**. Review all planned changes carefully before applying anything. Use this for debugging and inspection, not production changes.
{% endhint %}

## Step-by-step

{% stepper %}
{% step %}

#### Navigate to the source code directory

Clone or open your artifact's git repository and navigate to the directory containing your `.tf` files:

```
.                          <-- Artifact root directory
├── bricks.json
└── src
    └── terraform          <-- Navigate here
        ├── locals.tf
        ├── main.tf
        ├── outputs.tf
        ├── variables.tf
        └── vpc.tf
```

{% endstep %}

{% step %}

#### Run `bricks bp state-config`

Replace `<ENVIRONMENT_SLUG>` with your environment's slug (visible in the Bluebricks app on the environment page):

```bash
bricks bp state-config <ENVIRONMENT_SLUG>
```

This generates two files in your current directory:

* **`backend.tf`**: remote state backend configuration (contains a temporary JWT)
* **`bbx-terraform-temp.auto.tfvars`**: properties from the last successful run (if applicable)
  {% endstep %}

{% step %}

#### Review the generated files

Open `backend.tf` and `bbx-terraform-temp.auto.tfvars` and confirm they match your expectations before proceeding.
{% endstep %}

{% step %}

#### Initialize and plan

Run `terraform init` (or `tofu init`) followed by `terraform plan` (or `tofu plan`):

```bash
terraform init
terraform plan
```

Confirm your local environment matches the deployed state before making any changes.
{% endstep %}

{% step %}

#### Clean up before publishing

The `backend.tf` file contains your personal JWT token. Remove it before publishing the artifact:

```bash
rm backend.tf
```

To prevent accidental publishing, add `backend.tf` to the `.bricksignore` file in the artifact root directory:

```bash
echo "backend.tf" >> .bricksignore
```

{% endstep %}
{% endstepper %}

## Troubleshooting

**Resources keep being recreated**: your local environment settings (region, project, or account) likely differ from your Terraform configuration. Make sure local environment variables match. For example, set the AWS region:

```bash
export AWS_REGION=eu-north-1
```

Or add explicit provider configuration:

```hcl
provider "aws" {
  region = var.aws_region
}
```

**`bricks bp state-config` fails to create files**: the CLI is not authenticated. Run `bricks login` and try again.

**JWT expired during a long session**: the token in `backend.tf` expires after a period. Re-run `bricks bp state-config <ENVIRONMENT_SLUG>` to generate a fresh token.

## Related

* [Terraform/OpenTofu overview](https://docs.bluebricks.co/bluebricks-documentation/core-concepts/packages/artifacts-overview/terraform-open-tofu) (Docs)
* [Bricks CLI Overview](https://docs.bluebricks.co/bluebricks-documentation/bricks-cli/bricks-cli) (Docs)
* [Packages & Blueprints Troubleshooting](https://bluebricks.co/docs/help/troubleshooting/packages)