Quick Start

# Linux (AMD64)
tar -xzf geovertix-community-linux-amd64.tar.gz
cd geovertix-community

# macOS (Apple Silicon)
tar -xzf geovertix-community-macos-arm64.tar.gz
cd geovertix-community

# Windows (AMD64) — via WSL2
tar -xzf geovertix-community-linux-amd64.tar.gz
cd geovertix-community

# Extract (choose your platform)
tar -xzf geovertix-enterprise-linux-amd64.tar.gz     # Linux / WSL2
tar -xzf geovertix-enterprise-macos-arm64.tar.gz     # macOS Apple Silicon
cd geovertix-enterprise

# Place your license files
cp /path/to/license.key .
cp /path/to/license.key.sig .

# Place your mTLS certificates
mkdir -p certs
cp /path/to/client-cert.pem certs/
cp /path/to/client-key.pem certs/

$ ./geovertix install

GeoVertix Community — Installation
==============================

Checking for PostgreSQL...
  ✓ PostgreSQL is running

Database setup
  Do you already have a database for GeoVertix? [y/N]: n
  Database name [geovertix]: <enter>
  Username [geovertix]: <enter>
  Password: ********
  Confirm:  ********

Step 1/6: Checking prerequisites...
  ✓ PostgreSQL 16.2 (connected)
  ✓ PostGIS 3.4 (extension available)
  ✓ GEOS 3.12.2
  ✓ PROJ 9.5.1

Step 2/6: Database setup...
  Creating schema 'geovertix'...
  Creating tables and indexes... done

Step 3/6: Create admin user
  Username: admin
  Password: ********
  Confirm:  ********
  Email (optional): <enter>
  ✓ Admin user 'admin' created

Step 4/6: Configuration
  ✓ JWT_SECRET generated
  ✓ Log directory created: logs/

Step 5/6: Verify
  ✓ Ready to serve

Server configuration
  Bind address [127.0.0.1]: 0.0.0.0
  Server port [7501]: <enter>
  Max upload size (MB) [2048]: <enter>
  GIS data schema [gisdata]: <enter>
  Log level (debug/info/warn/error) [info]: <enter>
  ✓ Config written to ./config/geovertix.toml

# Start in foreground (for development)
./geovertix serve --foreground

# Or start as a daemon (default)
./geovertix serve

# Output:
✓ WMS available at /wms
✓ WFS available at /wfs
✓ MVT available at /tiles
✓ COG available at /raster
✓ API available at /api/v1
✓ Server ready on http://0.0.0.0:7501

# Upload a Shapefile via API
curl -X POST http://localhost:7501/api/v1/import/upload \
  -H "Cookie: auth_token=<jwt>" \
  -F "file=@parcels.zip"

# The server detects layers, imports to PostGIS,
# and auto-registers them for WMS/WFS/MVT.

# WMS endpoint
http://localhost:7501/wms?SERVICE=WMS&REQUEST=GetCapabilities

# WFS endpoint
http://localhost:7501/wfs?SERVICE=WFS&REQUEST=GetCapabilities

# MVT tiles
http://localhost:7501/tiles/{layer}/{z}/{x}/{y}.pbf

# ./config/geovertix.toml

# Database connection (required)
[database]
url = "postgres://geovertix:<your_password>@localhost:5432/geovertix"

# Server settings
[server]
host = "127.0.0.1"   # default; use "0.0.0.0" for all interfaces
port = 7501            # Community default (Enterprise: 7500)
# docs_self_hosted = false  # Serve API docs from embedded assets (air-gapped)

# Data storage
[storage]
import_schema = "gisdata"
max_upload_size_mb = 2048

# Logging
[logging]
level = "info"         # debug, info, warn, error

# Config file path
export GEOVERTIX_CONFIG="./config/geovertix.toml"

# Database (overrides [database] url)
export GEOVERTIX_DATABASE_URL="postgres://..."

# JWT secret (auto-generated by install into .env)
export JWT_SECRET="..."

# Server
export GEOVERTIX_SERVER_HOST="0.0.0.0"
export GEOVERTIX_SERVER_PORT=7501

