Local Development Guide

Guide for developing and testing the Zenoo Hub locally without requiring AWS cloud services.

Overview: Two Approaches

The Hub supports two approaches for local development:

Local Provider (Recommended) - In-memory storage with zero dependencies
LocalStack - AWS service emulation for testing AWS-specific behavior

Quick Comparison

Aspect	Local Provider	LocalStack
Setup	1 config line	Docker + configuration
Startup	`<100ms`	~10 seconds
Dependencies	None	Docker, LocalStack image
Memory	Low (~50MB)	High (~500MB)
Persistence	None (volatile)	Optional (volumes)
AWS Accuracy	N/A	~90%
Use Case	Quick dev, testing	AWS behavior testing

When to Use Local Provider

Use local provider when:

Developing features that don’t depend on AWS-specific behavior
Running unit and integration tests
Building CI/CD pipelines
Quick prototyping and experimentation
No need for data persistence
Want instant startup and teardown

Configuration:

hub:
  cloud:
    provider:
      type: local  # That's it!

Complete local provider guide

When to Use LocalStack

Use LocalStack when:

Testing AWS-specific features (DynamoDB queries, TTL, etc.)
Validating AWS configuration before deployment
Testing multi-region behavior
Need persistence between restarts
Developing AWS-specific integrations

Configuration:

hub:
  cloud:
    provider:
      type: aws
  aws:
    region: us-east-1
    dynamodb:
      endpoint: http://localhost:4566

Local Provider Setup

The local provider requires minimal setup and is perfect for most local development scenarios.

1. Add Dependency

Already included in backend-integration-tests and sample-hub-instance:

dependencies {
    implementation project(':backend-spring-boot-starter')
    implementation project(':cloud-provider-local')
}

2. Configure

application-local.yml:

hub:
  cloud:
    provider:
      type: local

  local:
    cleanupEnabled: true
    cleanupInterval: 5m
    verboseLogging: false

# Other Hub configuration...
kafka:
  bootstrap-servers: localhost:9092

3. Run

./gradlew bootRun --args='--spring.profiles.active=local'

The Hub will start instantly with in-memory storage. All data is lost on restart.

Testing with Local Provider

Example Integration Test:

@SpringBootTest
@TestPropertySource(properties = [
    "hub.cloud.provider.type=local"
])
class ComponentStorageTest {

    @Autowired
    LocalComponentStore componentStore

    @BeforeEach
    void setUp() {
        // Clear storage between tests
        componentStore.clear()
    }

    @Test
    void "should store and retrieve component"() {
        given:
        ComponentId id = ComponentId.of("test-workflow", "1.0")
        StringComponent component = StringComponent.builder()
            .id(id)
            .definition("workflow { }")
            .build()

        when:
        componentStore.store(component).block()

        then:
        StringComponent retrieved = componentStore.get(id).block()
        retrieved.id == id
        retrieved.definition == "workflow { }"
    }
}

CI/CD with Local Provider

Perfect for continuous integration:

# .github/workflows/integration-test.yml
name: Integration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v3
        with:
          java-version: '21'
          distribution: 'corretto'

      - name: Run Integration Tests
        run: ./gradlew integrationTest
        env:
          HUB_CLOUD_PROVIDER_TYPE: local  # No AWS credentials needed!

LocalStack Setup

LocalStack provides local emulation of AWS services.

Installation

Using Docker

docker run -d \
  --name localstack \
  -p 4566:4566 \
  -e SERVICES=dynamodb,secretsmanager \
  localstack/localstack

Using Docker Compose

# docker-compose.yml
version: '3.8'

services:
  localstack:
    image: localstack/localstack
    ports:
      - "4566:4566"
    environment:
      - SERVICES=dynamodb,secretsmanager
      - DEBUG=1
      - DATA_DIR=/tmp/localstack/data
    volumes:
      - ./localstack-data:/tmp/localstack/data

Start with:

docker-compose up -d

Hub Configuration for LocalStack

# application-local.yml
hub:
  cloud:
    provider:
      type: aws

  aws:
    region: us-east-1
    accessKey: test
    secretKey: test
    dynamodb:
      endpoint: http://localhost:4566
      prefix: local-hub
      createTables: true
    secrets:
      endpoint: http://localhost:4566
      prefix: local-hub

Running the Hub

