Honua
// docs & quickstart

Run the server locally. Publish a dataset. See the map.

With the prerequisites ready, go from a clone to a live browser map in about ten minutes. No license key, no signup, no phone-home. Once your own data renders locally, the deeper guides have something concrete to build on.

JavaScript learning path provenance: this site tracks trunk development @ 2ff3aff4aa37. The latest published package is @honua/sdk-js 0.1.0-beta.0; development documentation is not an immutable release.

Read the full documentation ↗ — concepts, how-to guides, operator runbooks, SDK references, and the compatibility matrices all live there. This page is the ten-minute version.

Before you start

Quickstart · go from zero to a map in your browser

1. Clone, configure, and start the stack.

git clone https://github.com/honua-io/honua-server.git && cd honua-server

# Compose merges this override automatically: it sets the admin password,
# the connection-encryption key, and a CORS origin for your map page.
cat > docker-compose.override.yml <<'EOF'
services:
  honua:
    environment:
      HONUA_ADMIN_PASSWORD: quickstart-admin-password
      Security__ConnectionEncryption__MasterKey: quickstart-master-key-0123456789abcdef
      Cors__AllowedOrigins__0: http://localhost:3000
EOF

docker compose up -d
curl http://localhost:8080/healthz/ready

This is the local path. Use managed secrets and real keys for production deployments.

2. Import a dataset and publish it.

# Admin endpoints authenticate with the X-API-Key header.
KEY="X-API-Key: quickstart-admin-password"

cat > points.geojson <<'EOF'
{"type":"FeatureCollection","features":[
 {"type":"Feature","properties":{"name":"Ferry Building"},"geometry":{"type":"Point","coordinates":[-122.3937,37.7955]}},
 {"type":"Feature","properties":{"name":"Coit Tower"},"geometry":{"type":"Point","coordinates":[-122.4058,37.8024]}},
 {"type":"Feature","properties":{"name":"Painted Ladies"},"geometry":{"type":"Point","coordinates":[-122.4330,37.7762]}}]}
EOF

# Import the file, register the compose database as a connection,
# publish the table as a layer, and allow anonymous reads for the browser.
curl -s -H "$KEY" -F "file=@points.geojson" -F "TableName=quickstart_points" \
  http://localhost:8080/api/v1/admin/import/upload

curl -s -H "$KEY" -H "Content-Type: application/json" \
  -d '{"name":"local","host":"postgres","port":5432,"databaseName":"honua_dev","username":"honua_user","password":"honua_password","sslRequired":false,"sslMode":"Prefer"}' \
  http://localhost:8080/api/v1/admin/connections

curl -s -H "$KEY" -H "Content-Type: application/json" \
  -d '{"schema":"honua_data","table":"quickstart_points","layerName":"quickstart-points","srid":4326}' \
  http://localhost:8080/api/v1/admin/connections/local/layers

curl -s -X PUT -H "$KEY" -H "Content-Type: application/json" \
  -d '{"allowAnonymous":true}' \
  http://localhost:8080/api/v1/admin/services/default/access-policy

3. Open the map.

# Save a minimal MapLibre page and serve it.
# If the publish response reported a layerId other than 1, change it below.
cat > map.html <<'EOF'
<!doctype html><html><head><meta charset="utf-8">
<script src="https://unpkg.com/maplibre-gl@4/dist/maplibre-gl.js"></script>
<link href="https://unpkg.com/maplibre-gl@4/dist/maplibre-gl.css" rel="stylesheet">
<style>html,body,#map{margin:0;height:100%}</style></head>
<body><div id="map"></div><script>
const layerId = 1;
new maplibregl.Map({container:'map',center:[-122.41,37.79],zoom:12,style:{version:8,
 sources:{
  osm:{type:'raster',tiles:['https://tile.openstreetmap.org/{z}/{x}/{y}.png'],tileSize:256,attribution:'© OpenStreetMap'},
  honua:{type:'vector',tiles:['http://localhost:8080/tiles/'+layerId+'/{z}/{x}/{y}.mvt']}},
 layers:[
  {id:'osm',type:'raster',source:'osm'},
  {id:'points',type:'circle',source:'honua','source-layer':'layer',
   paint:{'circle-radius':8,'circle-color':'#2D69A5','circle-stroke-color':'#fff','circle-stroke-width':2}}]}});
</script></body></html>
EOF

python3 -m http.server 3000
# open http://localhost:3000/map.html — three blue circles over San Francisco.

The same layer is now available through the documented OGC API Features, FeatureServer, WMS/WFS, and OData surfaces: publish once, then choose the interface each supported workflow needs. The canonical step-by-step version with verification and troubleshooting lives in the docs quickstart.

4. Keep going.

From here:

SDKs · current availability

Prefer typed clients over raw HTTP? The SDK family targets FeatureServer, OGC API Features, STAC, OData, vector tiles, and the admin control plane, but coverage and package availability differ by language. The current install boundary is explicit:

See SDK availability & compatibility for the registry-backed status and the correct server capability endpoint. The SDK overview ↗ describes the intended family architecture.

Building with a coding agent? Give it a stable, commit-pinned SDK reference: use the curated machine-doc index or the single-fetch documentation corpus.

Building support tooling? Use the public, fail-closed sanitized diagnostic-bundle JSON Schema. Its provenance record pins the source commit, byte count, and SHA-256 so SDK emitters can verify the contract without access to the source repository.

Source

Browse github.com/honua-io for the public server, SDK, mobile, Helm, benchmark, and MCP repositories. Availability differs by repository; use the status links above before choosing an install path.