# Storage
export GIS_DATA_SCHEMA="gisdata"
export MAX_UPLOAD_SIZE_MB=2048

# The install command will:
# 1. Check for PostgreSQL (offer to install from PGDG if missing)
# 2. Create database + user (or connect to existing)
# 3. Enable PostGIS extension
# 4. Create schemas: geovertix (metadata) + gisdata (spatial data)
# 5. Create admin user
$ ./geovertix install

[database]
url = "postgres://geovertix:<your_password>@localhost:5432/geovertix"
# read_url = "postgres://..."  # Optional read replica
pool_min = 2                    # Minimum connections (default: 2)
pool_max = 20                   # Maximum connections (default: 20)
connection_timeout_ms = 5000    # Connection timeout (default: 5s)
statement_timeout_ms = 30000   # Query timeout (default: 30s)
idle_timeout_ms = 600000       # Idle timeout (default: 10min)

[wms]
enabled = true                          # Enable WMS service
title = "GeoVertix - FAST web map services"  # GetCapabilities title
max_layers = 20                         # Max layers per GetMap request
default_format = "image/png"              # Default output format

# Rendering limits (shared by WMS/MVT)
[rendering]
max_width = 4096                # Max image width in pixels
max_height = 4096               # Max image height in pixels
max_concurrent_renders = 8      # Parallel render limit
max_geometry_vertices = 1000000  # Max vertices per request
fonts_dir = "./fonts"            # Font directory for labels

[wfs]
enabled = true                # Enable WFS service
max_features = 10000          # Hard limit per request
default_count = 1000           # Default if COUNT not specified

[wfs.transaction]
enabled = false               # WFS-T disabled by default
max_insert_batch = 1000       # Max features per insert
max_update_batch = 5000       # Max features per update
max_delete_batch = 1000       # Max features per delete

[cache]
enabled = true             # Global cache toggle

# Tile cache (rendered WMS images)
[cache.tile]
enabled = true
backend = "memory"         # "memory" or "redis" (Enterprise only)
max_entries = 10000
max_size_mb = 512
ttl_seconds = 3600          # 1 hour

# Query cache (PostGIS feature results)
[cache.query]
enabled = true
max_entries = 5000
max_size_mb = 256
ttl_seconds = 1800          # 30 minutes

GET /api/v1/layers

// Response
[
  {
    "id": 1,
    "schema_name": "gisdata",
    "table_name": "parcels",
    "geometry_type": "MultiPolygon",
    "srid": 4326,
    "style_name": "default",
    "is_public": false,
    "owner": "admin"
  }
]

# First-time setup
$ ./geovertix install

# Start as daemon (default)
$ ./geovertix serve
Server started (PID 12345)

# Start in foreground (for development)
$ ./geovertix serve --foreground
✓ Listening on 0.0.0.0:7501

# Graceful stop
$ ./geovertix stop
Server stopped

# Pre-generate tiles (Enterprise only)
$ ./geovertix seed -l parcels --min-zoom 0 --max-zoom 14 -c 8

$ ./geovertix license info

License Status: VALID
  ID:         acme-corp-2026
  Licensee:   Acme Corporation
  Email:      admin@acme.com
  Plan:       enterprise
  Issued:     2026-01-15T00:00:00Z
  Expires:    2027-01-15T00:00:00Z (336 days remaining)

$ ./geovertix license verify ./new-license.key
License is VALID: Acme Corporation (acme-corp-2026)

$ ./geovertix license machine-id

Machine ID: a1b2c3d4e5f6...  (64-char hex)
Platform:   linux (/etc/machine-id)

Provide this value to your license administrator.

# API server (handles HTTP: WMS, WFS, REST)
./geovertix serve

# Worker on same machine
./geovertix-worker

# Or scale out — run additional workers on other machines
# (all pointing to the same PostgreSQL database)
ssh worker-2 "./geovertix-worker"
ssh worker-3 "./geovertix-worker"

# Enterprise only — in config/geovertix.toml
[worker]
max_concurrent_tasks = 4   # Per worker instance (default: 4)

attribute = 'value'
attribute > 100
attribute >= 100
attribute < 100
attribute <= 100
attribute != 'value'
attribute LIKE 'prefix%'       # % = any chars, _ = single char
attribute IN ('a', 'b', 'c')
attribute IS NULL
attribute IS NOT NULL

