Self-Hosting Guide

Deploy wilayah-id on your own infrastructure for unlimited access, zero rate limits, and complete data privacy.

Choose Your Deployment Method

Recommended

Docker Quickstart

One-command deployment with pre-built Docker image. Fastest way to get started.

⏱️ 5 min● Easy💾 ~500MB

SQL Dump Restore

Download compressed database dump and restore to existing PostgreSQL.

⏱️ 10 min● Medium💾 ~100MB

Build from Source

Clone repo, run ETL pipeline, and build locally. Full control over data.

⏱️ 30+ min● Hard💾 ~2GB

Deployment Instructions

Recommended for most users

App server + PostgreSQL via Docker Compose. Load data via SQL dump after setup.

Prerequisites

Docker 20+ and Docker Compose 2+ must be installed.

Check versions

docker --version
docker compose version

Download Compose File

No need to clone the entire repo. Just download the compose file.

Terminal

mkdir wilayah-id && cd wilayah-id
curl -O https://raw.githubusercontent.com/dhanyyudi/wilayah-id/main/docker-compose.yml

Start Services

This will download the pre-built image with data already loaded.

Terminal

docker compose up -d

# Wait for services to be ready (~30 seconds)
docker compose logs -f app

Verify Installation

Test API

curl http://localhost:3000/api/v1/regions/provinces

# Expected: {"status":"success","data":[...],"meta":{"total":38}}

Configuration

Environment Variables

Create .env.local file with these settings

.env.local

# Required - PostgreSQL connection
DATABASE_URL=postgresql://username:password@localhost:5432/wilayah_id

# Optional - Custom tile server URL (default: /tiles)
NEXT_PUBLIC_TILES_BASE_URL=/tiles

# Optional - API rate limiting (self-hosted = unlimited)
# RATE_LIMIT_REQUESTS=1000
# RATE_LIMIT_WINDOW=60000

About the Data

91,248

Total Regions

77,721

Postal Codes

~500MB

Database Size

Data sourced from official Indonesian government records:

Batas Administrasi (Kemendagri) — Official boundary shapes from Kemendagri (2024)
Kode Wilayah (Kemendagri) — Region codes from Ministry of Home Affairs
Kode Pos (Pos Indonesia) — Postal codes from Pos Indonesia

Troubleshooting

Q: Database connection failed?

A: Ensure PostgreSQL is running and accessible. Check DATABASE_URL format: postgresql://user:pass@host:port/dbname

Q: PostGIS extension not found?

A: Install PostGIS: sudo apt-get install postgis (Ubuntu/Debian) or brew install postgis (macOS)

Q: Vector tiles not loading?

A: Check that tiles were generated in public/tiles/ directory. Run python etl/generate_tiles.py if missing.

Q: How to update data?

A: For Docker: pull latest image. For SQL: download new dump and restore. For source: re-run ETL pipeline.