second first commit

docs/getting-started/terraform.md

@@ -0,0 +1,144 @@
+# Terraform with Floci
+
+Terraform can use Floci as a local AWS-compatible endpoint. Terraform sends requests through the standard `hashicorp/aws` provider, while Floci stores and emulates the resources locally. No real AWS account or cloud resources are used.
+
+## Start Floci
+
+```yaml title="docker-compose.yml"
+services:
+  floci:
+    image: floci/floci:latest
+    ports:
+      - "4566:4566"
+    volumes:
+      - ./data:/app/data
+```
+
+```bash
+docker compose up -d
+```
+
+## Configure the AWS provider
+
+Create `provider.tf`:
+
+```hcl
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 6.0"
+    }
+  }
+}
+
+provider "aws" {
+  region     = "us-east-1"
+  access_key = "test"
+  secret_key = "test"
+
+  skip_credentials_validation = true
+  skip_metadata_api_check     = true
+  skip_requesting_account_id  = true
+  s3_use_path_style           = true
+
+  endpoints {
+    dynamodb       = "http://localhost:4566"
+    secretsmanager = "http://localhost:4566"
+    s3             = "http://localhost:4566"
+    sns            = "http://localhost:4566"
+    sqs            = "http://localhost:4566"
+    ssm            = "http://localhost:4566"
+  }
+}
+```
+
+The endpoint must be configured for every AWS service used by the Terraform configuration. See the [services overview](../services/index.md) for the services implemented by Floci.
+
+## Create local AWS resources
+
+Create `main.tf`:
+
+```hcl
+resource "aws_s3_bucket" "app" {
+  bucket = "floci-terraform-example"
+}
+
+resource "aws_sqs_queue" "jobs" {
+  name = "floci-terraform-jobs"
+}
+
+resource "aws_dynamodb_table" "items" {
+  name         = "floci-terraform-items"
+  billing_mode = "PAY_PER_REQUEST"
+  hash_key     = "id"
+
+  attribute {
+    name = "id"
+    type = "S"
+  }
+}
+
+resource "aws_ssm_parameter" "environment" {
+  name  = "/floci/environment"
+  type  = "String"
+  value = "local"
+}
+```
+
+Initialize and apply the configuration:
+
+```bash
+terraform init
+terraform validate
+terraform plan
+terraform apply
+```
+
+Verify a resource through the AWS CLI:
+
+```bash
+aws --endpoint-url http://localhost:4566 \
+  s3api head-bucket --bucket floci-terraform-example
+```
+
+Remove the local resources when finished:
+
+```bash
+terraform destroy
+```
+
+## Terraform state in Floci
+
+Terraform can keep state locally by using its default local backend. For a fully emulated AWS workflow, Floci also supports the S3 backend and DynamoDB locking used by the compatibility suite:
+
+```hcl
+terraform {
+  backend "s3" {
+    bucket                      = "tfstate"
+    key                         = "terraform.tfstate"
+    region                      = "us-east-1"
+    endpoint                    = "http://localhost:4566"
+    dynamodb_endpoint           = "http://localhost:4566"
+    dynamodb_table              = "tflock"
+    access_key                  = "test"
+    secret_key                  = "test"
+    skip_credentials_validation = true
+    skip_region_validation      = true
+    use_path_style              = true
+  }
+}
+```
+
+Create the backend resources before running `terraform init`:
+
+```bash
+aws --endpoint-url http://localhost:4566 s3api create-bucket --bucket tfstate
+aws --endpoint-url http://localhost:4566 dynamodb create-table \
+  --table-name tflock \
+  --attribute-definitions AttributeName=LockID,AttributeType=S \
+  --key-schema AttributeName=LockID,KeyType=HASH \
+  --billing-mode PAY_PER_REQUEST
+```
+
+For a complete automated example covering more services and the full lifecycle, see [`compatibility-tests/compat-terraform`](https://github.com/floci-io/floci/tree/main/compatibility-tests/compat-terraform).