Belajar LocalStack - Setup & First Run

#Pendahuluan

Di episode 2 kita membongkar arsitektur LocalStack: satu gateway di http://localhost:4566, provider-based, dan perbedaan emulasi stateful vs mock. Sekarang saatnya teori menjadi praktik — kita akan menjalankan emulator untuk pertama kali dan memverifikasi bahwa semuanya benar-benar bekerja.

Episode ini adalah momen paling menentukan di seri ini: kalau kalian bisa membuat LocalStack running dan berkomunikasi dengannya lewat awslocal, maka episode-episode selanjutnya (S3, DynamoDB, Lambda, dan lainnya) akan terasa mudah. Sebaliknya, kalau setup gagal di sini, semua materi berikutnya tidak akan bisa dicoba.

#Persiapan Sebelum Start

Pastikan tiga hal sebelum menyalakan LocalStack:

Docker daemon berjalan — cek dengan docker info atau docker ps.
CLI terpasang — localstack --version harus menampilkan versi, misalnya 2026.7.x.
Port 4566 bebas — pastikan tidak ada proses lain yang memakainya.

Warning

Konflik port 4566 adalah salah satu penyebab kegagalan paling umum. Jika ada aplikasi lain memakai port tersebut, LocalStack gagal bind gateway. Identifikasi dengan lsof -i :4566 atau netstat -tulpn sebelum start.

#Menjalankan dengan localstack start

Cara tercepat adalah memakai CLI. Pastikan Docker berjalan, lalu jalankan:

Memulai LocalStack dalam mode Docker

localstack start

Perintah ini akan menarik image localstack/localstack:latest (bila belum ada), menjalankan container bernama localstack-main, lalu menunggu hingga siap. Bila sudah berjalan, kalian akan melihat pesan Ready. di akhir log. Cek dari sisi Docker:

Melihat container LocalStack

docker ps --filter name=localstack-main

Note

localstack start menjalankan emulator di background sebagai container Docker. Output log bisa kalian ikuti kapan saja dengan localstack logs.

#Menjalankan dengan Docker Compose

Untuk tim dan CI, cara yang lebih reproducible adalah mendefinisikan environment lewat docker-compose.yml. Dengan ini seluruh konfigurasi menjadi artefak yang di-versioning di Git.

docker-compose.yml

services:
  localstack:
    image: localstack/localstack:latest
    container_name: localstack-main
    ports:
      - "4566:4566"
      - "4510-4559:4510-4559"
    environment:
      - PERSISTENCE=1
      - DEBUG=1
    volumes:
      - "./.localstack:/var/lib/localstack"

Jalankan dengan:

Menjalankan dengan Docker Compose

docker compose up -d
docker compose ps

Tip

Mount volume ./.localstack:/var/lib/localstack menyimpan data emulator ke disk lokal. Berguna saat PERSISTENCE=1 agar state tidak hilang saat container direstart — akan kita bahas detail di episode 4 dan 12.

#Menunggu Hingga Running

Emulator butuh beberapa detik hingga semua service aktif. Jangan langsung memerintah sebelum siap — LocalStack menyediakan health endpoint di /_localstack/health yang merespons status per service. Script berikut menunggu hingga emulator siap melayani request:

Menunggu LocalStack siap

for i in $(seq 1 30); do
  curl -sf http://localhost:4566/_localstack/health >/dev/null && break
  echo "Menunggu LocalStack siap..."
  sleep 2
done

#Verifikasi Dasar

Setelah running, verifikasi dengan tiga perintah kunci:

localstack status
localstack services

Penjelasan tiap perintah:

Perintah	Fungsi
`localstack status`	Menampilkan status container, versi image, dan apakah emulator `running`
`localstack services`	Mendaftar semua service AWS yang tersedia dan aktif
`awslocal sts get-caller-identity`	Memverifikasi autentikasi; mengembalikan identitas dengan kredensial palsu `test`/`test`

Jika semuanya berjalan, awslocal sts get-caller-identity akan mengembalikan JSON berisi Account dan Arn dengan kredensial default test. Itu artinya emulator menerima autentikasi dan siap dipakai.

Warning

Bila localstack status tidak menunjukkan running, periksa dua hal paling umum: apakah port 4566 sedang dipakai proses lain, dan apakah Docker daemon berjalan. Gunakan localstack logs untuk melihat error sebenarnya.

#Penutup

Jalankan LocalStack dengan localstack start (mode Docker) atau docker compose up -d dengan service localstack/localstack.
Tunggu hingga status running — bisa dipantau lewat health endpoint /_localstack/health.
Verifikasi dengan localstack status, localstack services, dan awslocal sts get-caller-identity.

Emulator kalian sekarang hidup. Di episode 4 berikutnya kita belajar mengelola siklus hidupnya secara profesional: localstack start, stop, restart, status, logs, config, plus variabel lingkungan penting seperti PERSISTENCE, DEBUG, dan SERVICES. Pastikan emulator tetap menyala untuk dipakai di materi selanjutnya!