expr AND expr
expr OR expr
NOT expr
(expr)   # grouping

BBOX(minx, miny, maxx, maxy)
BBOX(minx, miny, maxx, maxy, 'EPSG:4326')
INTERSECTS(geometry_wkt)
WITHIN(geometry_wkt)
CONTAINS(geometry_wkt)
CROSSES(geometry_wkt)

# Simple attribute filter
population > 1000000

# Combined filters
zone = 'residential' AND area_sqm < 500

# Pattern matching
name LIKE 'North%'

# Spatial + attribute
zone = 'commercial' AND BBOX(106.7, -6.3, 106.9, -6.1)

{
  "rules": [
    {
      "name": "Default",
      "fill": {
        "color": "#3b82f6",
        "opacity": 0.5
      },
      "stroke": {
        "color": "#1e40af",
        "width": 1
      }
    }
  ]
}

{
  "rules": [
    {
      "name": "Residential",
      "filter": "zone = 'residential'",
      "fill": { "color": "#4ade80" }
    },
    {
      "name": "Commercial",
      "filter": "zone = 'commercial'",
      "fill": { "color": "#f59e0b" }
    },
    {
      "name": "Industrial",
      "filter": "zone = 'industrial'",
      "fill": { "color": "#ef4444" }
    }
  ]
}

{
  "rules": [{
    "stroke": {
      "color": "#0891b2",
      "width": {
        "stops": [[8, 0.5], [12, 1], [16, 3]]
      }
    },
    "label": {
      "field": "name",
      "size": { "stops": [[10, 10], [16, 16]] },
      "color": "#0f172a",
      "halo_color": "#ffffff",
      "halo_width": 2,
      "min_zoom": 12
    }
  }]
}

/opt/geovertix/
├── geovertix              # Binary
├── config/
│   └── geovertix.toml     # Configuration
├── .env                   # JWT_SECRET (auto-generated)
├── fonts/                 # Font files for labels
├── logs/                  # Log files
└── libs/                  # Bundled shared libraries (Linux)
    ├── libgdal.so
    ├── libgeos.so
    ├── libproj.so
    └── ...

server {
    listen 443 ssl http2;
    server_name maps.example.com;

    ssl_certificate     /etc/ssl/certs/maps.crt;
    ssl_certificate_key /etc/ssl/private/maps.key;

    add_header X-Frame-Options "DENY";
    add_header X-Content-Type-Options "nosniff";
    add_header Referrer-Policy "strict-origin-when-cross-origin";
    add_header Content-Security-Policy "default-src 'self'";

    location / {
        proxy_pass http://127.0.0.1:7501;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# /etc/systemd/system/geovertix.service
[Unit]
Description=GeoVertix WMS/WFS Server
After=network.target postgresql.service

[Service]
Type=simple
User=geovertix
WorkingDirectory=/opt/geovertix
ExecStart=/opt/geovertix/geovertix serve --foreground
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable geovertix
sudo systemctl start geovertix

# Check status
sudo systemctl status geovertix

# View logs
journalctl -u geovertix -f

# Detailed health (includes DB, GEOS, PROJ status)
GET /api/v1/system/health

# Liveness probe (for load balancers)
GET /api/v1/system/ready

# Version info
GET /api/v1/system/info

# Available metrics include:
geovertix_http_requests_total{service, operation, status}
geovertix_http_request_duration_seconds{service, operation}
geovertix_cache_hits_total{cache_type}
geovertix_cache_misses_total{cache_type}
geovertix_db_pool_connections{state}
geovertix_import_jobs_total{status}

# Default (info level)
export RUST_LOG=info

# Debug WMS rendering
export RUST_LOG=geovertix_wms=debug

# Debug everything
export RUST_LOG=debug

# Example plugin.toml
name = "lidar"
binary = "bin/gxp-lidar"
description = "COPC point cloud streaming"

# Task submission
POST /api/v1/process
{
  "operation": "store.import_pointcloud",
  "params": { "source": "survey.las" }
}

# Check task status
GET /api/v1/tasks/{task_id}