Belajar Floci - Migration Playbook: LocalStack → Floci

#Pendahuluan

Sunset LocalStack Community pada 23 Maret 2026 memaksa ribuan tim bermigrasi — bukan karena ingin, tapi karena Community berhenti menerima security update dan menuntut auth token. Jika tim kalian salah satunya, episode ini adalah playbook sistematisnya.

Prinsip utamanya: migrasi emulator bukan operasi copy-paste buta, melainkan proses terukur dengan gerbang verifikasi eksplisit.

#Langkah

#Peta Migrasi Empat Langkah

Langkah 1 — swap image. localstack/localstack → floci/floci:<pinned>. Port tetap 4566, jadi aplikasi tidak sadar apa pun.

Langkah 2 — translate env. Tabel translasi episode 16 adalah referensi resminya: SERVICES dihapus, DEFAULT_REGION → FLOCI_DEFAULT_REGION, DATA_DIR → volume /app/data, dst.

Langkah 3 — verifikasi endpoint compat. Tiga klien yang wajib dites:

# CLI v2
aws --endpoint-url=http://localhost:4566 s3 ls
 
# boto3 (Python)
python -c "import boto3; print(boto3.client('s3', \
  endpoint_url='http://localhost:4566').list_buckets())"
 
# aws-sdk-js v3 (Node)
node -e "const {S3Client,ListBucketsCommand}=require('@aws-sdk/client-s3'); \
  new S3Client({endpoint:'http://localhost:4566',region:'us-east-1', \
  forcePathStyle:true}).send(new ListBucketsCommand({})).then(r=>console.log(r.Buckets))"
 
# env var resmi - cara paling non-invasif untuk semua tooling sekaligus
export AWS_ENDPOINT_URL=http://localhost:4566 && aws s3 mb s3://compat-check

Langkah 4 — audit fitur pro. Jika tim sempat memakai LocalStack Pro/Team (feature gates tertentu seperti RDS asli, IAM enforcement, atau Cloud pods), petakan fitur mana yang benar-benar dipakai dan cari padanannya di floci (real containers via docker.sock) atau putuskan pola alternatif.

#Risiko

#Perbedaan Perilaku Edge-Case & Gerbang Suite Penuh

Sumber risiko realistis:

• Conformance gaps pada operasi kompleks DynamoDB/Lambda (episode 5) — perilaku beda di edge case.
• Fitur yang tak ada padanannya — mis. IAM enforcement ketat; floci sengaja longgar.
• Perbedaan timing — cold start lambda lokal jauh lebih murah daripada produksi.

Karena itu satu-satunya gerbang sah untuk menyatakan migrasi selesai adalah re-run test suite penuh — bukan smoke test seadanya:

[ ] Unit tests        -> hijau
[ ] Integration tests -> hijau (suite sama persis, hanya endpoint beda)
[ ] E2E critical path -> hijau
[ ] Delta log         -> setiap perbedaan hasil didokumentasikan + keputusan

#Praktik

Target outline: migrasikan satu proyek LocalStack nyata + dokumentasikan delta.

#!/usr/bin/env bash
set -euo pipefail
 
echo "== 1. backup compose =="
cp docker-compose.yml docker-compose.yml.localstack.bak
 
echo "== 2. swap image + env (sed) =="
sed -i 's|image: localstack/localstack.*|image: floci/floci:1.5.15|' docker-compose.yml
sed -i 's|DEFAULT_REGION: \(.*\)|FLOCI_DEFAULT_REGION: \1|' docker-compose.yml
grep -v -e 'SERVICES' -e 'DATA_DIR' -e 'LOCALSTACK_HOST' docker-compose.yml > c.tmp && mv c.tmp docker-compose.yml
 
echo "== 3. up + health gate =="
docker compose up -d
for i in $(seq 1 20); do curl -sf http://localhost:4566/_floci/health >/dev/null && break || sleep 0.5; done
curl -sf http://localhost:4566/_floci/health | grep -q '"ok"' && echo "floci siap"
 
echo "== 4. compat probe CLI =="
aws --endpoint-url=http://localhost:4566 s3 mb s3://migration-gate >/dev/null
aws --endpoint-url=http://localhost:4566 s3 ls | grep migration-gate && echo "compat OK"

# Migration Delta: proyek X (tanggal)
## Yang berubah
- image swap + 2 env vars (commit abc123)
## Hasil suite
- unit 42/42, integration 18/18, e2e 6/6
## Delta ditemukan
1. Lambda timeout lokal lebih cepat -> ubah assertion sleep 3s menjadi event-driven
   KEPUTUSAN: perbaikan test, bukan bug floci
2. PutBucketLifecycle -> 400 di floci versi ini
   KEPUTUSAN: contract test ditandatangani skip-until, issue dilacak
## Kesimpulan
Migrasi lolos gerbang; 1 item dilacak.

Dokumen delta inilah yang membuat migrasi bisa diaudit — reviewer melihat bukti, bukan klaim.

#Penutup

Rangkuman episode ini:

• Empat langkah: swap image → translate env → verifikasi compat tiga klien → audit feature gates.
• Risiko nyata ada di edge-case conformance & fitur tanpa padanan; jawabannya disiplin, bukan keberuntungan.
• Gerbang sah migrasi: re-run suite PENUH + dokumen delta yang diaudit.

Episode 23 mengoptimalkan pengalaman developer harian: serverless local development loop — hot-reload handler, payload sample, debug breakpoint, dan log streaming. Sampai jumpa!