Honua Server

Honua Server is a high-performance geospatial server built on .NET 10, implementing OGC APIs, Esri GeoServices REST, and STAC standards. It provides enterprise-grade feature services with multi-cloud deployment support, pluggable data providers, and comprehensive observability.

Developers

See DEVELOPERS.md for the repo map, plugin layout, and agent/CLI pointers.

Key Features

• OGC API Compliance: Features, Tiles, Records, Processes, and SensorThings
• OData v4 Protocol: Standard OData queries with spatial functions (geo.distance, geo.intersects)
• Legacy OGC Support: WMS, WFS, WCS, WMTS, CSW
• Esri Compatibility: Full GeoServices REST API (FeatureServer, MapServer, GeometryServer)
• STAC Support: SpatioTemporal Asset Catalog for raster/imagery discovery
• Multi-Database: PostgreSQL/PostGIS, MySQL, SQL Server, SQLite, DuckDB
• Enterprise Data Warehouses: Snowflake, BigQuery, Redshift, Cosmos DB, MongoDB, Oracle
• Cloud-Native & Serverless: Docker, Kubernetes, Helm charts, Terraform modules for AWS/Azure/GCP with serverless-first design
• Cross-Cloud Services: Unified abstractions for storage (S3/Blob/GCS), queues (SQS/Service Bus/Pub/Sub), secrets (Secrets Manager/Key Vault), Redis, identity, and observability
• Modular & Opt-In: Enable only the APIs and plugins you need; endpoints and providers are individually configurable
• Real-Time: GeoEvent processing, geofencing, WebSocket/SignalR support
• AI Capabilities: Natural language to CQL2 query generation, AI-powered map creation, and DevSecOps agent for platform installation, deployment, configuration, optimization, monitoring, and upgrades
• Field Mobility: Honua Field cross-platform mobile app (.NET MAUI for iOS and Android) for inspection, data capture, and offline sync

Enterprise Features

• GeoETL: Visual ETL workflows for data transformation with AI-assisted pipeline generation and scheduling
• Geoprocessing: Server-side spatial analysis, buffer, overlay, union, intersection, and custom processing tasks
• Data Versioning: Branch, merge, and track changes to spatial datasets with full history
• Audit Logging: Comprehensive audit trails for data access and modifications (compliance-ready)
• SAML 2.0 SSO: Enterprise single sign-on integration

Architecture

Honua Server follows consistent architectural patterns across all 16 API implementations:

• Minimal API Pattern: Most endpoints use ASP.NET Core minimal APIs with route groups and static handler classes
• Unified Observability: All APIs include logging, tracing, and metrics via IObservabilityScope
• Standardized Authorization: Configuration-based auth enforcement with RequireViewer and RequireDataPublisher policies
• Unified Error Handling: IApiErrorFactory for JSON APIs, IOgcExceptionFactory for OGC XML services
• Query Validation: IQueryValidator<T> and IQueryMetrics<T> interfaces for consistent validation and monitoring

See API Implementation Patterns for details on adding new APIs.

Supported APIs

