Quickstart

Get Floci running and verify AWS CLI commands work against it in under five minutes.

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

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

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

4. Use in your application

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

   Java

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

   Python

   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",
   )
   

   Node.js

   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,
   });
   

   Go

   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)
   

   Rust

   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);
   

Next steps

Configuration

Explore all environment variables and storage modes.

Services

Browse per-service documentation, supported operations, and notable features.