Honua Server

Cloud-native geospatial server. One container exposes the same PostGIS-backed data through every major GIS protocol — GeoServices REST (FeatureServer, MapServer, ImageServer, Geometry, GPServer), OGC API (Features, Maps, Tiles, Coverages, Processes), classic OGC WMS/WFS/WMTS/WCS, STAC, OData v4, vector tiles (MVT/TileJSON), Terrain-RGB and elevation APIs, 3D Tiles, MCP for AI agents, and gRPC. Honua provides protocol-level compatibility for selected, operation-scoped Esri client workflows; support is bounded by the published GeoServices parity matrix and cross-client certification matrix. QGIS, MapLibre, Excel, and Power BI use the same layers — no ETL, no duplication, no GDAL toolchain to install.

Status

Honua Server is open core under the Elastic License 2.0. The GA-tier core (protocol surfaces, editing, imports, auth, operations) is production-ready and tracked under the v1.0 (GA) milestone. Feature requests and priorities go in issues. Versioned v* releases have not been tagged yet; until the first one is cut, run the nightly-built container image (see Quick start). The server runs in Community mode with no license file; paid Pro/Enterprise features activate only via signed entitlements and are marked (Pro) / (Enterprise) below (see Editions and licensing).

Quick start

Docker Compose (requires Docker with Compose v2 and Python 3):

git clone https://github.com/honua-io/honua-server.git && cd honua-server
python3 scripts/docker/quickstart.py
docker compose ps

Open http://localhost:8080/healthz/ready in a browser and wait for Ready.

The bootstrap generates per-install datastore passwords in a private .env file; retain it with your volumes. All published ports default to loopback. The default docker-compose.yml builds the server image from source on first run, so expect the first up to take a few minutes; for an instant start use the pre-built image below. PostGIS, Redis, and Honua Server start automatically; migrations run on first boot. HTTP/1 REST and gRPC-Web are at http://localhost:8080, native h2c gRPC at http://localhost:8081. Use the package quickstart for an isolated install, import, publish, and verified SDK query; continue this source installation with the source quickstart to see a browser map, or add the web Console with docker compose --profile console up -d (set HONUA_CONSOLE_IMAGE to a honua-console image you have built or mirrored — no public Console image is published yet; Operate serves at http://localhost:5174/operate).

Pre-built image (bring your own PostGIS):

docker run -p 8080:8080 -p 8081:8081 \
  -e ConnectionStrings__DefaultConnection="Host=host.docker.internal;Database=honua;Username=postgres;Password=postgres" \
  -e HONUA_ADMIN_PASSWORD="change-me" \
  -e Security__ConnectionEncryption__MasterKey="change-me-random-string-32-plus-characters" \
  honuaio/honua-server:nightly

:nightly (also tagged :trunk) is rebuilt from trunk every night; pin a specific build with :nightly-YYYYMMDD. The :latest tag is only promoted on tagged v* releases and will resume meaning "latest release" once the first release is cut.

Kubernetes — deploy with the Helm chart in honua-helm; see the Kubernetes guide.

Local development — .NET Aspire with a dashboard for traces, logs, and metrics:

dotnet run --project src/Honua.AppHost

To run geoprocessing jobs locally (in-process, no cloud), use the local GP dev quickstart. For self-hosted pilots, run the pilot onboarding runbook before handing a deployment to another team.

Protocols

Every published layer is reachable through every protocol its service enables. The canonical matrix with examples lives in Protocols.

Path shapes differ on purpose: each protocol carries exactly the scope its own specification makes the addressable unit. WMS, WMTS and WCS render a composition, so a service is in the path; WFS returns features that TYPENAMES already identifies, so it is served unscoped at /wfs with no service-scoped form and no GeoServices alias. The rule, and why adding one for symmetry would be a regression, is ADR-0079.

Surfaces marked (Pro) / (Enterprise) require a signed license; everything unmarked is Community. The machine-readable capability vocabulary behind this table is docs/gis/data/capability-keys.v1.json (generated from CapabilityKeyCatalog.cs) — keep the table in sync with it.

Plus operational surfaces: health probes (/healthz/live, /healthz/ready), OpenAPI documents per OGC API, an interactive API explorer at /docs (dev mode or HONUA_SERVE_API_DOCS=true), the admin API (/api/v1/admin), and a capability manifest (/api/v1/capabilities/manifest) for clients to discover what a deployment supports.

Compliance

• OGC CITE: 1138 / 1138 passing across 14 conformance suites, including WFS 2.0 basic at 167/167. See the authoritative snapshot and run receipt and OGC conformance evidence.
• Client compatibility: the supported client x protocol matrix — including known limitations — is the compatibility contract; Esri-side parity is tracked in GeoServices parity.
• gRPC stability: gRPC remains supported for 2026.1. Geospatial.Grpc is on nuget.org (dotnet add package Geospatial.Grpc). See the gRPC reference for versioning and stability guarantees.
• Control plane stability: admin/control-plane API versioning is governed by versioning and support.

