floci

KO | EN

gitlite — search

#php #java #hacktoberfest #javascript #python #c #dotfiles #android #csharp #library #ruby #nodejs

★ 20,184 Open GitHub ↗

가볍고 푹신하며 항상 무료 - AWS Local Emulator의 대안

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![Floci](docs/assets/floci-black.svg#gh-light-mode-only)
![Floci](docs/assets/floci-white.svg#gh-dark-mode-only)

**가볍고, 부드러우며, 언제나 무료**  
계정이 필요 없습니다. 인증 토큰이 필요 없습니다. 기능 제한(feature gate)이 없습니다. 단지 `docker compose up`만 실행하세요.

[![Latest Release](https://img.shields.io/github/v/release/floci-io/floci?label=latest%20release&color=blue)](https://github.com/floci-io/floci/releases/latest)
[![Build Status](https://img.shields.io/github/actions/workflow/status/floci-io/floci/release.yml?label=build)](https://github.com/floci-io/floci/actions/workflows/release.yml)
[![Docker Pulls](https://img.shields.io/docker/pulls/floci/floci?label=docker%20pulls)](https://hub.docker.com/r/floci/floci)
[![Docker Image Size](https://img.shields.io/docker/image-size/floci/floci/latest?label=image%20size)](https://hub.docker.com/r/floci/floci)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://opensource.org/licenses/MIT)
[![GitHub Stars](https://img.shields.io/github/stars/floci-io/floci?style=flat)](https://github.com/floci-io/floci/stargazers)

[빠른 시작](#quick-start) ·
[기능](#features) ·
[지원 서비스](#supported-services) ·
[SDK 연동](#sdk-integration) ·
[Testcontainers](#testcontainers) ·
[마이그레이션](#migrating-from-localstack) ·
[문서](https://floci.io/floci/)

---
## Floci란 무엇인가요?
Floci는 개발, 테스트, CI를 위한 무료 오픈소스 로컬 AWS 에뮬레이터입니다.
클라우드 계정, 인증 토큰, 유료 기능 제한 없이 내 컴퓨터에서 AWS 형태의 서비스를 사용할 수 있게 해줍니다. AWS SDK, CLI, Terraform, CDK, OpenTofu 또는 테스트 모인(test suite)을 `http://localhost:4566`을 가리키도록 설정하고 기존 워크플로우를 그대로 유지하세요.
Floci는 팝콘처럼 생긴 구름인 [floccus](https://en.wikipedia.org/wiki/Cirrocumulus\_floccus)에서 이름을 따왔습니다.
## 빠른 시작
Floci를 실행하는 가장 빠른 방법은 공식 [CLI](https://github.com/floci-io/floci-cli)를 사용하는 것입니다.
```bash
floci start
```
AWS 환경 변수를 내보냅니다(export):
```bash
eval $(floci env)
```
기존 AWS 도구를 평소처럼 사용하세요:
```bash
aws s3 mb s3://my-bucket
aws dynamodb create-table \
--table-name demo-table \
--attribute-definitions AttributeName=pk,AttributeType=S \
--key-schema AttributeName=pk,KeyType=HASH \
--billing-mode PAY\_PER\_REQUEST
aws dynamodb list-tables
```
### 실행 모습 보기
이 짧은 데모는 CLI 흐름을 보여줍니다: Floci 시작, 로컬 AWS 환경 내보내기, 표준 AWS CLI 명령어 실행, 에뮬레이터 중지.
https://github.com/user-attachments/assets/b55714dc-ef36-40ae-a734-cd2cadc288a8
모든 AWS 서비스는 `http://localhost:4566`에서 사용할 수 있습니다. 어떤 리전이든 작동합니다. 엄격한 서비스별 인증 검사를 명시적으로 활성화하지 않는 한, 자격 증명은 빈 값이 아닌 어떤 값이든 상관없습니다.
Docker Compose를 선호하시나요?
`compose.yaml` 파일을 생성하세요:
```yaml
services:
floci:
image: floci/floci:latest
ports:
- "4566:4566"
```
Floci 시작하기:
```bash
docker compose up
```
그런 다음 AWS 환경을 수동으로 구성하세요:
```bash
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
```

기존의 `hectorvent/floci` 이미지를 사용하고 계신가요?
이미지 이름을 업데이트하세요:
```yaml
# Before
image: hectorvent/floci:latest
# After
image: floci/floci:latest
```
기존 `hectorvent/floci` 레포지토리는 더 이상 업데이트를 받지 않습니다.
## 기능
**클라우드 계정 없는 로컬 AWS**
AWS 계정, 인증 토큰, 유료 기능 제한 없이 AWS 호환 서비스를 로컬에서 실행하세요.

**충실도가 중요한 곳에서의 실제 Docker**
Lambda, RDS, Neptune, ElastiCache, MSK, ECS, EC2, EKS, OpenSearch, CodeBuild는 얕은 목(mock) 대신 실제 Docker 기반 실행을 사용합니다.

**드롭인(Drop-in) AWS 호환성**
표준 AWS 클라이언트를 `http://localhost:4566`으로 지정하세요. 기존 자격 증명, 리전, SDK, CLI 명령어, IaC 워크플로우를 그대로 친숙하게 사용할 수 있습니다.

**CI에 적합한 빠른 속도**
네이티브 이미지는 밀리초 단위로 시작하고 유휴 메모리를 낮게 유지하므로, 로컬 개발 및 테스트 파이프라인에 실용적입니다.

**설정 가능한 지속성(Persistence)**
필요한 내구성 프로필에 따라 인메모리, 지속형, 하이브리드, 선행 기입 로그(WAL) 스토리지 중에서 선택하세요.
## 왜 Floci인가요?
LocalStack의 커뮤니티 에디션은 [2026년 3월에 지원이 종료(sunset)](https://blog.localstack.cloud/the-road-ahead-for-localstack/)되어, 인증 토큰이 필요하게 되고 보안 업데이트가 동결됩니다. Floci는 조건 없는 대안입니다.
| 기능 | Floci | LocalStack Community |
|---|:---:|:---:|
| 인증 토큰 필요 여부 | 아니요 | 예 |
| 보안 업데이트 | 예 | 동결됨 |
| 시작 시간 | ~24 ms | ~3.3 s |
| 유휴 메모리 | ~13 MiB | ~143 MiB |
| Docker 이미지 크기 | ~90 MB | ~1.0 GB |
| 라이선스 | MIT | 제한됨 |
| API Gateway v2 / HTTP API | 예 | 아니요 |
| Cognito | 예 | 아니요 |
| RDS, ElastiCache, MSK | 실제 Docker | 아니요 |
| Neptune (그래프 DB + Gremlin WebSocket) | 실제 Docker | 아니요 |
| DocumentDB (MongoDB 호환) | 실제 Docker | 아니요 |
| ECS, EC2, EKS | 실제 Docker | 아니요 |
| CodeBuild | 실제 Docker 실행 | 아니요 |
| 네이티브 바이너리 | ~40 MB | 아니요 |
\*\*69개의 AWS 서비스. 넓은 커버리지. 영구 무료.\*\*
## 아키텍처 개요
```mermaid
flowchart LR
Client["AWS SDK / CLI"]
subgraph Floci ["Floci, port 4566"]
Router["HTTP Router\nJAX-RS / Vert.x"]
subgraph Stateless ["Stateless Services"]
A["SSM · SQS · SNS\nIAM · STS · KMS\nSecrets Manager · SES\nCognito · Kinesis\nEventBridge · Scheduler · AppConfig\nCloudWatch · Step Functions\nCloudFormation · ACM · Config · CloudTrail\nAPI Gateway · AppSync · ELB v2 · Auto Scaling\nElastic Beanstalk · CodeDeploy · CodePipeline · Backup · Bedrock Runtime · Route53 · Transfer"]
end
subgraph Stateful ["Stateful Services"]
B["S3 · DynamoDB\nDynamoDB Streams"]
end
subgraph Containers ["Container Services"]
C["Lambda\nElastiCache\nRDS\nNeptune\nECS\nEC2\nMSK\nEKS\nOpenSearch\nCodeBuild"]
D["Athena -> floci-duck\nDuckDB sidecar"]
end
Router --> Stateless
Router --> Stateful
Router --> Containers
Stateless & Stateful --> Store[("StorageBackend\nmemory · hybrid · persistent · wal")]
end
Docker["Docker Engine"]
Client -->|"HTTP :4566\nAWS wire protocol"| Router
Containers -->|"Docker API\nIAM / SigV4 auth"| Docker
```
## 지원 서비스
Floci는 애플리케이션 서비스, 데이터 서비스, 이벤트 처리, 신원 관리, 인프라, 빌링, 그리고 컨테이너 기반 워크로드를 위한 로컬 에뮬레이션을 지원합니다.
| 카테고리 | 서비스 |
|---|---|
| 핵심 앱 서비스 | S3, SQS, SNS, DynamoDB, Lambda, IAM, KMS, Secrets Manager, SSM |
| 이벤트 및 워크플로우 | EventBridge, EventBridge Pipes, EventBridge Scheduler, Step Functions, CloudWatch Logs, CloudWatch Metrics |
| API 및 신원 관리 | API Gateway REST, API Gateway v2, AppSync, Cognito, ACM, Route53, Cloud Map |
| 컨테이너 및 연산 | ECS, EC2, Lightsail, EKS, MWAA, ECR, CodeBuild, CodeDeploy, CodePipeline, AWS Batch, Auto Scaling, Elastic Beanstalk, ELB v2 |
| 데이터, 분석, AI | Athena, Glue, EMR, Firehose, OpenSearch, S3 Vectors, Textract, Transcribe, Bedrock Runtime |
| 데이터베이스 및 캐싱 | RDS, RDS Data API, Neptune, DocumentDB, MemoryDB, ElastiCache |
| 메시징 및 전송 | SES, Kinesis, MSK, Amazon MQ, Transfer Family, IoT Core |
| 보안 및 거버넌스 | WAF v2, CloudTrail, CloudFront, Resource Groups Tagging API |
| 비용 및 빌링 | Pricing, Cost Explorer, Cost and Usage Reports, BCM Data Exports |
| 백업 및 설정 | AWS Backup, AWS Config, AppConfig, AppConfigData, CloudFormation, Cloud Control API |
오퍼레이션 수준의 호환성은 [서비스 개요](https://floci.io/floci/services/)를 참조하세요.
상세 서비스 노트
| 서비스 | 작동 방식 | 주요 특징 |
|---|---|---|
| SSM | 프로세스 내(In-process) + EC2 컨테이너 | Parameter Store (버전 기록, 레이블, SecureString, 태깅); Run Command (SendCommand, GetCommandInvocation, 직접 EC2 컨테이너 실행, 에이전트 폴링) |
| SQS | 프로세스 내 | 표준 및 FIFO 큐, DLQ, 가시성 타임아웃, 배치 작업, 태깅 |
| SNS | 프로세스 내 | 토픽, 구독, SQS, Lambda 및 HTTP 전달, 태깅 |
| S3 | 프로세스 내 | 버전 관리, 멀티파트 업로드, 사전 서명된 URL(pre-signed URL), Object Lock, 이벤트 알림 |
| S3 Vectors | 프로세스 내 | 벡터 버킷, 인덱스, 벡터 put / get / list / delete, 코사인 유사도 쿼리 |
| DynamoDB | 프로세스 내 | GSI, LSI, Query, Scan, TTL, 트랜잭션, 배치 작업; 샤드 이터레이터 및 Lambda 이벤트 소스 매핑이 포함된 스트림 |
| Lambda | 실제 Docker | 런타임 환경, 실행 모델, 웜 컨테이너 풀, 별칭(alias), Function URL |
| API Gateway REST | 프로세스 내 | 리소스, 메서드, 스테이지, Lambda 프록시, MOCK 통합, AWS 통합 |
| API Gateway v2 | 프로세스 내 | HTTP API, 라우트, 통합, JWT 인증자, 스테이지 |
| AppSync | 프로세스 내 | GraphQL API 관리 API, 스키마 레지스트리, AWS 스칼라, 도메인 이름, 채널 네임스페이스 |
| IAM | 프로세스 내 | 사용자, 역할, 그룹, 정책, 인스턴스 프로필, 액세스 키; STS AssumeRole, WebIdentity, SAML, GetFederationToken, GetSessionToken |
| Cognito | 프로세스 내 | 사용자 풀, 앱 클라이언트, 인증 흐름, JWKS 및 OpenID 웰노운(well-known) 엔드포인트 |
| KMS | 프로세스 내 | 암호화(Encrypt), 복호화(Decrypt), 서명(sign), 검증(verify), 데이터 키, 별칭 |
| Kinesis | 프로세스 내 | 스트림, 샤드, 향상된 팬아웃(enhanced fan-out), 분할 및 병합 |
| Secrets Manager | 프로세스 내 | 버전 관리, 리소스 정책, 태깅 |
| Step Functions | 프로세스 내 | ASL 실행, 태스크 토큰, 실행 기록 |
| CloudFormation | 프로세스 내 | 스택, 변경 세트, 리소스 프로비저닝, StackSets (크로스 계정 인스턴스) |
| EventBridge | 프로세스 내 | 커스텀 버스, 규칙, SQS, SNS 및 Lambda 타겟 |
| EventBridge Pipes | 프로세스 내 | 선택적 필터링을 사용하여 SQS, Kinesis, DynamoDB, MSK 소스를 타겟에 연결하는 폴러 기반 통합 |
| EventBridge Scheduler | 프로세스 내 | 일정 그룹, 일정, 유연한 시간 창, 재시도 정책, DLQ |
| CloudWatch Logs | 프로세스 내 | 로그 그룹, 스트림, 수집(ingestion), 필터링 |
| CloudWatch Metrics | 프로세스 내 | 커스텀 메트릭, 통계, 경보(alarm) |
| ElastiCache | 실제 Docker | Redis / Valkey 프로토콜, IAM 인증, SigV4 검증 |
| MemoryDB | 실제 Docker | 실제 컨테이너를 통한 Redis / Valkey 프로토콜; JSON 1.1 제어 평면; ElastiCache RESP 프록시 재사용 |
| RDS | 실제 Docker | PostgreSQL, MySQL, MariaDB, IAM 인증, JDBC 호환 엔진 |
| RDS Data API | 실제 RDS 컨테이너를 통한 REST JSON | 로컬 MySQL / MariaDB RDS 리소스를 위한 원시 SQL 실행 및 트랜잭션 |
| Neptune | 실제 Docker | TinkerPop Gremlin Server(기본값) 또는 openCypher/Bolt용 Neo4j(`NEPTUNE\_DB\_TYPE`)를 통한 그래프 DB; RDS 형태의 제어 평면; 포트 8182의 SigV4 프록시 |
| DocumentDB | 실제 Docker, 목 모드 지원 | 실제 MongoDB 컨테이너를 통한 MongoDB 호환 클러스터; RDS 형태의 제어 평면; 포트 27017의 MongoDB 와이어 프로토콜 |
| MSK | 실제 Docker | Redpanda를 통한 Kafka 호환 브로커 |
| Amazon MQ | 실제 Docker | rabbitmq:3-management를 통한 RabbitMQ 브로커; AMQP + 관리 콘솔 |
| Athena | DuckDB 사이드카가 포함된 프로세스 내 | S3 및 Glue 기반 뷰에 대한 실제 SQL 실행 |
| Glue | 프로세스 내 | 데이터 카탈로그, 스키마 레지스트리, Athena에서 소비하는 테이블 |
| EMR | 프로세스 내 | 클러스터(작업 흐름) 수명 주기, 인스턴스 그룹 및 플릿, 단계(step), 보안 구성, 태깅 |
| Data Firehose | 프로세스 내 | 스트리밍 전달, S3로의 NDJSON 플러시 |
| ECS | 실제 Docker | 클러스터, 태스크 정의, 태스크, 서비스, 용량 공급자(capacity provider), 태스크 세트 |
| EC2 | 실제 Docker | RunInstances를 통한 컨테이너 시작, SSH 키 주입, UserData, IMDS, VPC 리소스 |
| Lightsail | 프로세스 내 | 인스턴스, 디스크, 고정 IP, 키 페어, 포트, 태그, 리전, 블루프린트, 번들, 작업 |
| ACM | 프로세스 내 | 인증서 발급 및 검증 수명 주기 |
| ECR | 실제 레지스트리가 포함된 프로세스 내 | 리포지토리, docker push / pull, 이미지 기반 Lambda 함수 |
| Resource Groups Tagging API | 프로세스 내 | GetResources, 리소스 태그 추가/제거, 서비스 전반의 태그 키 및 값 검색 |
| SES | 프로세스 내 | v1 및 v2 API: 이메일 전송, 원시 이메일, 신원 검증, DKIM, 템플릿, 구성 세트, 계정 전송 |
| OpenSearch | 실제 Docker | 도메인 CRUD, 태그, 버전, 인스턴스 유형, 업그레이드 스텁 |
| AppConfig | 프로세스 내 | 애플리케이션, 환경, 프로필, 호스팅된 버전, 배포 |
| AppConfigData | 프로세스 내 | 구성 세션 및 동적 구성 검색 |
| Bedrock Runtime | 프로세스 내 스텁 | 로컬 개발을 위한 가짜 Converse 및 InvokeModel 응답 |
| EKS | 실제 Docker, 목 모드 지원 | 라이브 Kubernetes API 서버가 포함된 k3s 클러스터 |
| MWAA | 실제 Docker, 목 모드 지원 | 환경별 자체 Postgres 메타데이터 DB가 포함된 실제 Apache Airflow (LocalExecutor); 웹/CLI 프록시; S3 기반 DAG 동기화 |
| ELB v2 | 프로세스 내 | ALB, NLB, 타겟 그룹, 리스너, 라우팅 규칙, Lambda 타겟, 태그 |
| CodeBuild | 실제 Docker가 포함된 프로세스 내 | 실제 buildspec 실행, CloudWatch 로그, S3 아티팩트 |
| CodeDeploy | 프로세스 내 (Lambda 트래픽 전환 포함) | 배포 그룹, 구성, 수명 주기 훅, 자동 롤백 |
| CodePipeline | 프로세스 내 오케스트레이션 | 파이프라인, 실행, S3 아티팩트, 승인, 로컬 제공자, 커스텀 워커 |
| AWS Batch | 프로세스 내 | 연산 환경, 작업 큐, 작업 정의, 작업 제출 및 수명 주기 |
| Auto Scaling | 프로세스 내 (reconciler 포함) | 시작 구성, ASG, 원하는 용량 조정(reconciliation), 수명 주기 훅 |
| Elastic Beanstalk | 프로세스 내 | 애플리케이션, 애플리케이션 버전, 환경, 구성 템플릿, 플랫폼 및 솔루션 스택 메타데이터 |
| AWS Backup | 프로세스 내 | 볼륨, 백업 계획, 선택 항목, 시뮬레이션된 작업 수명 주기, 복구 지점 |
| AWS Config | 프로세스 내 | 설정 규칙, 설정 레코더, 전달 채널, 준수 팩(conformance pack), 태깅 |
| CloudTrail | 프로세스 내 | 트레일, 이벤트 셀렉터(버킷/접두사 매칭이 포함된 S3 데이터 이벤트), `StartLogging`/`StopLogging`, AWS 형태의 키 경로에서 대상 버킷으로 예약된 gzipped 로그 파일 내보내기, IAM 거부 경로에서 `AccessDenied` 레코드 내보내기 |
| CloudFront | 프로세스 내 | 배포, 오리진, 캐시 동작, 무효화(invalidation), 태깅 |
| WAF v2 | 프로세스 내 | 웹 ACL, IP 세트, 정규 표현식 패턴 세트, 규칙 그룹, 로깅 구성, 리소스 연결, 태깅 (REGIONAL 및 CLOUDFRONT 범위) |
| Route53 | 프로세스 내 | 호스팅 영역, SOA 및 NS 레코드, 리소스 레코드 세트, 변경 추적, 태깅 |
| Cloud Map | 프로세스 내 | HTTP 및 DNS 네임스페이스, 서비스, 인스턴스 등록, 검색 쿼리, 작업, 태깅 |
| Transfer Family | 프로세스 내 | 서버 수명 주기, 사용자 관리, SSH 키 가져오기, 태깅 |
| Textract | 프로세스 내 스텁 | API 호환 스텁, 더미 블록 데이터, 비동기 작업 시뮬레이션 |
| Transcribe | 프로세스 내 스텁 | 전사(transcription) 작업 및 커스텀 어휘; 실제 오디오 처리 없이 작업 즉시 완료 |
| Pricing | 정적 스냅샷이 포함된 프로세스 내 | 제품 검색, 속성, 가격표 파일, 페이지네이션 |
| Cost Explorer | 프로세스 내 | Floci 리소스 상태 및 가격 스냅샷에서 합성된 비용 |
| Cost and Usage Reports | floci-duck 사이드카가 포함된 프로세스 내 | CUR 2.0 및 FOCUS 1.2 컬럼, 계정 범위 스토리지, Parquet 내보내기 |
| BCM Data Exports | 프로세스 내 | 내보내기 수명 주기, 실행, 업데이트 및 삭제 작업 |
## 실제 Docker 연동
Floci는 프로세스 내 에뮬레이션이 충실도를 떨어뜨릴 수 있는 경우 실제 Docker 컨테이너를 사용합니다. 이는 상태 저장 데이터베이스, 연결 집약적 프로토콜, 런타임, 빌드 시스템에 적용됩니다.
| 서비스 | 기본 이미지 | 실제 작동하는 부분 |
|---|---|---|
| Lambda | `public.ecr.aws/lambda/` | AWS 런타임 환경, 실행 모델, 웜 컨테이너 풀 |
| ElastiCache | `valkey/valkey:8` | Redis / Valkey 프로토콜, ACL 기반 IAM 인증, SigV4 검증 |
| RDS PostgreSQL | `postgres:16-alpine` | PostgreSQL 엔진, IAM 인증, JDBC 호환 액세스 |
| RDS MySQL / Aurora | `mysql:8.0` | MySQL 엔진, IAM 인증, JDBC 호환 액세스 |
| RDS MariaDB | `mariadb:11` | MariaDB 엔진, IAM 인증, JDBC 호환 액세스 |
| Neptune | `tinkerpop/gremlin-server:3.7.3` | TinkerPop Gremlin Server; 포트 8182의 Gremlin WebSocket; SigV4 인증 프록시 |
| Neptune (openCypher) | `neo4j:5-community` | `FLOCI\_SERVICES\_NEPTUNE\_DB\_TYPE=neo4j` 시 Neo4j 백엔드; Bolt를 통한 openCypher |
| DocumentDB | `mongo:7.0` | MongoDB 엔진; 포트 27017의 MongoDB 와이어 프로토콜 |
| MSK | `redpandadata/redpanda:latest` | Redpanda를 통한 Kafka 호환 브로커 |
| Amazon MQ | `rabbitmq:3-management` | RabbitMQ 브로커; 포트 5672의 AMQP, 15672의 관리 콘솔 |
| EC2 | AMI 매핑된 Linux 이미지 | Linux 컨테이너, SSH 키 주입, UserData, IMDS, IAM 자격 증명 |
| ECS | 사용자가 지정한 태스크 이미지 | 컨테이너 수명 주기, 시작, 중지, 상태 검사 |
| EKS | `rancher/k3s:latest` | k3s를 통한 Kubernetes API 서버 |
| MWAA | `apache/airflow:-python3.12` + `postgres:16-alpine` | 자체 Postgres 메타데이터 DB가 있는 실제 Apache Airflow (LocalExecutor: scheduler + webserver); Floci의 프록시를 통해 접근 가능한 webserver/CLI |
| CodeBuild | 사용자가 지정한 환경 이미지 | Buildspec 실행, 로그 스트리밍, S3 아티팩트 업로드 |
| OpenSearch | `opensearchproject/opensearch:2` | REST API가 포함된 완전한 OpenSearch 엔진 |
| ECR | `registry:2` | docker push 및 docker pull을 위한 OCI 호환 레지스트리 |
Docker 기반 서비스는 Docker 소켓이 필요합니다:
```bash
docker run -d --name floci \
-p 4566:4566 \
-v /var/run/docker.sock:/var/run/docker.sock \
-u root \
floci/floci:latest
```
### 기본 이미지 오버라이드
| 변수 | 기본값 |
|---|---|
| `FLOCI\_SERVICES\_ELASTICACHE\_DEFAULT\_IMAGE` | `valkey/valkey:8` |
| `FLOCI\_SERVICES\_RDS\_DEFAULT\_POSTGRES\_IMAGE` | `postgres:16-alpine` |
| `FLOCI\_SERVICES\_RDS\_DEFAULT\_MYSQL\_IMAGE` | `mysql:8.0` |
| `FLOCI\_SERVICES\_RDS\_DEFAULT\_MARIADB\_IMAGE` | `mariadb:11` |
| `FLOCI\_SERVICES\_MSK\_DEFAULT\_IMAGE` | `redpandadata/redpanda:latest` |
| `FLOCI\_SERVICES\_OPENSEARCH\_DEFAULT\_IMAGE` | `opensearchproject/opensearch:2` |
| `FLOCI\_SERVICES\_NEPTUNE\_DEFAULT\_IMAGE` | `tinkerpop/gremlin-server:3.7.3` |
| `FLOCI\_SERVICES\_NEPTUNE\_DEFAULT\_NEO4J\_IMAGE` | `neo4j:5-community` |
| `FLOCI\_SERVICES\_DOCDB\_DEFAULT\_IMAGE` | `mongo:7.0` |
| `FLOCI\_SERVICES\_EKS\_DEFAULT\_IMAGE` | `rancher/k3s:latest` |
| `FLOCI\_SERVICES\_MWAA\_DEFAULT\_POSTGRES\_IMAGE` | `postgres:16-alpine` |
| `FLOCI\_SERVICES\_ECR\_REGISTRY\_IMAGE` | `registry:2` |
| `FLOCI\_ECR\_BASE\_URI` | `public.ecr.aws` |
## 지속성 및 스토리지 모드
Floci는 워크플로우에 따라 속도와 내사이에서 선택할 수 있습니다. `FLOCI\_STORAGE\_MODE`로 기본 모드를 설정하거나, 서비스별로 스토리지를 오버라이드하세요.
| 모드 | 동작 | 최적 용도 | 내구성 |
|---|---|---|:---:|
| `memory` | 완전히 RAM에 저장됨. 컨테이너가 중지되면 데이터가 손실됨. | CI 및 임시 테스트 | 없음 |
| `persistent` | 시작 시 로드되며 모든 쓰기 작업 시 디스크에 즉시 플러시됨. | 즉시 지속성이 필요한 단순 로컬 상태 유지 | 보통 |
| `hybrid` | 5초마다 주기적인 비동기 플러시가 포함된 인메모리 성능. | 로컬 개발 | 좋음 |
| `wal` | 선행 기입 로그(Write-ahead log). 응답하기 전에 모든 변경 사항이 기록됨. | 최고 수준의 내구성 | 최고 |
빠른 테스트 실행에는 `memory`를 사용하세요. 오버헤드 없이 컨테이너 재시작 간에 상태가 유지되도록 하려면 `hybrid`를 사용하세요.
자세한 내용은 [스토리지 설정 문서](https://floci.io/floci/configuration/storage/)를 참조하세요.
## 멀티 계정 격리
Floci는 추가 설정 없이 계정별 리소스 격리를 지원합니다. `AWS\_ACCESS\_KEY\_ID`가 정확히 12자리 숫자인 경우, Floci는 이를 계정 ID로 사용합니다. 한 계정에 의해 생성된 리소스는 다른 계정에서 볼 수 없습니다.
```bash
AWS\_ACCESS\_KEY\_ID=111111111111 aws sqs create-queue --queue-name orders
AWS\_ACCESS\_KEY\_ID=222222222222 aws sqs create-queue --queue-name orders
```
`test` 또는 `AKIA...`와 같은 다른 키 형식의 경우, Floci는 기본값인 `000000000000`으로 설정된 `FLOCI\_DEFAULT\_ACCOUNT\_ID`로 대체(fallback)됩니다.
STS 임시 자격 증명도 라우팅됩니다: `AssumeRole`의 자격 증명은 가정된 역할(assumed role)의 계정으로 확인되므로, 크로스 계정 assume-role-then-provision 패턴이 로컬에서 작동합니다. 해석 우선순위는 12자리 AKID → 임시 세션 조회 → `FLOCI\_DEFAULT\_ACCOUNT\_ID` 순입니다.
[멀티 계정 격리 문서](https://floci.io/floci/configuration/multi-account/)를 참조하세요.
## SDK 연동
기존 AWS SDK가 `http://localhost:4566`을 가리키도록 설정하세요.
**Java, AWS SDK v2**
```java
var client = DynamoDbClient.builder()
.endpointOverride(URI.create("http://localhost:4566"))
.region(Region.US\_EAST\_1)
.credentialsProvider(StaticCredentialsProvider.create(
AwsBasicCredentials.create("test", "test")))
.build();
client.createTable(b -> b
.tableName("demo-table")
.billingMode(BillingMode.PAY\_PER\_REQUEST)
.attributeDefinitions(
AttributeDefinition.builder().attributeName("pk").attributeType(ScalarAttributeType.S).build())
.keySchema(
KeySchemaElement.builder().attributeName("pk").keyType(KeyType.HASH).build()));
System.out.println(client.listTables().tableNames());
```

**Python, boto3**
```python
import boto3
client = boto3.client(
"ssm",
endpoint\_url="http://localhost:4566",
region\_name="us-east-1",
aws\_access\_key\_id="test",
aws\_secret\_access\_key="test",
)
client.put\_parameter(
Name="/demo/app/message",
Value="hello from floci",
Type="String",
Overwrite=True,
)
response = client.get\_parameter(Name="/demo/app/message")
print(response["Parameter"]["Value"])
```

**Node.js, AWS SDK v3**
```javascript
import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";
const client = new SQSClient({
endpoint: "http://localhost:4566",
region: "us-east-1",
credentials: { accessKeyId: "test", secretAccessKey: "test" },
});
await client.send(
new SendMessageCommand({
QueueUrl: "http://localhost:4566/000000000000/demo-queue",
MessageBody: "hello from floci",
}),
);
```

**Go, AWS SDK v2**
```go
package main
import (
"context"
"fmt"
"log"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/credentials"
"github.com/aws/aws-sdk-go-v2/service/s3"
)
func main() {
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithRegion("us-east-1"),
config.WithCredentialsProvider(
credentials.NewStaticCredentialsProvider("test", "test", ""),
),
config.WithBaseEndpoint("http://localhost:4566"),
)
if err != nil {
log.Fatal(err)
}
client := s3.NewFromConfig(cfg, func(o \*s3.Options) {
o.UsePathStyle = true
})
out, err := client.ListBuckets(context.TODO(), nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(out.Buckets)
}
```

**Rust, AWS SDK**
```rust
use aws\_sdk\_secretsmanager::config::{Credentials, Region};
use aws\_sdk\_secretsmanager::Client;
#[tokio::main]
async fn main() -> Result<(), Box> {
let config = aws\_config::defaults(aws\_config::BehaviorVersion::latest())
.region(Region::new("us-east-1"))
.credentials\_provider(Credentials::new("test", "test", None, None, "floci"))
.endpoint\_url("http://localhost:4566")
.load()
.await;
let client = Client::new(&config);
client
.create\_secret()
.name("demo/secret")
.secret\_string("hello from floci")
.send()
.await?;
Ok(())
}
```

**Bash, AWS CLI**
```bash
export AWS\_ACCESS\_KEY\_ID=test
export AWS\_SECRET\_ACCESS\_KEY=test
export AWS\_DEFAULT\_REGION=us-east-1
aws --endpoint-url http://localhost:4566 s3 mb s3://my-bucket
aws --endpoint-url http://localhost:4566 s3 ls
```
## Testcontainers
Floci는 테스트에서 격리된 Floci 인스턴스를 직접 시작하기 위한 Testcontainers 모듈을 제공합니다. 이를 통해 공유 상태, 수동 데몬 설정, 포트 충돌을 방지할 수 있습니다.
| 언어 | 패키지 | 최신 버전 | 레지스트리 | 소스 |
|---|---|---|---|---|
| Java | `io.floci:testcontainers-floci` | `1.4.0` | [Maven Central](https://mvnrepository.com/artifact/io.floci/testcontainers-floci) | [GitHub](https://github.com/floci-io/testcontainers-floci) |
| Node.js | `@floci/testcontainers` | `0.1.0` | [npm](https://www.npmjs.com/package/@floci/testcontainers) | [GitHub](https://github.com/floci-io/testcontainers-floci-node) |
| Python | `testcontainers-floci` | `0.1.1` | [PyPI](https://pypi.org/project/testcontainers-floci/) | [GitHub](https://github.com/floci-io/testcontainers-floci-python) |
| Go | 개발 중 | 개발 중 | N/A | [GitHub](https://github.com/floci-io/testcontainers-floci-go) |
**Java**
```xml
io.floci
testcontainers-floci
1.4.0
test
```
```java
@Testcontainers
class S3IntegrationTest {
@Container
static FlociContainer floci = new FlociContainer();
@Test
void shouldCreateBucket() {
S3Client s3 = S3Client.builder()
.endpointOverride(URI.create(floci.getEndpoint()))
.region(Region.of(floci.getRegion()))
.credentialsProvider(StaticCredentialsProvider.create(
AwsBasicCredentials.create(floci.getAccessKey(), floci.getSecretKey())))
.forcePathStyle(true)
.build();
s3.createBucket(b -> b.bucket("my-bucket"));
}
}
```
Testcontainers 2.x / Spring Boot 4.x의 경우 버전 `2.5.0`을 사용하세요.

**Node.js / TypeScript**
```sh
npm install --save-dev @floci/testcontainers
```
```ts
import { FlociContainer } from "@floci/testcontainers";
import { S3Client, CreateBucketCommand } from "@aws-sdk/client-s3";
describe("S3", () => {
let floci: FlociContainer;
beforeAll(async () => {
floci = await new FlociContainer().start();
});
afterAll(async () => {
await floci.stop();
});
it("creates a bucket", async () => {
const s3 = new S3Client({
endpoint: floci.getEndpoint(),
region: floci.getRegion(),
credentials: {
accessKeyId: floci.getAccessKey(),
secretAccessKey: floci.getSecretKey(),
},
forcePathStyle: true,
});
await s3.send(new CreateBucketCommand({ Bucket: "my-bucket" }));
});
});
```

**Python**
```sh
pip install testcontainers-floci
```
```python
import boto3
from testcontainers\_floci import FlociContainer
def test\_s3\_create\_bucket():
with FlociContainer() as floci:
s3 = boto3.client(
"s3",
endpoint\_url=floci.get\_endpoint(),
region\_name=floci.get\_region(),
aws\_access\_key\_id=floci.get\_access\_key(),
aws\_secret\_access\_key=floci.get\_secret\_key(),
)
s3.create\_bucket(Bucket="my-bucket")
```
## 호환성 테스트
[`compatibility-tests`](./compatibility-tests/) 디렉터리는 SDK 및 도구 워크플로 전반에서 Floci의 유효성을 검증합니다.
| 모듈 | 언어 / 도구 | SDK / 클라이언트 | 테스트 수 |
|---|---|---|---:|
| `sdk-test-java` | Java 17 | AWS SDK for Java v2 | 1,326 |
| `sdk-test-node` | Node.js | AWS SDK for JavaScript v3 | 449 |
| `sdk-test-python` | Python 3 | boto3 | 311 |
| `sdk-test-go` | Go | AWS SDK for Go v2 + RDS Data API SDK v1 | 157 |
| `sdk-test-awscli` | Bash | AWS CLI v2 | 205 |
| `compat-terraform` | Terraform | v1.10+ | 22 |
| `compat-opentofu` | OpenTofu | v1.9+ | 16 |
| `compat-cdk` | AWS CDK | v2+ | 20 |
\*\*5개의 SDK와 3개의 IaC 도구에 걸쳐 총 2,506개의 자동화된 호환성 테스트가 수행됩니다.\*\*
## LocalStack에서 마이그레이션하기
Floci는 LocalStack Community를 대체할 수 있는 드롭인(drop-in) 대체재입니다. 포트, 자격 증명, SDK 구성 및 CLI 엔드포인트 패턴이 동일하게 작동합니다. 이미지만 교체하고 계속 사용하세요.
```yaml
# Before
image: localstack/localstack
# After, standard image
image: floci/floci:latest
# After, if init scripts need AWS CLI or boto3
image: floci/floci:latest-compat
```
LocalStack 환경 변수는 자동으로 변환됩니다:
| LocalStack | Floci 동등 항목 |
|---|---|
| `LOCALSTACK\_HOST` | `FLOCI\_HOSTNAME` |
| `PERSISTENCE=1` | `FLOCI\_STORAGE\_MODE=persistent` |
| `LAMBDA\_DOCKER\_NETWORK` | `FLOCI\_SERVICES\_LAMBDA\_DOCKER\_NETWORK` |
| `LAMBDA\_REMOVE\_CONTAINERS=1` | `FLOCI\_SERVICES\_LAMBDA\_EPHEMERAL=true` |
| `DEBUG=1` | `QUARKUS\_LOG\_LEVEL=DEBUG` |
`/etc/localstack/init/` 아래에 마운트된 초기화 스크립트는 변경 없이 그대로 실행됩니다. `/\_localstack/init` 및 `/\_localstack/health` 엔드포인트도 계속 제공됩니다. 에뮬레이터가 실행되면 로그의 마지막 줄에 LocalStack 스타일의 `Ready.`가 표시되므로, Testcontainers의 `LocalStackContainer` 기본 대기 전략과 같이 이를 감시하는 도구들도 변경 없이 그대로 작동합니다. 자동 변환을 사용하지 않으려면 `LOCALSTACK\_PARITY=false`로 설정하세요.
[전체 마이그레이션 가이드](https://floci.io/floci/getting-started/migrate-from-localstack/)를 참조하세요.
## 이미지 태그
모든 태그는 변형(variant)과 채널(channel)의 조합으로 이루어집니다.
| 채널 | 표준 | AWS CLI 및 boto3 포함 호환 버전 |
|---|---|---|
| 릴리스, 플로팅 | `latest` | `latest-compat` |
| 릴리스, 고정 | `x.y.z` | `x.y.z-compat` |
| 나이트리, 플로팅 | `nightly` | `nightly-compat` |
| 나이트리, 날짜 지정 | `nightly-mmddyyyy` | `nightly-mmddyyyy-compat` |
안정적인 릴리스에는 `latest`를 사용하고, 재현 가능한 빌드를 위해서는 고정된 버전을 사용하며, `main` 브랜치를 추적하려면 `nightly`를 사용하세요.
```yaml
# Recommended
image: floci/floci:latest
# Includes AWS CLI and boto3
image: floci/floci:latest-compat
# Pinned release
image: floci/floci:1.5.11
# Track main
image: floci/floci:nightly
```
## 구성
모든 설정은 `FLOCI\_` 접두사가 붙은 환경 변수를 통해 재정의할 수 있습니다.
| 변수 | 기본값 | 설명 |
|---|---|---|
| `FLOCI\_PORT` | `4566` | Floci API에서 노출하는 포트 |
| `FLOCI\_DEFAULT\_REGION` | `us-east-1` | 기본 AWS 리전 |
| `FLOCI\_DEFAULT\_ACCOUNT\_ID` | `000000000000` | 기본 AWS 계정 ID |
| `FLOCI\_BASE\_URL` | `http://localhost:4566` | Floci가 서비스 URL을 반환할 때 사용하는 기본 URL |
| `FLOCI\_HOSTNAME` | 설정되지 않음 | Floci가 Docker Compose 내에서 실행될 때 반환되는 URL에 사용되는 호스트 이름 |
| `FLOCI\_STORAGE\_MODE` | `memory` | 스토리지 모드: `memory`, `persistent`, `hybrid`, 또는 `wal` |
| `FLOCI\_STORAGE\_PERSISTENT\_PATH` | `./data` | 지속성 상태를 저장하는 데 사용되는 디렉터리 |
| `FLOCI\_ECR\_BASE\_URI` | `public.ecr.aws` | 컨테이너 이미지를 풀(pull)할 때 사용하는 ECR 기본 URI |
| `FLOCI\_SERVICES\_S3\_ENFORCE\_AUTH` | `false` | S3 공개/비공개 읽기 권한을 강제하고 알 수 없는 서명된 S3 액세스 키를 거부합니다. |
전체 레퍼런스: [구성 문서](https://floci.io/floci/configuration/advanced/application-yml)
### 멀티 컨테이너 Docker Compose
애플리케이션이 다른 컨테이너에서 실행되는 경우, SQS `QueueUrl` 값과 같이 반환된 URL이 올바르게 resolve되도록 `FLOCI\_HOSTNAME`을 Floci 서비스 이름으로 설정하세요.
```yaml
services:
floci:
image: floci/floci:latest
ports:
- "4566:4566"
environment:
- FLOCI\_HOSTNAME=floci
my-app:
environment:
- AWS\_ENDPOINT\_URL=http://floci:4566
depends\_on:
- floci
```
이렇게 하지 않으면 서비스가 `localhost`를 사용하는 URL을 반환하여, 애플리케이션 컨테이너 관점에서 잘못된 컨테이너를 가리키게 될 수 있습니다.
## 커뮤니티
[Slack](https://join.slack.com/t/floci/shared\_invite/zt-3tjn02s3q-A00kEjJ1cZxsg\_imTfy6Cw) 또는 [GitHub Discussions](https://github.com/orgs/floci-io/discussions)에서 Floci 커뮤니티에 참여하세요. 기능 아이디어, 호환성 질문, 디자인 절충안, 대략적인 제안 등 무엇이든 환영합니다.
## 스폰서
Floci는 사용자의 지원으로 운영되는 독립 오픈소스입니다. Floci가 시간을 절약해 주었다면 [프로젝트 후원하기](https://github.com/sponsors/floci-io)를 고려해 보세요. 모든 후원은 에뮬레이터를 빠르고 가볍고 무료로 유지하는 데 큰 도움이 됩니다.
### 🥇 골드
최상단 배치의 대형 로고, 전담 지원 채널, 로드맵 우선순위 의견 제시, 맞춤형 통합 지원.
\*여기에 귀하의 로고를 — [골드 스폰서 되기](https://github.com/sponsors/floci-io).\*
### 🥈 실버
이 README 및 floci.io에 로고 노출, 우선순위 이슈 지원, 릴리스 노트 언급.
\*여기에 귀하의 로고를 — [실버 스폰서 되기](https://github.com/sponsors/floci-io).\*
### 🥉 커뮤니티
이 README에 이름 기재, GitHub 스폰서 배지, 그리고 진심 어린 감사.
- [Nexxion.ai](https://github.com/Nexxion-ai)
- [Your name here](https://github.com/sponsors/floci-io)
## 스타 히스토리

[![Star History Chart](https://api.star-history.com/chart?repos=floci-io/floci&type=date&legend=top-left)](https://www.star-history.com/?repos=floci-io%2Ffloci&type=date&legend=top-left)

## 기여자
[![](https://contrib.rocks/image?repo=floci-io/floci&max=100&columns=20)](https://github.com/floci-io/floci/graphs/contributors)
## 라이선스
MIT. 원하시는 대로 자유롭게 사용하세요.

floci

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README