Docs
Run Honua in Docker. Make a request. Pick an SDK.
The fastest path into Honua: start the server, hit an endpoint, install one SDK, then
jump into the deeper docs for your protocol, migration, or mobile use case.
Quickstart
Zero to an authenticated request.
Step 1
Run the server
docker network create honua
docker run -d --name honua-postgis --network honua \
-e POSTGRES_DB=honua \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
postgis/postgis:17-3.5-alpine
docker exec honua-postgis pg_isready -U postgres -d honua
docker run -d --name honua-server --network honua -p 8080:8080 \
-e ConnectionStrings__DefaultConnection="Host=honua-postgis;Database=honua;Username=postgres;Password=postgres" \
-e HONUA_ADMIN_PASSWORD="change-me-now" \
-e Security__ConnectionEncryption__MasterKey="test-master-key-that-is-at-least-32-characters-long-for-security" \
-e HostValidation__AllowedHosts__0="localhost" \
-e HostValidation__AllowedHosts__1="127.0.0.1" \
honuaio/honua-server:latest
curl http://localhost:8080/healthz/ready
This is the local Docker evaluation path. For production deployments, use managed secrets,
a real encryption key, and an explicit host/base URL configuration.
If you bind a different host port, update the URLs in the next steps to match.
Step 2
Set up auth for admin and automation calls
In this local Docker path, the initial admin API key is the same value you set in
HONUA_ADMIN_PASSWORD.
export HONUA_ADMIN_API_KEY="change-me-now"
curl -H "X-API-Key: ${HONUA_ADMIN_API_KEY}" \
http://localhost:8080/api/v1/admin/capabilities
Step 3
Make a first standards-compatible API call
curl "http://localhost:8080/rest/services?f=pjson"
A fresh server returns an empty service catalog. After you import or publish data,
this same endpoint becomes the GeoServices REST directory clients discover first.
Step 4
Install one SDK
The current MVP install path is the Python SDK directly from GitHub. It requires Python 3.11+.
python3.11 -m venv .venv
source .venv/bin/activate
pip install "git+https://github.com/honua-io/honua-sdk-python.git@trunk"
python - <<'PY'
from honua_sdk import HonuaClient
with HonuaClient("http://localhost:8080") as client:
catalog = client.list_services(response_format="pjson")
print(catalog.get("services", []))
PY
This quickstart was validated against a clean Docker bring-up: fresh network, fresh PostGIS container,
explicit database readiness check, a server boot with the required local secrets and host allowlist,
one authenticated admin call, one public protocol call, and one SDK entry path.