Key capabilities

• Query and edit — FeatureServer query/applyEdits/attachments/related records, OGC API Features CRUD with CQL2, WFS 2.0 transactions, OData CRUD with spatial functions (geo.distance, geo.intersects, $batch). FeatureServer applyEdits is (Pro); edits through the open protocols (OGC API Features, WFS-T, OData, gRPC) stay Community. Output as JSON, GeoJSON, PBF, FlatGeobuf, GeoParquet, and GeoArrow.

• Esri migration and coexistence — Honua provides protocol-level compatibility for selected, operation-scoped ArcGIS Pro and Esri SDK workflows, bounded by the published GeoServices parity matrix and cross-client certification matrix. Import public ArcGIS REST and GeoServer services into PostGIS (service imports are (Enterprise)); scan ArcGIS Server and GeoServer for deterministic migration inventories. See Migrate from ArcGIS Server and from GeoServer.

• No GDAL required on the server — import GeoJSON, Shapefile (zip), GeoPackage, GPX, KML, WKT, FlatGeobuf, File Geodatabase (.gdb.zip), and GeoParquet directly, with CRS auto-detection and PostGIS reprojection; the serving container ships no GDAL, while optional geoprocessing worker images bundle it separately.

• Rendering and rasters — MapServer export/identify/legend, OGC API Maps, WCS, and server-generated Terrain-RGB elevation tiles (Community); ImageServer and OGC API Coverages (Preview). Cloud-optimized GeoTIFFs registered in place from S3/Azure are served under (Pro).

• Geoprocessing and workflows — one canonical async job runtime behind GPServer, OGC API Processes, gRPC, and MCP; declarative multi-step DAG workflows with retries and cron scheduling (Redis required for durable jobs).

• AI-operable — the /mcp surface implements the open geospatial-mcp standard so agents can validate plans, dry-run, execute, and read results with the same authorization as any other client. MCP discovery/query and spec artifacts are Community; agent operations and spec-apply execution are (Pro); approval workflows are (Enterprise). See Connect AI agents.

• Cloud-native operations — container-first and stateless; multi-layer caching with in-memory fallback (output cache and Redis caching are (Pro)); OpenTelemetry traces and metrics; API-key auth, OIDC SSO (Pro) — multi-provider OIDC, SAML 2.0, and SCIM 2.0 are (Enterprise) — and experimental mTLS client-certificate auth (Enterprise) (off by default, not on the GA path); a server-computed operate loop for humans, Console, and agents (Operating Honua).

• Spatial analytics — viewshed, line-of-sight, and sun/shadow analysis; H3 aggregation; density, clustering, spatial join, buffer-aggregate, and slice, all (Pro); analysis content and reporting stay Community. These are synchronous — the elevation analytics are POST /elevation/{datasetId}/… calls and the vector ones are FeatureServer query extensions, not async jobs. The long-running GDAL-worker operations are catalogued separately in geoprocessing operations.

• Geocoding — forward and reverse geocoding against a local PostGIS-backed geocoder (Community), batch geocoding (Enterprise), and provider failover (Pro), served to Esri clients through GeocodeServer (provider parity).

• Routing and network analysis — routes, service areas, closest facility, origin-destination cost matrices, and location-allocation through NAServer (Pro).

• Time — temporal extent discovery and time filtering (Community), temporal histograms, time-series tiles, and an SDK-side animation API (Pro), so time-aware layers answer "when" as well as "where". See Work with time.

• Real-time, geofencing and alerting — feature subscriptions for change streams (Pro); an alert-rule evaluation engine (Pro, Preview) whose trigger types are enter/exit geofences (Pro, Preview) and dwell and threshold triggers (Enterprise, Preview); delivery to a webhook (Pro, Preview) or to Slack, Teams, email, AWS SNS, Azure EventGrid, or a digest (Enterprise, Preview). See React to changes.

• Field operations — form packages for data collection (Community) and offline sync for disconnected field work (Pro, Preview); the mobile SDK and collection app live in honua-mobile and honua-collect.

• Collaboration — multi-user saved-map sessions with an operation log (Community), and feature locks for concurrent editing (Community) — note that the shipped lock authorizer denies every claim until you register your own IFeatureLockAuthorizer, so the manifest reports available: false out of the box. Leases are also single-node.

• Data enrichment — enrich your features with attributes from a registered reference dataset by spatial join (data enrichment, Community).

• Static maps — server-rendered map images (Community) for reports, tiles-free embeds and notifications; high-DPI output, large dimensions and rich overlays are (Pro).