API	Endpoints	Description
OGC API Features	/ogc/collections/*	Modern RESTful geospatial API
OGC API Tiles	/ogc/tiles/*	Vector and raster tile serving
OGC API Coverages	/ogc/coverages/*	Raster/coverage data access
OGC API EDR	/ogc/edr/*	Environmental Data Retrieval (spatio-temporal queries)
OGC API Records	/ogc/records/*	Metadata catalog
OGC API Styles	/ogc/styles/*	Style management and versioning
OGC API SensorThings	/sensorthings/*	IoT sensor data (Enterprise)
OData v4	/odata/*	Standard OData protocol with spatial functions
WMS 1.3.0	/wms	Web Map Service
WFS 2.0	/wfs	Web Feature Service
WMTS 1.0	/wmts	Web Map Tile Service
WCS 2.0	/wcs	Web Coverage Service
CSW 2.0	/csw	Catalog Service for the Web
STAC 1.0	/stac/*	SpatioTemporal Asset Catalog
GeoServices REST	/rest/services/*	Esri ArcGIS compatibility
Carto SQL API	/carto/api/v3/*	SQL-based GIS queries
OpenRosa/ODK	/openrosa/*	Mobile data collection forms
Admin API	/api/admin/*	Server administration

Quick Start

Docker (Minimal)

docker run -p 8080:8080 \
  -e ConnectionStrings__DefaultConnection="Host=postgres;Database=honua;Username=postgres;Password=postgres" \
  ghcr.io/honuaio/honua-server:latest

Docker Compose (Full Stack)

docker compose up -d

This starts PostgreSQL/PostGIS, Redis, and the Honua Server with observability tools (Prometheus, Grafana, Jaeger).

From Source

# Build
dotnet build Honua.sln

# Run
ASPNETCORE_ENVIRONMENT=Development \
dotnet run --project src/apps/host/Honua.Server.Host.csproj

Verify Installation

• Landing page: http://localhost:8080/
• OGC API Features: http://localhost:8080/ogc/features
• Health check: http://localhost:8080/healthz/live
• WFS Capabilities: http://localhost:8080/wfs?request=GetCapabilities

Honua Field Mobile App

Honua Field is the cross-platform mobile companion built with .NET MAUI for iOS and Android. It captures inspections, field reports, and offline spatial data, syncing securely with Honua Server over OIDC. Field teams can collect imagery, asset data, or work orders offline and automatically mirror them into downstream GIS, analytics, or compliance workflows.

Authentication

Honua supports multiple authentication methods:

Method	Description
Local	Username/password with PBKDF2 hashing
JWT Bearer	Standard JWT tokens with revocation support
OIDC	Generic OpenID Connect providers
SAML 2.0	Enterprise SSO integration (Enterprise)
Azure AD	Microsoft Entra ID integration
Google OAuth	Google authentication
API Keys	Header-based API key authentication

Configure via honua:authentication:mode in HCL or environment variables.

Configuration

Honua uses HCL (HashiCorp Configuration Language) as the primary configuration format:

honua {
  environment = "production"
  log_level   = "info"
}

data_source "main" {
  provider   = "postgres"
  connection = "Host=postgres;Database=honua;Username=postgres;Password=${PGPASSWORD}"
  pool = { min_size = 5, max_size = 50 }
}

service "ogc_api" { enabled = true }
service "wfs"     { enabled = true }
service "wms"     { enabled = true }

layer "parcels" {
  data_source = data_source.main
  table       = "public.parcels"
  id_field    = "id"
  geometry    = { column = "geom", type = "MultiPolygon", srid = 4326 }
  services    = ["ogc_api", "wfs", "wms"]
}

Set HONUA_CONFIG_PATH to point to your HCL file. Environment variables and appsettings.json work as fallbacks.

Project Structure

src/
├── apps/
│   ├── host/                  # Main ASP.NET Core web server (Honua.Server.Host)
│   │   ├── Ogc/               # OGC API endpoints
│   │   ├── Stac/              # STAC endpoints
│   │   ├── OData/             # OData endpoints
│   │   ├── Carto/             # Carto SQL API
│   │   ├── OpenRosa/          # OpenRosa/ODK endpoints
│   │   └── Csw/               # CSW endpoints
│   ├── gateway/               # YARP reverse proxy
│   ├── alert-receiver/        # Webhook alert receiver
│   └── admin-blazor/          # Web UI admin portal
├── platform/
│   ├── core/                  # Core geospatial engine, data access, observability
│   ├── core-raster/           # Raster/tile processing
│   ├── core-cloud/            # Cloud storage & messaging
│   ├── http/                  # HTTP infrastructure
│   ├── rendering/             # Map rendering
│   └── observability/         # Metrics, logging, tracing
├── domain/
│   ├── ogc/                   # OGC Web Services (WFS, WMS, WMTS, WCS)
│   ├── ogcapi/                # OGC API domain logic
│   ├── geoservices/           # GeoServices REST domain
│   └── enterprise/            # Enterprise features (sensors, geoprocessing)
├── plugins/                   # Runtime plugin drop (built artifacts)
├── src/plugins/               # Service plugin shims (protocol/cloud/db)
└── tooling/
    ├── cli/                   # Command-line interface
    └── cli-ai/                # DevSecOps agent CLI

tests/                         # Unit, integration, and E2E tests
deploy/
├── kubernetes/                # Helm charts
└── terraform/                 # AWS, Azure, GCP modules
docs/
├── architecture/              # Architecture documentation
└── *.md                       # Feature and deployment guides

AI Capabilities

Honua includes AI-powered features across the platform:

• Natural Language Queries: Convert plain English to CQL2 filters for spatial queries
• AI Map Generation: Generate map configurations and styles from descriptions
• DevSecOps Agent (Honua.Cli.AI): AI-powered platform operations including installation, deployment, configuration, optimization, monitoring, upgrades, diagnostics, and compliance validation

Database Support

Vector Data:

• PostgreSQL/PostGIS (recommended)
• MySQL
• SQL Server
• SQLite
• DuckDB

Enterprise (Optional):

• Snowflake
• Google BigQuery
• Amazon Redshift
• Databricks
• Azure Cosmos DB
• MongoDB
• Elasticsearch
• Oracle

Data Import

Vector File Formats:

• GeoJSON
• Shapefile (ZIP archive)
• GeoPackage
• GML (Geography Markup Language)
• KML/KMZ
• GPX (GPS Exchange Format)
• CSV with geometry (WKT, WKB, or lat/lon columns)

Raster/Coverage Formats:

• GeoTIFF, Cloud Optimized GeoTIFF (COG)
• NetCDF
• HDF5
• GRIB/GRIB2
• Zarr
• JPEG2000

Remote Service Import:

• GeoServices REST / Esri FeatureServer (with pagination and token auth)
• WFS (OGC Web Feature Service 1.0, 1.1, 2.0)
• OGC API Features (with CQL2 filter support)

Output Formats

Vector/Feature Formats:

• GeoJSON, GeoJSON-Seq (newline-delimited)
• Shapefile (ZIP archive)
• GeoPackage
• GML (Geography Markup Language)
• KML/KMZ (Google Earth)
• TopoJSON
• FlatGeobuf
• GeoArrow (Apache Arrow)
• GeoParquet (Apache Parquet)
• MVT (Mapbox Vector Tiles)
• PMTiles

Tabular Formats:

• CSV
• JSON, JSON-LD

Coverage/Raster Formats:

• GeoTIFF, Cloud Optimized GeoTIFF (COG)
• PNG, JPEG, WebP, BMP, GIF
• JPEG2000
• NetCDF
• CoverageJSON
• Zarr

Geometry Text Formats:

• WKT (Well-Known Text)
• WKB (Well-Known Binary)

Docker Image Variants

Image	Description
ghcr.io/honuaio/honua-server:latest	Full features (vector + raster + cloud)
ghcr.io/honuaio/honua-server:lite	Vector-only, smaller footprint

Tests

# Unit tests (fast)
dotnet test --filter Category=Unit

# Integration tests
dotnet test tests/Honua.Server.Host.Tests/

# UI tests (requires Playwright browsers)
npx playwright install --with-deps
dotnet test tests/Honua.Ui.Tests/

# All tests
dotnet test Honua.sln

Documentation

Detailed documentation is in the docs/ folder:

Getting Started

• Quick Start - Getting started guide
• Configuration - HCL and environment settings
• Service & Layer Setup - Exposing your data

Architecture

• Architecture Overview - System design overview
• API Layer - Endpoint routing and handlers
• API Implementation Patterns - Patterns for adding new APIs
• Data Layer - Database providers and repositories
• Services - Core service architecture
• Request Flows - Request processing pipeline

Operations

• Deployment - Docker, Kubernetes, Terraform
• Security - Security configuration and best practices
• Testing - Test execution guide
• Release Readiness - Production checklist
• YARP Gateway - Reverse proxy configuration

API References

• GeoServices REST API - Esri API reference

Legacy documentation is archived in docs/_archive/.

Contributing

See CONTRIBUTING.md for development guidelines and contribution workflow.

License

• Source Code: Elastic License 2.0
• Third-Party Notices: THIRD-PARTY-LICENSES.md