Local Development Container

Test and iterate on blueprints locally using the bricks run command before deploying to cloud environments.

What Is Local Blueprint Development?

Local blueprint development enables testing blueprints on your local machine without cloud deployment. Use the bricks run command to execute blueprints locally, validate configuration, and iterate rapidly.

Key Features:

• Local execution without cloud deployment costs

• Rapid iteration on blueprint configuration

• Offline development when cloud access is limited

• Testing and validation before publishing

• Local file references for packages and IaC code

How It Works

The bricks run command executes blueprints locally:

bricks run ./my-blueprint
        ↓
Analyze bricks.json configuration
        ↓
Resolve dependencies and Data references
        ↓
Execute packages locally
        ↓
Outputs returned to local directory

Local execution mirrors cloud deployment behavior but runs entirely on your local machine.

Local File References

Local development supports referencing packages and IaC code using local file paths in bricks.json.

Referencing Local Packages

Reference local packages in the packages array using file paths:

Relative paths:

{
  "packages": [
    {
      "name": "./packages/my-terraform-module",
      "id": "my_module"
    },
    {
      "name": "../shared-blueprints/vpc",
      "id": "shared_vpc"
    }
  ]
}

Absolute paths:

{
  "packages": [
    {
      "name": "/home/user/blueprints/networking",
      "id": "networking"
    },
    {
      "name": "~/workspace/terraform-modules/s3",
      "id": "s3_module"
    }
  ]
}

Explicit file protocol:

{
  "packages": [
    {
      "name": "file://./packages/custom-module",
      "id": "custom"
    }
  ]
}

Referencing IaC Code

Within packages, use the executor field to reference local IaC code:

Terraform/OpenTofu:

{
  "name": "my-terraform-package",
  "version": "1.0.0",
  "executor": {
    "type": "terraform",
    "path": "./src/terraform"
  }
}

Helm:

{
  "name": "my-helm-package",
  "version": "1.0.0",
  "executor": {
    "type": "helm",
    "path": "./src/helm"
  }
}

Generic artifact:

{
  "name": "my-generic-package",
  "version": "1.0.0",
  "executor": {
    "type": "generic",
    "image": "my-custom-image:latest",
    "path": "./scripts"
  }
}

Path Resolution

Local paths are resolved relative to the directory containing bricks.json:

• ./packages/module - Relative to current bricks.json location

• ../shared/module - Relative to parent directory

• ~/workspace/module - Relative to home directory

• /absolute/path/module - Absolute filesystem path

Local Development Workflow

1. Develop Blueprint Locally

Create or modify a blueprint:

cd ~/my-project
# Edit bricks.json, modify packages, etc.

2. Run Locally

Execute the blueprint without cloud deployment:

# Basic local run
bricks run .

# With custom properties
bricks run . --props-file dev-props.json

# Dry run (plan only)
bricks run . --dry

# With verbose output
bricks run . --verbose

3. Iterate and Test

Review outputs, modify code, and test again:

# Review plan
bricks run . --dry

# Apply changes
bricks run .

# Check outputs in ./packages/ directory

4. Publish When Ready

Once validated locally, publish to Bluebricks:

bricks blueprint publish

Local Run Command

Basic Usage

bricks run [package] [flags]

Arguments:

• package - Path to blueprint directory or package name

Common Flags

Execution Control:

--dry              # Create plan without execution
--apply            # Apply plan (default behavior)
--destroy          # Create destroy plan
--verbose          # Print detailed execution steps

Configuration:

--props-file FILE  # Properties JSON file
--props JSON       # Properties as JSON string
--secrets-file     # Secrets JSON file
--secrets JSON     # Secrets as JSON string
--output DIR       # Output directory for artifacts

Advanced:

--deployment GUID  # Deployment ID (for state reference)
--provider NAME    # Cloud provider (aws, gcp, azure)
--token TOKEN      # Backend server-to-server token

Local vs Cloud Execution

Local Execution

When to use:

• Developing new blueprints

• Testing configuration changes

• Validating package composition

• Debugging execution issues

• Offline development

Limitations:

• No cloud resource creation

• Limited cloud provider authentication

• State management is local

• No deployment tracking in Bluebricks

Cloud Execution

When to use:

• Production deployments

• Environment-specific deployments

• Team collaboration

• Persistent state management

• Cloud resource provisioning

Benefits:

• Full cloud provider integration

• Centralized state management

• Deployment history and tracking

• Team visibility

Local Development Examples

Example 1: Single Terraform Package

# Directory structure
my-terraform-module/
├── bricks.json
└── src/
    └── terraform/
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

bricks.json:

{
  "name": "my-terraform-module",
  "version": "1.0.0",
  "executor": {
    "type": "terraform",
    "path": "./src/terraform"
  },
  "props": {
    "region": {
      "type": "string",
      "description": "AWS region"
    }
  }
}

Test locally:

cd my-terraform-module

# Plan
bricks run . --dry --props '{"region":"us-east-1"}'

# Apply
bricks run . --props-file test-props.json

