Deploy LocalStack — AWS Emulator

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:

/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:

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:

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:

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

This domain becomes your LocalStack AWS endpoint.

You can verify that LocalStack is running by opening:

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:

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:

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:

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

And list your buckets:

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:

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:

forcePathStyle: true

This avoids relying on wildcard bucket subdomains such as:

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

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

Railway Deployment Architecture

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

LocalStack vs AWS

Important Limitations

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

/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:

502 Bad Gateway

check the deployment logs first.

A common cause is a missing or invalid:

LOCALSTACK_AUTH_TOKEN

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

Get your LocalStack Auth Token from:

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:

--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:

PERSISTENCE="1"

is configured and that the Railway volume is mounted at:

/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.