• Raster configuration — temporal mosaics (Pro) on top of the COG serving above. Cloud-storage provider selection (S3 / Azure Blob) is startup configuration (HONUA_STORAGE_PROVIDER), not a licensed gate — paid enforcement for cloud-served rasters happens at request time through COG serving.

• Print and export — server-rendered PDF output (Pro) from configurable layout templates (Pro).

• 3D (not on the 2026.1 path) — owner decision D0.2 moved 3D wholesale to 2026.2. The scene catalog is deferred, OGC 3D Tiles serving to CesiumJS is experimental, I3S scene serving is (Enterprise) and experimental, and BIM and point-cloud ingest are (Enterprise) and experimental. Treat all of it as preview. See Publish 3D scenes.

The admin API (/api/v1/admin) manages connections, services, layers, styles, and import jobs; the web admin UI lives in honua-console. The admin API is also the substrate for self-managed control-plane workflows: change management and instance lifecycle automation build on it rather than on a third-party GitOps controller.

Data providers

PostGIS is the primary read/write backend. Additional providers serve data in place, read/query-only, through the same protocol surfaces:

Per-provider capabilities, selection variables, and limitations are in the data sources reference.

Configuration

All settings are environment variables. Copy .env.example for a full annotated reference, or see the environment variable reference.

Required (PostgreSQL provider — default):

ConnectionStrings__DefaultConnection="Host=postgres;Database=honua;Username=postgres;Password=postgres"
HONUA_ADMIN_PASSWORD="change-me"
# Encrypts stored data-connection credentials (>=32 chars). Required outside
# Development — startup fails without it; in dev, registering a data
# connection fails until it is set.
Security__ConnectionEncryption__MasterKey="change-me-random-string-32-plus-characters"

Common options:

ConnectionStrings__Redis="localhost:6379"   # optional; shared caches, and required for durable jobs/workflows
HONUA_OBSERVABILITY=true                    # metrics endpoints (health probes are always on)
HONUA_OPENTELEMETRY=true                    # distributed tracing
Cors__AllowedOrigins__0="https://app.example.com"

PostGIS is mandatory; Redis is optional. A single-node install with no ConnectionStrings__Redis starts, reports Ready, and serves the full read path with an in-memory cache — it just refuses durable jobs, workflows, and operation proposals with a typed dependency-unavailable error. See Redis is optional; PostGIS is not.

Production tuning — bounded database admission is the default production posture: keep Limits__Connections__MaxConcurrentQueries aligned with the pool size and size from the shared database budget across replicas (small 4-vCPU nodes profile best in the 4–6 active-query range; larger pools can overfeed PostGIS and worsen tail latency). Adaptive admission (Limits__Connections__AdaptiveConcurrencyEnabled) is an explicit tuning profile, not the default — monitor /monitoring/metrics/connection-pool and keep fixed-cap results as the baseline. Full guidance: Scale and tune performance and admission and pooling variables.

Invalid configuration fails startup with a detailed error message.

Documentation

Full hosted documentation: honua.gitbook.io/honuaio. The in-repo table of contents is docs/README.md.

Reading this as an agent? Start at docs/llms.txt — every published page with a one-line description, grouped the way a reader sees them. The docs are an Open Knowledge Format bundle: one subject per file, the file path as the concept's identity, and a declared type on each page (concept, guide, reference, runbook, index). Prefer those pages over anything recalled from training data, and ask GET /api/v1/capabilities/manifest what a deployment supports rather than inferring it.

Frequent destinations:

Related repositories

Honua is a family of repos around this server — the full map is in Ecosystem:

• honua-console — web console (Studio, Catalog, Operate, Share) over the admin API; the admin/UI home
• honua-helm — Helm chart, the Kubernetes deploy path
• honua-sdk-js · honua-sdk-python · honua-sdk-dotnet — client SDKs generated from the same admin contract
• honua-mobile — Experimental reusable .NET MAUI SDK and map/control foundation for offline field workflows (Apache-2.0)
• honua-collect — Experimental full end-user field-collection app built on honua-mobile (ELv2)
• geospatial-grpc — open gRPC protocol standard the server's geospatial.v1 surface implements
• geospatial-mcp — open geospatial MCP standard behind /mcp

Feedback

GitHub Issues are the primary feedback loop. Please use the forms so reports include enough detail for triage:

• Report a bug (include screenshots and repro steps)
• Request a feature — or upvote existing roadmap items
• New ideas start in Discussions → Ideas; popular ideas graduate to roadmap issues

Security

See SECURITY.md for how to report a vulnerability privately, response targets, and the coordinated-disclosure policy. Do not open public issues for suspected vulnerabilities.

License

Elastic License 2.0 (ELv2) — free to use, deploy, and modify, within the ELv2 limitations: you may not provide Honua to third parties as a hosted or managed service, may not circumvent the license-key functionality, and may not remove or obscure the licensor's notices.