Floci入門 — 無料軽量AWSローカルエミュレータの使い方を徹底解説【2026年版】

この記事でわかること

• Floci（フロチ）の概要と選ばれる理由
• DockerとネイティブバイナリでのFlociインストール方法
• docker-compose.yml と環境変数の基本設定
• ストレージモード4種（memory/persistent/hybrid/wal）の使い分け
• よくあるエラーとトラブルシューティング

Floci は、Quarkusで実装された軽量なAWSローカルエミュレータです。LocalStackコミュニティ版が2026年3月に認証必須となったことで、無料・MITライセンス・オフライン可の代替として注目を集めています。本記事ではFlociの基本的な使い方を、インストールから実運用の勘所までハンズオン形式で解説します。

Flociとは？ — LocalStackとの違いを3行で

• Quarkusベースのネイティブ実装で、起動24ms・メモリ13MiBの超軽量
• MITライセンスで商用利用・再配布・改変が自由
• http://localhost:4566 のエンドポイントでLocalStackと互換

対応サービスは S3 / DynamoDB / Lambda / SQS / SNS / IAM / Cognito / EventBridge など24種類。本番AWSで使われる主要サービスのローカル開発・CI検証をカバーできます。

比較の詳細は LocalStack vs Floci 比較記事 を参照してください。

動作要件

ネイティブバイナリを使う場合はDocker不要です。

インストール方法

方法1: Docker（推奨）

docker pull hectorvent/floci:latest
docker run -d --name floci -p 4566:4566 hectorvent/floci:latest

起動確認:

curl http://localhost:4566/_floci/health

方法2: docker-compose

プロジェクトルートに docker-compose.yml を配置:

services:
  floci:
    image: hectorvent/floci:latest
    ports:
      - "4566:4566"
    volumes:
      - ./data:/app/data
    environment:
      - FLOCI_STORAGE_MODE=memory

docker compose up -d

方法3: ネイティブバイナリ

GitHub Releases から自OS用バイナリをダウンロード:

chmod +x floci
./floci

Quarkus GraalVMネイティブビルドのため、Javaランタイム不要で起動します。

疎通確認 — S3で動作テスト

AWS CLIが必要です（brew install awscli など）。

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 s3 ls s3://my-test-bucket/

出力に test.txt が表示されれば成功です。

ストレージモード4種の使い分け

Floci最大の特徴は 4種類のストレージモード を用途別に選べる点です。

設定例

services:
  floci:
    image: hectorvent/floci:latest
    ports:
      - "4566:4566"
    environment:
      - FLOCI_STORAGE_MODE=persistent
      - FLOCI_STORAGE_PERSISTENT_PATH=/app/data
    volumes:
      - ./floci-data:/app/data

CIでは memory、開発PCでは persistent が基本です。

環境変数リファレンス

Docker Compose でアプリと統合

アプリコンテナとFlociを同じネットワーク上で起動する構成:

services:
  floci:
    image: hectorvent/floci:latest
    environment:
      - FLOCI_HOSTNAME=floci
    ports:
      - "4566:4566"

  app:
    build: .
    environment:
      - AWS_ENDPOINT_URL=http://floci:4566
      - AWS_DEFAULT_REGION=us-east-1
      - AWS_ACCESS_KEY_ID=test
      - AWS_SECRET_ACCESS_KEY=test
    depends_on:
      - floci

重要なのは FLOCI_HOSTNAME=floci を設定することです。これがないと、S3のリダイレクトレスポンスで localhost:4566 を返してしまい、アプリコンテナからアクセスできません。

初期データ投入（seedスクリプト）

チーム開発では、起動時に必要なバケットやテーブルを自動生成しておくと便利です。

#!/bin/bash
# scripts/floci-seed.sh
set -e
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

echo "Waiting for Floci..."
until curl -s http://localhost:4566/_floci/health > /dev/null; do sleep 1; done

aws s3 mb s3://app-uploads || true
aws s3 mb s3://app-logs || true
aws sqs create-queue --queue-name task-queue || true
echo "Seed completed."

docker compose up 後に実行するだけでチーム全員が同じ初期状態を手に入れられます。

よくあるエラーと対処

Connection refused エラー

ConnectionError: ... Connection refused ...

• Flociが起動していない → docker compose ps で確認
• ポート4566が他プロセスと競合 → lsof -i :4566
• Docker Desktop のWSL2側でポートが露出していない → ports 設定を確認

InvalidSignatureException

AWS_ACCESS_KEY_ID と AWS_SECRET_ACCESS_KEY が未設定。環境変数を必ず設定してください（値は test でOK）。

S3で PermanentRedirect

forcePathStyle=true（SDK）または s3_use_path_style=true（Terraform）を設定。Floci（およびLocalStack）はpath-style前提です。

