Skip to content
Klutch.sh Docs

Deploying a LocalStack App

Introduction

LocalStack provides a fully functional local cloud stack that emulates AWS services. Deploying LocalStack with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for stateful mocks—all controlled from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample usage, and production tips.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your LocalStack configuration (GitHub is the only supported git source)
  • Docker familiarity
  • Optional: credentials for downstream services if you proxy requests or integrate external systems

For platform onboarding, see the Quick Start.

Architecture and ports

  • LocalStack serves multiple AWS-compatible endpoints; the edge gateway defaults to 4566 (HTTP). Set the internal container port to 4566 and choose TCP traffic in Klutch.sh.
  • Individual service ports are auto-managed by LocalStack behind the edge port; you typically expose only 4566.
  • Persistent storage is recommended for /var/lib/localstack to retain state between restarts.

Repository layout

localstack/
├── Dockerfile              # Must be at repo root for auto-detection
├── localstack.env          # Optional env overrides
├── scripts/                # Helper scripts (optional)
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Test LocalStack locally before pushing to GitHub:

Terminal window
docker run --rm -p 4566:4566 \
  -e SERVICES=s3,lambda,iam \
  -v $(pwd)/state:/var/lib/localstack \
  localstack/localstack:latest

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
exec localstack start

Make it executable with chmod +x start.sh.

Dockerfile for LocalStack (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM localstack/localstack:1.4


WORKDIR /app


# Optional: copy additional configs or scripts
COPY localstack.env /app/localstack.env


EXPOSE 4566
CMD ["localstack", "start", "--host"]

Notes:

  • Pin the image tag for reproducible behavior.
  • Use localstack.env for service lists and limits, or set env vars directly in Klutch.sh.

Environment variables (Klutch.sh)

Set these in the Klutch.sh app settings (Secrets tab) before deploying:

  • PORT=4566
  • SERVICES=s3,lambda,iam (choose only the services you need)
  • DEBUG=0 (set to 1 for troubleshooting)
  • DATA_DIR=/var/lib/localstack (persist state)
  • LAMBDA_EXECUTOR=docker-reuse (or local depending on your use case)
  • LOCALSTACK_HOST=example-app.klutch.sh

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD="echo LocalStack uses prebuilt image"
  • NIXPACKS_START_CMD=localstack start --host
  • NIXPACKS_JDK_VERSION=17

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /var/lib/localstack — required if you want to persist state (S3 objects, etc.).

Ensure this path is writable inside the container.

Deploy LocalStack on Klutch.sh (Dockerfile workflow)

  1. Push your repository (with the Dockerfile at the root) to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  1. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile.
  2. Choose TCP traffic for LocalStack.
  3. Set the internal port to 4566.
  4. Add the environment variables above (services list, data dir, executor, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach a persistent volume for /var/lib/localstack, selecting a size that fits your stateful usage.
  6. Deploy. Your LocalStack endpoint will be reachable at example-app.klutch.sh:8000 over TCP for clients and SDKs.

Sample usage (S3 with AWS CLI)

Point AWS CLI to LocalStack (replace host/port):

Terminal window
aws --endpoint-url http://example-app.klutch.sh:8000 s3 mb s3://demo-bucket
aws --endpoint-url http://example-app.klutch.sh:8000 s3 ls

Health checks and production tips

  • Use /health or a simple S3 list command for health probes.
  • Enforce network policies and credentials even for mock environments; store secrets in Klutch.sh.
  • Pin image tags and upgrade intentionally.
  • Monitor volume usage on /var/lib/localstack and resize before it fills.
  • Limit SERVICES to only what you need to reduce startup time and resource use.

LocalStack on Klutch.sh combines reproducible Docker builds with managed secrets, persistent state for mocked AWS services, and flexible TCP routing. With the Dockerfile at the repo root and port 4566 configured, you can run reliable AWS emulation without extra YAML or workflow overhead.