Floci 딥다이브
— 무료 오픈소스 AWS 로컬 에뮬레이터

1프로젝트 한줄 요약

Floci는 로컬 환경에서 AWS 서비스 54개 이상을 에뮬레이션하는 무료 오픈소스 도구입니다. docker compose up 한 줄이면 S3, DynamoDB, Lambda, SQS 등을 인증 토큰 없이 즉시 사용할 수 있습니다. Java + Quarkus + GraalVM 네이티브 이미지로 만들어져 시작 시간 24ms, 유휴 메모리 13MiB라는 극한의 경량화를 달성했습니다.

2왜 주목받는가

LocalStack vs Floci 상세 비교

3기술 스택 전체 지도

① 백엔드 코어

② 인프라 / 빌드

③ 지원하는 AWS 프로토콜

4아키텍처 심화 분석

전체 시스템 구조도

핵심 설계 패턴 5가지

1. 단일 엔드포인트 멀티플렉싱 (Port 4566)

모든 AWS 서비스가 하나의 포트(4566)에서 서비스됩니다. 요청의 Authorization 헤더나 X-Amz-Target 헤더를 분석하여 어떤 서비스로 라우팅할지 결정합니다.

2. 프로토콜 어댑터 패턴

AWS 서비스마다 다른 프로토콜(REST XML, JSON 1.1, Query)을 사용합니다. Floci는 각 프로토콜에 대한 파서를 두고, 내부적으로는 통일된 서비스 인터페이스로 변환합니다.

3. 플러거블 스토리지 엔진

4가지 스토리지 모드를 서비스별로 독립 설정합니다. DynamoDB는 WAL, S3는 Persistent, 단위 테스트는 Memory처럼 용도에 맞게 조합할 수 있습니다.

floci:
  storage:
    mode: hybrid                    # 글로벌 기본값
    persistent-path: ./data
    wal:
      compaction-interval: 30s
    services:
      dynamodb:
        mode: wal                   # DynamoDB만 WAL 모드
      s3:
        mode: persistent            # S3는 동기 저장

4. Docker-in-Docker (Lambda 실행)

Lambda 서비스는 docker-java 라이브러리를 통해 실제 Docker 컨테이너를 생성하여 함수를 실행합니다. Docker 소켓(/var/run/docker.sock)을 마운트하는 이유가 바로 이것입니다.

5. Wire Proxy 패턴 (RDS/ElastiCache)

RDS와 ElastiCache는 단순 HTTP API가 아니라 실제 데이터베이스 프로토콜을 에뮬레이션합니다. 실제 psql, redis-cli로 직접 접속할 수 있습니다.

5디렉토리 구조 해부

6학습 포인트 (기술별)

6.1 Quarkus + GraalVM 네이티브 이미지

Quarkus의 빌드 타임 최적화가 어떻게 24ms 시작 시간을 달성하는지, GraalVM Mandrel을 사용한 네이티브 컴파일 파이프라인, 리플렉션 제한 환경에서의 Java 프로그래밍 패턴을 배웁니다.

6.2 Docker 멀티스테이지 빌드

# Stage 1: 빌드 (Mandrel builder, 수 GB)
FROM quay.io/quarkus/ubi-quarkus-mandrel-builder-image:jdk-24 AS build
COPY pom.xml .
RUN mvn dependency:go-offline        # 의존성 캐시 레이어
COPY src ./src
RUN mvn clean package -Dnative -DskipTests

# Stage 2: 런타임 (마이크로 이미지, ~90MB)
FROM quay.io/quarkus/quarkus-micro-image:2.0
COPY --from=build /app/target/*-runner /app/application
ENTRYPOINT ["/app/application"]

6.3 플러거블 스토리지 아키텍처

인터페이스 기반 스토리지 추상화 설계, Memory/Persistent/Hybrid/WAL 4가지 모드의 트레이드오프, WAL(Write-Ahead Log) 구현: append-only 쓰기 + 30초 주기 컴팩션, 서비스별 스토리지 모드 독립 설정을 배웁니다.

6.4 AWS 프로토콜 에뮬레이션

AWS SDK가 내부적으로 사용하는 4가지 프로토콜(REST XML, REST JSON, JSON 1.1, Query), 단일 포트(4566)에서 멀티 프로토콜 라우팅, X-Amz-Target 헤더를 이용한 서비스 디스패칭을 배웁니다.

6.5 Docker-in-Docker 패턴

docker-java 라이브러리를 사용한 프로그래매틱 컨테이너 관리, Docker 소켓 마운트의 보안 고려사항, Lambda 함수를 Docker 컨테이너로 격리 실행하는 패턴을 배웁니다.

6.6 Wire Proxy 패턴

PostgreSQL/MySQL 와이어 프로토콜을 Java로 구현하는 방법, Redis RESP 프로토콜 프록시 구현, IAM 인증을 데이터베이스 프로토콜 레벨에서 처리하는 패턴을 배웁니다.

7하드웨어 / 시스템 요구사항

Lambda 사용 시 추가 요구사항: Docker 소켓 접근 권한, 최초 1회 Lambda 런타임 이미지 다운로드, 함수 크기에 따라 128MB~512MB 추가 RAM.

RDS/ElastiCache 추가 포트: PostgreSQL proxy 7001~7099, Redis proxy 6379~6399.

8직접 해볼 수 있는 실습 과제

docker run -d -p 4566:4566 floci/floci:latest
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

aws s3 mb s3://my-test-bucket
echo "Hello Floci" > test.txt
aws s3 cp test.txt s3://my-test-bucket/
aws sqs create-queue --queue-name my-queue
aws sqs send-message --queue-url http://localhost:4566/000000000000/my-queue \
  --message-body '{"event":"file_uploaded","key":"test.txt"}'

# provider.tf
provider "aws" {
  region                      = "us-east-1"
  access_key                  = "test"
  secret_key                  = "test"
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  endpoints {
    s3       = "http://localhost:4566"
    dynamodb = "http://localhost:4566"
    lambda   = "http://localhost:4566"
  }
}

# .github/workflows/test.yml
services:
  floci:
    image: floci/floci:latest
    ports:
      - 4566:4566
    env:
      FLOCI_STORAGE_MODE: memory  # CI 속도 최적화

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

• GitHub — floci-io/floci
• 공식 문서 — floci.io/floci
• Hacker News 토론
• Quarkus 공식 가이드
• GraalVM Native Image 문서
• AWS SDK 엔드포인트 설정 가이드
• TrendShift