# Run with local profile
./gradlew bootRun --args='--spring.profiles.active=local'

Accessing LocalStack Services

DynamoDB

# List tables
aws dynamodb list-tables \
  --endpoint-url http://localhost:4566

# Scan components table
aws dynamodb scan \
  --table-name local-hub-components \
  --endpoint-url http://localhost:4566

Secrets Manager

# List secrets
aws secretsmanager list-secrets \
  --endpoint-url http://localhost:4566

# Get secret value
aws secretsmanager get-secret-value \
  --secret-id local-hub/component-config/test/1.0 \
  --endpoint-url http://localhost:4566

Testing

Unit Tests

Run unit tests without any cloud services:

./gradlew test

Integration Tests with LocalStack

# Start LocalStack
docker-compose up -d localstack

# Run integration tests
./gradlew integrationTest

# Stop LocalStack
docker-compose down

Test Configuration

# application-test.yml
hub:
  aws:
    region: us-east-1
    accessKey: test
    secretKey: test
    dynamodb:
      endpoint: http://localhost:4566
      prefix: test-hub
      createTables: true
    secrets:
      endpoint: http://localhost:4566
      prefix: test-hub

IntelliJ IDEA Setup

Run Configuration

Create new Spring Boot run configuration
Set main class: com.zenoo.hub.HubApplication
Set active profiles: local

Set environment variables:

SPRING_PROFILES_ACTIVE=local
AWS_REGION=us-east-1

Debug Configuration

Same as run configuration with debug mode enabled.

Troubleshooting

LocalStack Not Starting

# Check logs
docker logs localstack

# Restart LocalStack
docker restart localstack

Tables Not Created

# Manually create tables
aws dynamodb create-table \
  --table-name local-hub-components \
  --attribute-definitions \
    AttributeName=componentName,AttributeType=S \
    AttributeName=revision,AttributeType=N \
  --key-schema \
    AttributeName=componentName,KeyType=HASH \
    AttributeName=revision,KeyType=RANGE \
  --billing-mode PAY_PER_REQUEST \
  --endpoint-url http://localhost:4566

Connection Refused

Check LocalStack is running:

curl http://localhost:4566/_localstack/health

Hub Backend

Hub Client

Local Development Guide

Local Development Guide

Overview: Two Approaches

Quick Comparison

When to Use Local Provider

When to Use LocalStack

Local Provider Setup

1. Add Dependency

2. Configure

3. Run

Testing with Local Provider

CI/CD with Local Provider

LocalStack Setup

Installation

Using Docker

Using Docker Compose

Hub Configuration for LocalStack

Running the Hub

Accessing LocalStack Services

DynamoDB

Secrets Manager

Testing

Unit Tests

Integration Tests with LocalStack

Test Configuration

IntelliJ IDEA Setup

Run Configuration

Debug Configuration

Troubleshooting

LocalStack Not Starting

Tables Not Created

Connection Refused

See Also

​Local Development Guide

​Overview: Two Approaches

​Quick Comparison

​When to Use Local Provider

​When to Use LocalStack

​Local Provider Setup

​1. Add Dependency

​2. Configure

​3. Run

​Testing with Local Provider

​CI/CD with Local Provider

​LocalStack Setup

​Installation

​Using Docker

​Using Docker Compose

​Hub Configuration for LocalStack

​Running the Hub

​Accessing LocalStack Services

​DynamoDB

​Secrets Manager

​Testing

​Unit Tests

​Integration Tests with LocalStack

​Test Configuration

​IntelliJ IDEA Setup

​Run Configuration

​Debug Configuration

​Troubleshooting

​LocalStack Not Starting

​Tables Not Created

​Connection Refused

​See Also

Local Development Guide

Overview: Two Approaches

Quick Comparison

When to Use Local Provider

When to Use LocalStack

Local Provider Setup

1. Add Dependency

2. Configure

3. Run

Testing with Local Provider

CI/CD with Local Provider

LocalStack Setup

Installation

Using Docker

Using Docker Compose

Hub Configuration for LocalStack

Running the Hub

Accessing LocalStack Services

DynamoDB

Secrets Manager

Testing

Unit Tests

Integration Tests with LocalStack

Test Configuration

IntelliJ IDEA Setup

Run Configuration

Debug Configuration

Troubleshooting

LocalStack Not Starting

Tables Not Created

Connection Refused

See Also