> **Page index:** https://km.oslo.systems/llms.txt lists every page on this site, with a link to its Markdown version.

# Set up remote state

Now that you have created the environment definition file, you can bootstrap the environment.

Terraform state is a file that tracks the resources Terraform has created. By default, this file is stored locally. The bootstrap command creates the S3 bucket and DynamoDB table needed to store Terraform state remotely.

After these steps, you have a foundation for all the other stacks you create inside this environment.

## Step 1: Add and configure the `remote-state` package

repo-iac/environments/dev/

```
ok pkg add remote-state
```

In `package-config.yml`, set `S3Backend` to `false`:

repo-iac/environments/dev/remote-state/package-config.yml

```
StackName: "remote-state"

S3Backend: false
```

## Step 2: Install the package

repo-iac/environments/dev/remote-state/

```
ok pkg install
```

## Step 3: Initialize and apply the `remote-state` stack

Initialize and apply the stack to create the S3 bucket and DynamoDB table:

> [!NOTE]
>
> **SSH Key**
>
> If you haven't already added a SSH key to your GitHub account (or have `gh`(GitHub CLI) configured). See [GitHub SSH key guide](<https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account>) for more information. This is required for Terraform to be able to fetch the modules from the `golden-path-iac` repository.

repo-iac/environments/dev/remote-state/

```
terraform init
terraform apply
```

## Step 4: Verify

Verify that the S3 bucket for storing remote Terraform state was created.

You are looking for a bucket with the following name:

```
ok-iac-config-${local.account_id}-${local.region}-${local.environment}
```

For example:

```
2021-09-01 10:00:00 ok-iac-config-12345678910-eu-west-1-my-team-dev
```

Run the following command:

```
aws s3 ls
```

The list should contain the name of the S3 bucket you just created.

Sign in to the AWS console and navigate to S3.

The list should contain the name of the S3 bucket you just created.

---

## Step 5: Move your current local Terraform state to the S3 backend

You now have remote storage for all future stacks. However, this stack still uses a local state file (`terraform.tfstate`).

Transfer the local state to the S3 bucket by reconfiguring Terraform to use S3 as the backend.

Edit `package-config.yml` and set `S3Backend` to `true`:

repo-iac/environments/dev/remote-state/package-config.yml

```
StackName: "remote-state"

S3Backend: true
```

Reinstall the package:

repo-iac/environments/dev/remote-state/

```
ok pkg install
```

Initialize the new configuration:

repo-iac/environments/dev/remote-state/

```
terraform init -migrate-state -force-copy
```

Verify that everything is working by running `terraform plan`. There should not be any changes to apply at this point:

repo-iac/environments/dev/remote-state/

```
terraform plan
```

Delete `terraform.tfstate` since it's now stored in S3. Removing it makes Terraform use the remote state instead of creating a new local file.

repo-iac/environments/dev/remote-state/

```
rm "terraform.tfstate" && \
rm "terraform.tfstate.backup"
```

> [!TIP]
>
> **Commit your files**
>
> At this stage it is a good idea to commit your files.

You're done with the Terraform setup.

## Next step

Set up [DNS](<https://km.oslo.systems/initial-setup-of-your-aws-environment/set-up-dns/index.md>).