Step-by-step installation of single-node Elasticsearch for local development.
New to Docker or Elasticsearch? Read the Beginner's Tutorial first — it explains every term, then sends you back here for the formal steps.
Confirm Docker and Compose are available:
docker --version # 24+ (29.x fine)
docker compose version # v2.xIf docker commands need sudo, either prefix them or add your user to the
docker group (then log out/in):
sudo usermod -aG docker "$USER"Linux only. On macOS / Windows, Docker Desktop sets this inside its own VM — skip this section entirely and go to step 3. (The helper script in Option A detects a non-Linux host and exits cleanly, so it's safe to run too.)
Elasticsearch refuses to start unless vm.max_map_count >= 262144.
./scripts/setup-host.shIt is idempotent: sets the value for the current boot and persists it in
/etc/sysctl.conf for future reboots, skipping anything already in place.
# Apply now
sudo sysctl -w vm.max_map_count=262144
# Persist across reboots
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.confVerify:
sysctl vm.max_map_count # → vm.max_map_count = 262144docker compose up -dFirst run pulls the ~600 MB image and boots the node (≈ 30–60 s).
Follow the boot logs until you see started:
docker compose logs -f elasticsearchdocker compose ps # STATUS should show "healthy"
curl http://localhost:9200/_cluster/health?prettystatus should be green or yellow. See
VERIFICATION.md for the full acceptance checklist.
In your NestJS project's .env:
ELASTICSEARCH_NODE=http://localhost:9200See ../examples/nestjs/ for module wiring.
| Action | Command | Make target |
|---|---|---|
| Start | docker compose up -d |
make up |
| Stop (keep data) | docker compose down |
make down |
| Restart | docker compose restart |
make restart |
| Logs | docker compose logs -f elasticsearch |
make logs |
| Health | curl localhost:9200/_cluster/health?pretty |
make health |
| Wipe data | docker compose down -v |
make clean |