LocalStack Bootstrap

Create empty LocalStack-backed AWS resources first, then use one Rank mutation plan to seed DynamoDB and S3 together.

Source

examples/localstack-bootstrap/types.rank

use aws::DynamoDB::{ Table }

pub SeedRow = Object {
  dataset: string,
  id: string,
  service: string,
  owner: string,
  enabled: bool,
}

pub SeedsTable = Table<SeedRow, `dataset`, `id`>

pub BootstrapBundle = Object {
  generatedBy: string,
  generatedAt: string,
  services: [Object {
    service: string,
    owner: string,
    enabled: bool,
  }],
}

examples/localstack-bootstrap/main.rank

/// Seeds LocalStack-backed DynamoDB and S3 resources in one mutation plan.
/// Shows Mutation::plan, Mutation::commit, and provider mutation effects.

use aws::{ DynamoDB, S3 }
use std::Env
use std::Mutation
use root::types::{ BootstrapBundle, SeedRow, SeedsTable }

SysEnv = Object {
  DYNAMODB_ENDPOINT?: string,
  S3_ENDPOINT?: string,
  ...: string,
}

{ DYNAMODB_ENDPOINT, S3_ENDPOINT } = Env<SysEnv> {}

dynamodb_endpoint = DYNAMODB_ENDPOINT ?? `http://127.0.0.1:4566`
s3_endpoint = S3_ENDPOINT ?? `http://127.0.0.1:4566`

table_name = `BootstrapSeeds`
bucket_name = `rank-bootstrap-seeds`
bundle_key = `bootstrap/services.json`

dynamo_client: aws::DynamoDB::ClientConfig = DynamoDB::createClient({
  region: `us-east-1`,
  endpoint: dynamodb_endpoint,
  credentials: {
    accessKeyId: `test`,
    secretAccessKey: `test`,
  },
})

s3_client: aws::S3::ClientConfig = S3::createClient({
  region: `us-east-1`,
  endpoint: s3_endpoint,
  credentials: {
    accessKeyId: `test`,
    secretAccessKey: `test`,
  },
})

put_web_seed_row: Mutation::Effect<SeedRow> = aws::DynamoDB::Put<SeedsTable> {
  client: dynamo_client,
  tableName: table_name,
}

put_api_seed_row: Mutation::Effect<SeedRow> = aws::DynamoDB::Put<SeedsTable> {
  client: dynamo_client,
  tableName: table_name,
}

put_bundle_seed: Mutation::Effect<BootstrapBundle> = aws::S3::Put<BootstrapBundle> {
  client: s3_client,
  bucket: bucket_name,
  key: bundle_key,
}

web_seed: SeedRow = {
  dataset: `services`,
  id: `web`,
  service: `web`,
  owner: `web-platform`,
  enabled: true,
}

api_seed: SeedRow = {
  dataset: `services`,
  id: `api`,
  service: `api`,
  owner: `payments`,
  enabled: true,
}

bundle_seed: BootstrapBundle = {
  generatedBy: `localstack-bootstrap`,
  generatedAt: `2026-05-13`,
  services: [
    {
      service: web_seed.service,
      owner: web_seed.owner,
      enabled: web_seed.enabled,
    },
    {
      service: api_seed.service,
      owner: api_seed.owner,
      enabled: api_seed.enabled,
    },
  ],
}

pub main = || Mutation::commit(
  Mutation::plan({
    webSeed: put_web_seed_row(web_seed),
    apiSeed: put_api_seed_row(api_seed),
    bundleSeed: put_bundle_seed(bundle_seed),
  }),
  |report| {
    commitStatus: report.status,
    targets: {
      tableName: table_name,
      bucket: bucket_name,
      key: bundle_key,
    },
    operations: report.operations,
  },
)

examples/localstack-bootstrap/rank.toml

manifestVersion = 1

[package]
name = "localstack-bootstrap-example"
version = "0.1.0"
source = "."

[providers]
aws = { path = "../../packages/plugins/aws" }

[security]
allow-provider-capabilities = ["network"]
allow-provider-mutation-exports = ["aws::DynamoDB::Put", "aws::S3::Put"]
allow-env = ["DYNAMODB_ENDPOINT", "S3_ENDPOINT"]

Output

commitStatus: succeeded
targets:
  tableName: BootstrapSeeds
  bucket: rank-bootstrap-seeds
  key: bootstrap/services.json
operations:
  webSeed:
    status: succeeded
  apiSeed:
    status: succeeded
  bundleSeed:
    status: succeeded

Run it

Start LocalStack from the example directory:

cd examples/localstack-bootstrap
docker compose up

Then run the Rank program from the workspace root:

npm run rank -- examples/localstack-bootstrap

If you changed the LocalStack host port, pass matching endpoints:

DYNAMODB_ENDPOINT=http://127.0.0.1:4567 S3_ENDPOINT=http://127.0.0.1:4567 npm run rank -- examples/localstack-bootstrap

Key concepts

• Mutation::plan(...) groups multiple provider writes into one commit boundary.
• Direct effect bindings keep the mutation graph explicit: each plan field calls a named local Mutation::Effect binding.
• Mixed AWS mutations seed DynamoDB rows and an S3 object in the same commit.
• LocalStack-backed workflow keeps the example runnable without touching real AWS resources.