アプリコンテナから接続できない

FLOCI_HOSTNAME=floci を設定し、アプリのAWS_ENDPOINT_URL に http://floci:4566 を指定。

DynamoDB ResourceNotFoundException

FLOCI_STORAGE_MODE=memory で再起動するとテーブルも消えます。永続化するなら persistent または wal を利用。

よくある質問（FAQ）

Q1. Flociは本番環境で使えますか？

ローカル開発・CI専用です。本番は実AWSを使ってください。

Q2. LocalStackとエンドポイントは同じ？

はい。http://localhost:4566 で互換があります。既存のboto3/SDKコードはほぼ無変更で動きます。

Q3. 対応していないサービスは？

CloudFront / XRay / AppSync / Redshift など一部は未対応です。対応サービス一覧 を確認してください。

Q4. データの永続化は？

FLOCI_STORAGE_MODE=persistent または wal を設定し、/app/data をボリュームマウントします。

Q5. 商用プロダクトのCIで使ってよい？

MITライセンスなので商用利用・改変・再配布すべて自由です。

WSL2 / Apple Silicon Mac 固有のハマりポイント

WSL2（Windows）

• Docker Desktop設定で WSL2 integration を有効化してから起動
• ポート4566は Windows側 からも localhost:4566 でアクセス可
• WSL2内のLinuxからは 127.0.0.1:4566 で問題なし
• ファイル共有のパフォーマンス低下を避けるため、データボリュームは WSL2側のファイルシステム（例: /home/<user>/floci-data）に置く

Apple Silicon（M1/M2/M3 Mac）

• Flociイメージは arm64ネイティブ対応のためRosetta不要
• ただしLambda関数のベースイメージはruntime種別によっては amd64 のみ → --platform linux/arm64 を関数作成時に指定
• Colima を使う場合は colima start --arch aarch64 --cpu 2 --memory 4 程度で十分

パフォーマンス実測（参考値）

Intel Mac / Apple Silicon M2 / Ubuntu 22.04 (x86_64) の3環境で計測した起動〜疎通確認までの所要時間:

CI環境（GitHub Actions ubuntu-latest）でも同等の数値が出ます。10倍以上の高速化が見込める構成です。

VSCode Dev Container で使う

.devcontainer/devcontainer.json:

{
  "name": "app-with-floci",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "customizations": {
    "vscode": {
      "extensions": ["ms-python.python", "amazonwebservices.aws-toolkit-vscode"]
    }
  }
}

docker-compose.yml にアプリとFlociを同時定義しておくと、Dev Container起動と同時にFlociが立ち上がり、チームメンバーは Reopen in Container 一発で開発開始できます。

本番AWSへの移行チェックリスト

Flociで開発・検証が完了したら、本番移行前に以下を必ず確認:

• AWS_ENDPOINT_URL 依存のコードが残っていないか（環境変数で切替可能か）
• forcePathStyle / s3_use_path_style の本番挙動（virtual-hosted推奨）
• IAMポリシーの条件キー（aws:SourceIp, aws:PrincipalTag）の実評価
• LambdaのVPC設定・セキュリティグループ
• SQS/SNSの**暗号化（KMS）**設定
• DynamoDBのPITR（ポイントインタイムリカバリ） 有効化
• CloudWatch Logs / X-Ray の有効化
• コスト予測（Cost Explorer / Budgets）
• 本番相当のテストデータでのスモークテスト

テスト戦略の考え方

Flociを中心に据えたテストピラミッドの例:

     [E2E (本番AWS)]  ← 数個、デプロイ前に最終確認
    [統合 (Floci)]     ← 数十、CIで毎回実行
  [ユニット (Moto/モック)] ← 数百、常時実行

• ユニットテスト は Moto / モックで高速に
• 統合テスト は Floci で AWS API 相当の挙動を確認
• E2E は本番相当のAWSサンドボックスアカウントで

この三層で開発速度と本番品質を両立できます。

まとめ

• Flociは無料・軽量・MITのAWSローカルエミュレータ
• インストールは docker run または docker-compose で即完了
• ストレージモード4種をCI/開発/本番検証で使い分け
• FLOCI_HOSTNAME 設定と path-style 設定が初回つまずきポイント
• 主要サービスはLocalStackと互換で移行コストほぼゼロ

次は各サービス別のハンズオン記事で、Floci + S3 / DynamoDB / Lambda / SQS などの実装例を深掘りしていきます。

関連記事

• LocalStack有料化の代替はFloci！徹底比較【2026年版】
• Floci × S3 ハンズオン
• Floci × DynamoDB ハンズオン
• Floci × Lambda ハンズオン
• Floci × SQS / SNS / EventBridge ハンズオン
• Floci × Cognito / IAM ハンズオン