{"id":47573734,"url":"https://github.com/hectorvent/floci","last_synced_at":"2026-04-03T21:00:51.444Z","repository":{"id":344693023,"uuid":"1160497244","full_name":"hectorvent/floci","owner":"hectorvent","description":"Light, fluffy, and always free - AWS Local Emulator ","archived":false,"fork":false,"pushed_at":"2026-03-31T22:12:20.000Z","size":1464,"stargazers_count":2362,"open_issues_count":50,"forks_count":106,"subscribers_count":10,"default_branch":"main","last_synced_at":"2026-03-31T23:13:54.635Z","etag":null,"topics":["aws","aws-emulation","localstack"],"latest_commit_sha":null,"homepage":"https://floci.io","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hectorvent.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["hectorvent"]}},"created_at":"2026-02-18T02:28:29.000Z","updated_at":"2026-03-31T23:06:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"0c50f97a-7b9d-45d5-b062-0b85a2c846b9","html_url":"https://github.com/hectorvent/floci","commit_stats":null,"previous_names":["hectorvent/floci"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/hectorvent/floci","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hectorvent%2Ffloci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hectorvent%2Ffloci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hectorvent%2Ffloci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hectorvent%2Ffloci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hectorvent","download_url":"https://codeload.github.com/hectorvent/floci/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hectorvent%2Ffloci/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31377101,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-emulation","localstack"],"created_at":"2026-03-30T23:00:26.298Z","updated_at":"2026-04-03T21:00:51.438Z","avatar_url":"https://github.com/hectorvent.png","language":"Java","funding_links":["https://github.com/sponsors/hectorvent"],"categories":["Java","aws"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"floci_banner.svg\" alt=\"Floci\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/hectorvent/floci/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/hectorvent/floci?label=latest%20release\u0026color=blue\" alt=\"Latest Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/hectorvent/floci/actions/workflows/release.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/hectorvent/floci/release.yml?label=build\" alt=\"Build Status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://hub.docker.com/r/hectorvent/floci\"\u003e\u003cimg src=\"https://img.shields.io/docker/pulls/hectorvent/floci?label=docker%20pulls\" alt=\"Docker Pulls\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://hub.docker.com/r/hectorvent/floci\"\u003e\u003cimg src=\"https://img.shields.io/docker/image-size/hectorvent/floci/latest?label=image%20size\" alt=\"Docker Image Size\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/hectorvent/floci/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/hectorvent/floci?style=flat\" alt=\"GitHub Stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/hectorvent/floci/graphs/contributors\"\u003e\u003cimg src=\"https://img.shields.io/github/contributors/hectorvent/floci\" alt=\"GitHub Contributors\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://join.slack.com/t/floci/shared_invite/zt-3tjn02s3q-A00kEjJ1cZxsg_imTfy6Cw\"\u003e\u003cimg src=\"https://img.shields.io/badge/Slack-Join%20the%20community-4A154B?logo=slack\u0026logoColor=white\" alt=\"Join Floci on Slack\"\u003e\u003c/a\u003e\n\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eNamed after \u003ca href=\"https://en.wikipedia.org/wiki/Cirrocumulus_floccus\"\u003efloccus\u003c/a\u003e — the cloud formation that looks exactly like popcorn.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  A free, open-source local AWS emulator. No account. No feature gates. Just\u0026nbsp;\u003ccode\u003edocker compose up\u003c/code\u003e.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Join the community on \u003ca href=\"https://join.slack.com/t/floci/shared_invite/zt-3tjn02s3q-A00kEjJ1cZxsg_imTfy6Cw\"\u003eSlack\u003c/a\u003e to ask questions, share feedback, and discuss Floci with other contributors and users. You can also open any topic in \u003ca href=\"https://github.com/hectorvent/floci/discussions\"\u003eGitHub Discussions\u003c/a\u003e — feature ideas, compatibility questions, design tradeoffs, wild proposals, or half-baked thoughts are all welcome. No idea is too small, too early, or too popcorn-fueled to start a good discussion.\n\u003c/p\u003e\n\n---\n\n\u003e LocalStack's community edition [sunset in March 2026](https://blog.localstack.cloud/the-road-ahead-for-localstack/) — requiring auth tokens, and freezing security updates. Floci is the no-strings-attached alternative.\n\n## Why Floci?\n\n| | Floci | LocalStack Community |\n|---|---|---|\n| Auth token required | No | Yes (since March 2026) |\n| Security updates | Yes | Frozen |\n| Startup time | **~24 ms** | ~3.3 s |\n| Idle memory | **~13 MiB** | ~143 MiB |\n| Docker image size | **~90 MB** | ~1.0 GB |\n| License | **MIT** | Restricted |\n| API Gateway v2 / HTTP API | ✅ | ❌ |\n| Cognito | ✅ | ❌ |\n| ElastiCache (Redis + IAM auth) | ✅ | ❌ |\n| RDS (PostgreSQL + MySQL + IAM auth) | ✅ | ❌ |\n| S3 Object Lock (COMPLIANCE / GOVERNANCE) | ✅ | ⚠️ Partial |\n| DynamoDB Streams | ✅ | ⚠️ Partial |\n| IAM (users, roles, policies, groups) | ✅ | ⚠️ Partial |\n| STS (all 7 operations) | ✅ | ⚠️ Partial |\n| Kinesis (streams, shards, fan-out) | ✅ | ⚠️ Partial |\n| KMS (sign, verify, re-encrypt) | ✅ | ⚠️ Partial |\n| Native binary | ✅ ~40 MB | ❌ |\n\n**25 services. 408/408 SDK tests passing. Free forever.**\n\n## Architecture Overview\n\n```mermaid\nflowchart LR\n    Client[\"☁️ AWS SDK / CLI\"]\n\n    subgraph Floci [\"Floci — port 4566\"]\n        Router[\"HTTP Router\\n(JAX-RS / Vert.x)\"]\n\n        subgraph Stateless [\"Stateless Services\"]\n            A[\"SSM · SQS · SNS\\nIAM · STS · KMS\\nSecrets Manager · SES\\nCognito · Kinesis · OpenSearch\\nEventBridge · CloudWatch\\nStep Functions · CloudFormation\\nACM · API Gateway\"]\n        end\n\n        subgraph Stateful [\"Stateful Services\"]\n            B[\"S3 · DynamoDB\\nDynamoDB Streams\"]\n        end\n\n        subgraph Containers [\"Container Services  🐳\"]\n            C[\"Lambda\\nElastiCache\\nRDS\"]\n        end\n\n        Router --\u003e Stateless\n        Router --\u003e Stateful\n        Router --\u003e Containers\n        Stateless \u0026 Stateful --\u003e Store[(\"StorageBackend\\nmemory · hybrid\\npersistent · wal\")]\n    end\n\n    Docker[\"🐳 Docker Engine\"]\n    Client --\u003e|\"HTTP :4566\\nAWS wire protocol\"| Router\n    Containers --\u003e|\"Docker API\\n+ IAM / SigV4 auth\"| Docker\n```\n\n## Supported Services\n\n| Service | Ops | How it works | Notable features |\n|---|---|---|---|\n| **SSM Parameter Store** | 12 | In-process | Version history, labels, SecureString, tagging |\n| **SQS** | 17 | In-process | Standard \u0026 FIFO, DLQ, visibility timeout, batch, tagging |\n| **SNS** | 13 | In-process | Topics, subscriptions, SQS / Lambda / HTTP delivery, tagging |\n| **S3** | 30 | In-process | Versioning, multipart upload, pre-signed URLs, Object Lock, event notifications |\n| **DynamoDB** | 22 | In-process | GSI / LSI, Query, Scan, TTL, transactions, batch operations |\n| **DynamoDB Streams** | 5 | In-process | Shard iterators, records, Lambda ESM trigger |\n| **Lambda** | 25 | **Real Docker containers** | Warm pool, aliases, Function URLs, SQS / Kinesis / DDB Streams ESM |\n| **API Gateway REST** | 24 | In-process | Resources, methods, stages, Lambda proxy, MOCK integrations, AWS integrations |\n| **API Gateway v2 (HTTP)** | 16 | In-process | Routes, integrations, JWT authorizers, stages |\n| **IAM** | 65+ | In-process | Users, roles, groups, policies, instance profiles, access keys |\n| **STS** | 7 | In-process | AssumeRole, WebIdentity, SAML, GetFederationToken, GetSessionToken |\n| **Cognito** | 20 | In-process | User pools, app clients, auth flows, JWKS / OpenID well-known endpoints |\n| **KMS** | 15 | In-process | Encrypt / decrypt, sign / verify, data keys, aliases |\n| **Kinesis** | 15 | In-process | Streams, shards, enhanced fan-out, split / merge |\n| **Secrets Manager** | 10 | In-process | Versioning, resource policies, tagging |\n| **Step Functions** | 11 | In-process | ASL execution, task tokens, execution history |\n| **CloudFormation** | 12 | In-process | Stacks, change sets, resource provisioning |\n| **EventBridge** | 14 | In-process | Custom buses, rules, targets (SQS / SNS / Lambda) |\n| **CloudWatch Logs** | 14 | In-process | Log groups, streams, ingestion, filtering |\n| **CloudWatch Metrics** | 5 | In-process | Custom metrics, statistics, alarms |\n| **ElastiCache** | 9 | **Real Docker containers** | Redis / Valkey, IAM auth, SigV4 validation |\n| **RDS** | 14 | **Real Docker containers** | PostgreSQL \u0026 MySQL, IAM auth, JDBC-compatible |\n| **ACM** | 8 | In-process | Certificate issuance, validation lifecycle |\n| **SES** | 14 | In-process | Send email / raw email, identity verification, DKIM attributes |\n| **OpenSearch** | 24 | In-process | Domain CRUD, tags, versions, instance types, upgrade stubs |\n\n\u003e **Lambda, ElastiCache, and RDS** spin up real Docker containers and support IAM authentication and SigV4 request signing — the same auth flow as production AWS.\n\n## Quick Start\n\n```yaml\n# docker-compose.yml\nservices:\n  floci:\n    image: hectorvent/floci:latest\n    ports:\n      - \"4566:4566\"\n    volumes:\n      # Local directory bind mount (default)\n      - ./data:/app/data\n      \n      # OR named volume (optional):\n      # - floci-data:/app/data\n\n#volumes:\n#  floci-data:\n```\n\n```bash\ndocker compose up\n```\n\nAll services are available at `http://localhost:4566`. Use any AWS region — credentials can be anything.\n\n```bash\nexport AWS_ENDPOINT_URL=http://localhost:4566\nexport AWS_DEFAULT_REGION=us-east-1\nexport AWS_ACCESS_KEY_ID=test\nexport AWS_SECRET_ACCESS_KEY=test\n\n# Try it\naws s3 mb s3://my-bucket\naws sqs create-queue --queue-name my-queue\naws dynamodb list-tables\n```\n\n## SDK Integration\n\nPoint your existing AWS SDK at `http://localhost:4566` — no other changes needed.\n\n```java\n// Java (AWS SDK v2)\nDynamoDbClient client = DynamoDbClient.builder()\n    .endpointOverride(URI.create(\"http://localhost:4566\"))\n    .region(Region.US_EAST_1)\n    .credentialsProvider(StaticCredentialsProvider.create(\n        AwsBasicCredentials.create(\"test\", \"test\")))\n    .build();\n```\n\n```python\n# Python (boto3)\nimport boto3\nclient = boto3.client(\"s3\",\n    endpoint_url=\"http://localhost:4566\",\n    region_name=\"us-east-1\",\n    aws_access_key_id=\"test\",\n    aws_secret_access_key=\"test\")\n```\n\n```javascript\n// Node.js (AWS SDK v3)\nimport { S3Client } from \"@aws-sdk/client-s3\";\n\nconst client = new S3Client({\n    endpoint: \"http://localhost:4566\",\n    region: \"us-east-1\",\n    credentials: { accessKeyId: \"test\", secretAccessKey: \"test\" },\n    forcePathStyle: true,\n});\n```\n\n## Compatibility Testing\n\n\u003e For full compatibility validation against real SDK and client workflows, use [floci-compatibility-tests](https://github.com/hectorvent/floci-compatibility-tests).\n\nThis companion project provides a dedicated compatibility test suite for Floci across multiple SDKs and tooling scenarios, and is the recommended starting point when verifying integration behavior end to end.\n\nAvailable SDK test modules:\n\n| Module | Language / Tool | SDK / Client |\n|---|---|---|\n| `sdk-test-java` | Java 17 | AWS SDK for Java v2 |\n| `sdk-test-go` | Go | AWS SDK for Go v2 |\n| `sdk-test-node` | Node.js | AWS SDK for JavaScript v3 |\n| `sdk-test-python` | Python 3 | boto3 |\n| `sdk-test-rust` | Rust | AWS SDK for Rust |\n| `sdk-test-awscli` | Bash | AWS CLI v2 |\n\nThe repository also includes compatibility validation for infrastructure tooling through `compat-cdk` (AWS CDK v2) and `compat-opentofu` (OpenTofu / Terraform-compatible workflows).\n\n## Image Tags\n\n| Tag | Description |\n|---|---|\n| `latest` | Native image — sub-second startup **(recommended)** |\n| `latest-jvm` | JVM image — broadest platform compatibility |\n| `x.y.z` / `x.y.z-jvm` | Pinned releases |\n\n## Configuration\n\nAll settings are overridable via environment variables (`FLOCI_` prefix).\n\n| Variable | Default | Description |\n|---|---|---|\n| `QUARKUS_HTTP_PORT` | `4566` | HTTP port |\n| `FLOCI_DEFAULT_REGION` | `us-east-1` | Default AWS region |\n| `FLOCI_DEFAULT_ACCOUNT_ID` | `000000000000` | Default AWS account ID |\n| `FLOCI_BASE_URL` | `http://localhost:4566` | Base URL used in API responses (e.g. SQS QueueUrl) |\n| `FLOCI_HOSTNAME` | *(unset)* | Override hostname in response URLs (for Docker Compose) |\n| `FLOCI_STORAGE_MODE` | `memory` | `memory` · `persistent` · `hybrid` · `wal` |\n| `FLOCI_STORAGE_PERSISTENT_PATH` | `./data` | Data directory |\n| `FLOCI_ECR_BASE_URI` | `public.ecr.aws` | AWS ECR Base URI to pull container images (e.g. Lambda) |\n\n→ Full reference: [configuration docs](https://hectorvent.dev/floci/configuration/application-yml/)\n→ Per-service storage overrides: [storage docs](https://hectorvent.dev/floci/configuration/storage/#per-service-storage-overrides)\n\n**Multi-container Docker Compose:** When your application runs in a separate container from Floci, set `FLOCI_HOSTNAME` to the Floci service name so that returned URLs (e.g. SQS QueueUrl) resolve correctly:\n\n```yaml\nservices:\n  floci:\n    image: hectorvent/floci:latest\n    ports:\n      - \"4566:4566\"\n    environment:\n      - FLOCI_HOSTNAME=floci  # URLs will use http://floci:4566/...\n  my-app:\n    environment:\n      - AWS_ENDPOINT_URL=http://floci:4566\n    depends_on:\n      - floci\n```\n\nWithout this, SQS returns `http://localhost:4566/...` in QueueUrl responses, which resolves to the wrong container.\n\n## Star history\n\n[![Star History Chart](https://api.star-history.com/svg?repos=hectorvent/floci\u0026type=Date)](https://star-history.com/#hectorvent/floci\u0026Date)\n\n## Contributors\n\n\u003ca href=\"https://github.com/hectorvent/floci/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=hectorvent/floci\" /\u003e\n\u003c/a\u003e\n\n## License\n\nMIT — use it however you want.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhectorvent%2Ffloci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhectorvent%2Ffloci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhectorvent%2Ffloci/lists"}