---
title: "Deploy Floci — AWS Emulator"
description: "A fast, free AWS emulator for development, testing, and CI."
category: "Other"
url: https://railway.com/deploy/floci
---

# Deploy Floci — AWS Emulator

A fast, free AWS emulator for development, testing, and CI.

**[Deploy Floci — AWS Emulator on Railway](https://railway.com/template/floci)**

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

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

## Template content

### floci https://res.cloudinary.com/drxplgxxg/image/upload/v1788763915/floci.png

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

## Documentation

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

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

```text
/app/data
```

No custom start command is required.

## How to Use Floci

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

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

This domain becomes your AWS-compatible endpoint.

For the examples below:

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

```bash
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.

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

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

Upload a file:

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

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

Download the file:

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

### 4. Test SQS

Create a queue:

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

The response will contain a `QueueUrl` similar to:

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

Send a message:

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

Receive messages:

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

### 5. Test DynamoDB

Create a table:

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

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

Add an item:

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

Read the item:

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

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

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

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

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

with a Railway volume mounted at:

```text
/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

| Feature                                | Floci on Railway | AWS |
| -------------------------------------- | ---------------- | --- |
| AWS-compatible APIs                    | ✅                | ✅   |
| Requires AWS account                   | ❌                | ✅   |
| Requires real AWS credentials          | ❌                | ✅   |
| Local/test resources                   | ✅                | ❌   |
| Persistent emulator state              | ✅                | N/A |
| AWS infrastructure                     | ❌                | ✅   |
| Suitable for development & CI          | ✅                | ✅   |
| Suitable as production AWS replacement | ❌                | ✅   |

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


## 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/floci