Example 2: Blueprint with Local Packages

# Directory structure
my-infrastructure/
├── bricks.json
└── packages/
    ├── networking/
    │   ├── bricks.json
    │   └── src/terraform/
    └── database/
        ├── bricks.json
        └── src/terraform/

Root bricks.json:

{
  "name": "my-infrastructure",
  "version": "1.0.0",
  "packages": [
    {
      "name": "./packages/networking",
      "id": "vpc",
      "props": {
        "cidr": {
          "value": "Props.vpc_cidr"
        }
      }
    },
    {
      "name": "./packages/database",
      "id": "rds",
      "props": {
        "vpc_id": {
          "value": "Data.vpc.vpc_id"
        }
      }
    }
  ],
  "props": {
    "vpc_cidr": {
      "type": "string",
      "default": "10.0.0.0/16"
    }
  }
}

Test locally:

cd my-infrastructure

# Plan the full stack
bricks run . --dry

# Apply with custom properties
bricks run . --props '{"vpc_cidr":"10.1.0.0/16"}'

Example 3: Mixing Local and Registry Packages

bricks.json:

{
  "name": "hybrid-blueprint",
  "version": "1.0.0",
  "packages": [
    {
      "name": "./packages/custom-vpc",
      "id": "vpc"
    },
    {
      "name": "terraform_aws_s3",
      "id": "s3",
      "version": "2.5.0",
      "props": {
        "bucket_name": {
          "value": "Data.vpc.vpc_id + '-logs'"
        }
      }
    }
  ]
}

Local package (./packages/custom-vpc) and registry package (terraform_aws_s3) work together.

Local State Management

State Location

Local runs store state in output directory:

./packages/
├── <package-id>/
│   ├── state.json
│   ├── plan.json
│   └── outputs.json

State Persistence

Local state:

• Stored in filesystem

• Not uploaded to Bluebricks

• Persists across local runs

• Cleaned manually if needed

Cloud state:

• Stored in HTTP backend

• Accessible across deployments

• Managed by Bluebricks

• Persistent and versioned

Clear Local State

# Remove local state
rm -rf ./packages/

# Fresh run
bricks run .

Testing Best Practices

Development Cycle

1. Write/Modify Blueprint

   • Edit bricks.json

   • Update package references

   • Modify properties

2. Plan Locally

   bricks run . --dry

   • Review execution plan

   • Check dependency resolution

   • Validate configuration

3. Apply Locally

   bricks run .

   • Execute blueprint

   • Review outputs

   • Check for errors

4. Iterate

   • Fix issues

   • Adjust configuration

   • Repeat plan/apply

5. Publish

   bricks blueprint publish

Property Testing

Test with different property sets:

# Development props
bricks run . --props-file dev-props.json

# Staging props
bricks run . --props-file staging-props.json

# Production props (validation only)
bricks run . --props-file prod-props.json --dry

Configuration Testing

Test different configuration scenarios:

# Test with different property values
bricks run . --props-file dev-props.json
bricks run . --props-file staging-props.json

# Validate package references resolve correctly
bricks run . --dry --verbose

Local Development Limitations

Cloud Resource Creation

Local development does not create actual cloud resources:

• Terraform/Helm/Bicep plans are generated

• Generic artifacts execute containers

• No AWS/GCP/Azure API calls made

• State is local only

Cloud Authentication

Limited cloud provider authentication:

• No automatic cloud credential injection

• Must configure cloud credentials locally

• Some executors may require manual setup

State Synchronization

Local state is not synced:

• State stays on local machine

• Not visible in Bluebricks dashboard

• Team members cannot see local runs

• Must publish and deploy to cloud for shared state

Deployment Tracking

Local runs are not tracked:

• No deployment history

• No status monitoring in UI

• No log streaming to Bluebricks

• Purely local execution

Transitioning to Cloud

From Local to Cloud Deployment

# Test locally
bricks run . --dry
bricks run .

# Publish blueprint
bricks blueprint publish

# Deploy to cloud environment
bricks install ./my-blueprint --collection development

# Verify in cloud
bricks deploy list

Reusing Local Configuration

Local props files work in cloud:

# Local
bricks run . --props-file my-props.json

# Cloud
bricks install ./my-blueprint \
  --collection production \
  --props-file my-props.json

Best Practices

Local Development

• Test all changes locally before publishing

• Use props files for different scenarios

• Keep local state clean between major changes

• Run dry-run before apply for complex blueprints

Property Management

• Create separate props files for each environment

• Test with production-like properties

• Validate required properties locally

• Document property requirements

Iteration Speed

• Use local runs for rapid iteration

• Reserve cloud deployments for validation

• Test edge cases locally first

• Publish only after local validation

Team Workflow

• Share props files in version control

• Document local testing procedures

• Establish testing checklist before publishing

• Use cloud deployments for team collaboration

See also

• Creating Blueprints -- blueprint structure and publishing

• Self-Hosted Runner -- production orchestration setup

• Bricks CLI overview -- CLI installation and bricks run reference