Deploy Floci — AWS Emulator

Deploy and Host Floci on Railway

Floci is a fast, free, and open-source AWS service emulator for development, testing, automation, and CI workflows. It provides AWS-compatible APIs for services such as S3, SQS, DynamoDB, SNS, Secrets Manager, IAM, Lambda, API Gateway, and many others without requiring a real AWS account.

About Hosting Floci

This template deploys Floci on Railway using the official floci/floci:latest Docker image.

Floci exposes its AWS-compatible APIs through a unified endpoint on port 4566. Applications, AWS CLI, SDKs, automation tools, and development environments can connect to the Railway public domain using it as a custom AWS endpoint.

Persistent state is stored in a Railway volume mounted at /app/data, allowing supported resources and emulator state to survive service restarts.

Railway volumes are mounted as root. This template uses RAILWAY_RUN_UID=0 to avoid permission issues when Floci writes persistent state to the mounted volume.

Common Use Cases

• Develop applications against AWS-compatible APIs without using production AWS resources
• Test S3, SQS, SNS, DynamoDB, Secrets Manager, IAM, and other AWS integrations
• Run integration and end-to-end tests against isolated AWS-like infrastructure
• Develop AWS SDK integrations without consuming AWS resources
• Test automation workflows that depend on AWS services
• Build CI/CD environments without requiring real AWS credentials
• Use a remotely accessible AWS emulator for development teams

Dependencies for Floci Hosting

• Official floci/floci:latest Docker image
• Railway public networking on port 4566
• Railway persistent volume mounted at /app/data

Railway Configuration

The template uses the following important configuration:

PORT="4566"
FLOCI_PORT="4566"
FLOCI_BASE_URL="https://${{RAILWAY_PUBLIC_DOMAIN}}"

RAILWAY_RUN_UID="0"

FLOCI_STORAGE_MODE="persistent"
FLOCI_STORAGE_PERSISTENT_PATH="/app/data"

FLOCI_DEFAULT_REGION="us-east-1"
FLOCI_DEFAULT_ACCOUNT_ID="000000000000"

Persistent volume:

/app/data

No custom start command is required.

How to Use Floci

After deployment, Railway will provide a public domain similar to:

https://your-floci-service.up.railway.app

This domain becomes your AWS-compatible endpoint.

For the examples below:

export AWS_ENDPOINT_URL="https://your-floci-service.up.railway.app"

Replace the example URL with your actual Railway public domain.

1. Check Floci Health

Verify that Floci is running:

curl "$AWS_ENDPOINT_URL/_floci/health"

A successful response confirms that the emulator is available.

2. Configure AWS CLI

Floci does not require real AWS credentials. Any non-empty credentials can be used.

export AWS_ENDPOINT_URL="https://your-floci-service.up.railway.app"
export AWS_DEFAULT_REGION="us-east-1"
export AWS_ACCESS_KEY_ID="test"
export AWS_SECRET_ACCESS_KEY="test"

You can now use normal AWS CLI commands while directing them to Floci.

3. Test S3

Create a bucket:

aws s3 mb s3://my-bucket \
  --endpoint-url "$AWS_ENDPOINT_URL"

Upload a file:

echo "Hello from Floci on Railway" > hello.txt

aws s3 cp hello.txt s3://my-bucket/hello.txt \
  --endpoint-url "$AWS_ENDPOINT_URL"

List the bucket:

aws s3 ls s3://my-bucket \
  --endpoint-url "$AWS_ENDPOINT_URL"

Download the file:

aws s3 cp s3://my-bucket/hello.txt downloaded.txt \
  --endpoint-url "$AWS_ENDPOINT_URL"

4. Test SQS

Create a queue:

aws sqs create-queue \
  --queue-name orders \
  --endpoint-url "$AWS_ENDPOINT_URL"

The response will contain a QueueUrl similar to:

https://your-floci-service.up.railway.app/000000000000/orders

Send a message:

aws sqs send-message \
  --queue-url "$AWS_ENDPOINT_URL/000000000000/orders" \
  --message-body '{"event":"order.placed"}' \
  --endpoint-url "$AWS_ENDPOINT_URL"

Receive messages:

aws sqs receive-message \
  --queue-url "$AWS_ENDPOINT_URL/000000000000/orders" \
  --endpoint-url "$AWS_ENDPOINT_URL"

5. Test DynamoDB

Create a table:

aws dynamodb create-table \
  --table-name Users \
  --attribute-definitions AttributeName=id,AttributeType=S \
  --key-schema AttributeName=id,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST \
  --endpoint-url "$AWS_ENDPOINT_URL"

List tables:

aws dynamodb list-tables \
  --endpoint-url "$AWS_ENDPOINT_URL"

Add an item:

aws dynamodb put-item \
  --table-name Users \
  --item '{"id":{"S":"1"},"name":{"S":"Floci User"}}' \
  --endpoint-url "$AWS_ENDPOINT_URL"

Read the item:

aws dynamodb get-item \
  --table-name Users \
  --key '{"id":{"S":"1"}}' \
  --endpoint-url "$AWS_ENDPOINT_URL"

Using Floci from an Application

The main requirement is to override the AWS service endpoint and point it to your Railway domain.

Node.js / TypeScript

Using AWS SDK for JavaScript v3:

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

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

Python

Using boto3:

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://your-floci-service.up.railway.app",
    region_name="us-east-1",
    aws_access_key_id="test",
    aws_secret_access_key="test",
)

Java

Using AWS SDK for Java v2:

S3Client s3 = S3Client.builder()
    .endpointOverride(
        URI.create("https://your-floci-service.up.railway.app")
    )
    .region(Region.US_EAST_1)
    .credentialsProvider(
        StaticCredentialsProvider.create(
            AwsBasicCredentials.create("test", "test")
        )
    )
    .build();

Persistent Storage

This template uses:

FLOCI_STORAGE_MODE="persistent"
FLOCI_STORAGE_PERSISTENT_PATH="/app/data"

with a Railway volume mounted at:

/app/data

This allows supported Floci state to survive container restarts and redeployments.

Deleting the Railway volume will delete the persisted emulator state stored inside it.

Important Notes

• Do not use real AWS access keys with Floci. Dummy credentials such as test are sufficient.
• Floci is an AWS emulator, not a connection or proxy to a real AWS account.
• Set your application's AWS endpoint to the Railway public domain instead of the normal AWS endpoint.
• FLOCI_BASE_URL is configured with the Railway public domain so URLs generated by services such as SQS use an externally reachable hostname.
• Persistent resources are stored under /app/data.
• Some advanced AWS services may depend on capabilities beyond the core Floci process. Verify service-specific compatibility before relying on them for production-like testing.
• Floci should be used for development, testing, CI, and emulation rather than as a replacement for actual AWS infrastructure.

Floci vs Real AWS

Why Deploy Floci 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.

By deploying Floci on Railway, you get a remotely accessible AWS-compatible development environment with persistent storage, automatic HTTPS, public networking, and simple infrastructure management without maintaining your own server.