Quickstart

Start Floci

Create a docker-compose.yml file with the native image:

services:
  floci:
    image: hectorvent/floci:latest
    ports:
      - "4566:4566"
    volumes:
      - ./data:/app/data

Then start Floci in the background:

docker compose up -d

All services are available at http://localhost:4566.

Configure AWS CLI

Floci accepts any non-empty credentials — no real AWS account is needed. Export the following environment variables in your shell:

export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_DEFAULT_REGION=us-east-1
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test

Add these lines to your shell profile (.bashrc or .zshrc) so they persist across sessions.

Verify the setup

Run a few smoke tests against S3, SQS, and DynamoDB to confirm everything is working:

# S3 — create a bucket and upload a file
aws s3 mb s3://my-bucket
echo "hello floci" | aws s3 cp - s3://my-bucket/hello.txt
aws s3 ls s3://my-bucket

# SQS — create a queue and send a message
aws sqs create-queue --queue-name orders
aws sqs send-message \
  --queue-url http://localhost:4566/000000000000/orders \
  --message-body '{"event":"order.placed"}'

# 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

You should see successful responses for all three commands.

Use in your application

Point your AWS SDK at http://localhost:4566. Select your language below:

Java
Python
Node.js
Go
Rust

S3Client s3 = S3Client.builder()
    .endpointOverride(URI.create("http://localhost:4566"))
    .region(Region.US_EAST_1)
    .credentialsProvider(StaticCredentialsProvider.create(
        AwsBasicCredentials.create("test", "test")))
    .build();

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="http://localhost:4566",
    region_name="us-east-1",
    aws_access_key_id="test",
    aws_secret_access_key="test",
)

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

const s3 = new S3Client({
  endpoint: "http://localhost:4566",
  region: "us-east-1",
  credentials: { accessKeyId: "test", secretAccessKey: "test" },
  forcePathStyle: true,
});

cfg, _ := config.LoadDefaultConfig(context.TODO(),
    config.WithRegion("us-east-1"),
    config.WithEndpointResolverWithOptions(
        aws.EndpointResolverWithOptionsFunc(func(service, region string, opts ...interface{}) (aws.Endpoint, error) {
            return aws.Endpoint{URL: "http://localhost:4566"}, nil
        }),
    ),
)
client := s3.NewFromConfig(cfg)

let config = aws_config::from_env()
    .endpoint_url("http://localhost:4566")
    .region(Region::new("us-east-1"))
    .credentials_provider(Credentials::new("test", "test", None, None, "static"))
    .load()
    .await;

let client = aws_sdk_s3::Client::new(&config);

Get Started

Configuration

Services

Contributing

Next steps

Configuration

Services

Build docs developers (and LLMs) love

Get Started

Configuration

Services

Contributing

​Next steps

Configuration

Services

Build docs developers (and LLMs) love

Next steps