---
title: "Deploy LocalStack — AWS Emulator"
description: "An AWS cloud emulator for development, testing, and CI workflows."
category: "Other"
url: https://railway.com/deploy/localstack-aws-emulator
---

# Deploy LocalStack — AWS Emulator

An AWS cloud emulator for development, testing, and CI workflows.

**[Deploy LocalStack — AWS Emulator on Railway](https://railway.com/template/localstack-aws-emulator)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/localstack-aws-emulator/manifest.json

- **Creator:** INF Labs
- **Category:** Other

## Template content

### localstack https://res.cloudinary.com/drxplgxxg/image/upload/v1788762947/localstack.png

- **Image:** localstack/localstack:latest
- **Public domain:** Yes

## Documentation

# Deploy and Host LocalStack on Railway

LocalStack is a cloud service emulator that provides AWS-compatible APIs for development, testing, automation, and CI/CD workflows.

It allows applications to interact with services such as S3, SQS, SNS, DynamoDB, Secrets Manager, SSM, IAM, STS, and many other AWS APIs without connecting directly to production AWS infrastructure.

## About Hosting LocalStack

This template deploys LocalStack on Railway using the official `localstack/localstack` Docker image.

LocalStack exposes AWS-compatible APIs through a unified gateway on port `4566`. AWS CLI, AWS SDKs, applications, and automation tools can connect to the Railway public domain and use it as a custom AWS endpoint.

A Railway persistent volume is mounted at:

```text
/var/lib/localstack
```

With persistence enabled, supported LocalStack resources and state can survive container restarts and redeployments.

> **Important:** A valid `LOCALSTACK_AUTH_TOKEN` is required to start current LocalStack releases. You can obtain your token from https://app.localstack.cloud.

Because Railway does not expose the host Docker daemon or `/var/run/docker.sock`, LocalStack features that require additional Docker containers may be unavailable or limited.

## Common Use Cases

* Develop applications against AWS-compatible APIs without using production AWS resources
* Test S3-compatible object storage integrations
* Test SQS and SNS messaging workflows
* Develop and test DynamoDB integrations
* Test Secrets Manager, SSM, IAM, STS, and other supported AWS APIs
* Run integration tests in CI/CD pipelines
* Test AWS CLI and AWS SDK configurations
* Create isolated AWS-like development and QA environments
* Provide a remotely accessible AWS emulator for development teams

## Dependencies for LocalStack Hosting

* Official `localstack/localstack` Docker image
* Valid LocalStack Auth Token
* Railway HTTP networking on port `4566`
* Railway persistent volume mounted at `/var/lib/localstack`

No external PostgreSQL, Redis, MinIO, or other database service is required for the default deployment.

## Configuration

This template uses a minimal configuration:

```env
PORT="4566"
DEBUG="0"
PERSISTENCE="1"
LOCALSTACK_AUTH_TOKEN=""
```

### Environment Variables

* `PORT=4566` — LocalStack gateway port used by Railway networking
* `DEBUG=0` — set to `1` to enable verbose LocalStack debugging
* `PERSISTENCE=1` — persists supported LocalStack state across container restarts
* `LOCALSTACK_AUTH_TOKEN` — **required** LocalStack authentication token from https://app.localstack.cloud

## Before Deploying

You must have a valid LocalStack Auth Token.

1. Open https://app.localstack.cloud
2. Sign in or create a LocalStack account
3. Copy your LocalStack Auth Token
4. Enter the token into the `LOCALSTACK_AUTH_TOKEN` variable when deploying the Railway template

Do not replace the token with a randomly generated Railway secret. It must be a valid token issued by LocalStack.

If the token is missing or invalid, LocalStack may stop during startup and Railway will return a `502 Bad Gateway` because no application is listening on port `4566`.

## Railway Configuration

The template uses:

```text
Docker Image
localstack/localstack

Target Port
4566

Volume
/var/lib/localstack
```

No custom start command is required.

## After Deployment

Once the deployment is running, Railway will provide a public domain similar to:

```text
https://your-localstack.up.railway.app
```

This domain becomes your LocalStack AWS endpoint.

You can verify that LocalStack is running by opening:

```text
https://your-localstack.up.railway.app/_localstack/health
```

A successful response indicates that the LocalStack gateway is reachable.

## Connecting with AWS CLI

AWS CLI can connect to LocalStack by specifying the Railway public domain with `--endpoint-url`.

Example:

```bash
aws \
  --endpoint-url=https://your-localstack.up.railway.app \
  s3 ls
```

For LocalStack development environments, dummy AWS credentials can normally be used by AWS clients:

```bash
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=us-east-1
```

You can then create an S3 bucket:

```bash
aws \
  --endpoint-url=https://your-localstack.up.railway.app \
  s3 mb s3://my-test-bucket
```

And list your buckets:

```bash
aws \
  --endpoint-url=https://your-localstack.up.railway.app \
  s3 ls
```

## Connecting with AWS SDK

Use the Railway public domain as the AWS SDK endpoint.

Example using AWS SDK for JavaScript:

```javascript
import { S3Client } from "@aws-sdk/client-s3";

const s3 = new S3Client({
    region: "us-east-1",
    endpoint: "https://your-localstack.up.railway.app",
    credentials: {
        accessKeyId: "test",
        secretAccessKey: "test"
    },
    forcePathStyle: true
});
```

### S3 Path-Style Access

When using S3 through a Railway-generated public domain, path-style addressing is recommended:

```javascript
forcePathStyle: true
```

This avoids relying on wildcard bucket subdomains such as:

```text
bucket-name.your-localstack.up.railway.app
```

which may not be available through the Railway-generated domain.

## Railway Deployment Architecture

```text
Application / AWS CLI / AWS SDK
              │
              │ HTTPS
              ▼
      Railway Public Domain
              │
              ▼
      LocalStack Gateway
             :4566
              │
              ▼
     /var/lib/localstack
       Railway Volume
```

## LocalStack vs AWS

| Feature                               | LocalStack on Railway | AWS   |
| ------------------------------------- | --------------------- | ----- |
| AWS-compatible APIs                   | ✅                     | ✅     |
| Development and testing               | ✅                     | ✅     |
| AWS production infrastructure         | ❌                     | ✅     |
| Requires AWS production resources     | ❌                     | ✅     |
| LocalStack account/token              | ✅                     | ❌     |
| Persistent state                      | ✅                     | ✅     |
| AWS usage billing                     | ❌                     | ✅     |
| Managed HTTPS endpoint                | ✅ Railway             | ✅ AWS |
| Docker-dependent LocalStack features  | ⚠️ Limited            | N/A   |
| Suitable for production AWS workloads | ❌                     | ✅     |

## Important Limitations

Railway containers do not provide access to the host Docker daemon through:

```text
/var/run/docker.sock
```

Some LocalStack functionality, particularly features that create additional Docker containers, may therefore be unavailable.

For example, some Lambda execution workflows depend on Docker-based execution environments and may not work the same way they do with a traditional Docker Compose or local Docker installation.

This Railway template is best suited for AWS services and development workflows that operate directly through the LocalStack gateway.

## Troubleshooting

### 502 Bad Gateway

If Railway returns:

```text
502 Bad Gateway
```

check the deployment logs first.

A common cause is a missing or invalid:

```text
LOCALSTACK_AUTH_TOKEN
```

Current LocalStack releases may terminate during startup when valid credentials are not available.

Get your LocalStack Auth Token from:

```text
https://app.localstack.cloud
```

Then update the Railway variable and redeploy the service.

### LocalStack is Running but AWS CLI Fails

Make sure your AWS CLI command includes:

```bash
--endpoint-url=https://your-localstack.up.railway.app
```

Without this option, AWS CLI will attempt to contact the real AWS service instead of LocalStack.

### Persistent Resources Disappear

Verify that:

```env
PERSISTENCE="1"
```

is configured and that the Railway volume is mounted at:

```text
/var/lib/localstack
```

## Why Deploy LocalStack on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

Deploying LocalStack on Railway provides a remotely accessible AWS-compatible environment with managed HTTPS networking, persistent storage, deployment logs, environment variables, and simple container management.

This makes it useful for development environments, API integrations, automated testing, CI/CD workflows, and teams that need a shared AWS emulator without maintaining their own server or Docker host.


## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/localstack-aws-emulator