Deployment Guides

Step-by-step instructions for deploying, configuring, and scaling GeoServer across containerized, cloud, and on-premise environments.

# Overview

GeoServer supports multiple deployment architectures depending on your scale, security requirements, and infrastructure preferences. This guide covers production-ready configurations with focus on reliability, performance, and security best practices.

ℹ️
All deployment methods assume you are using GeoServer 3.2+. Legacy 2.x deployments are available in our archives.

# Prerequisites

Before deploying, ensure your environment meets the following requirements:

  • Java Runtime: OpenJDK 11, 17, or 21 (LTS recommended)
  • Memory: Minimum 2GB RAM (4GB+ recommended for production)
  • Disk: 10GB+ for base install, additional for workspace data
  • Network: Outbound internet access for plugin updates (or configure offline repo)
  • Docker: v20.10+ with Compose v2+ (for container deployments)

# Docker & Containers

The fastest way to get a production-ready instance running. Official images are published on Docker Hub and support ARM64 and AMD64 architectures.

Pull the Official Image

Always use the official registry to ensure security patches and verified builds.

Run with Default Configuration

Start a container with exposed ports and persistent data volumes.

Verify Deployment

Check logs and access the web UI to confirm successful startup.

# Pull latest stable release
docker pull geoserver/geoserver:3.2-latest-jdk17

# Run with persistent data and memory limits
docker run -d \
  --name geoserver \
  -p 8080:8080 \
  -v geoserver_data:/geoserver/data_dir \
  -e GEOSERVER_DATA_DIR=/geoserver/data_dir \
  -e JAVA_OPTS="-Xms1g -Xmx2g -XX:+UseG1GC" \
  geoserver/geoserver:3.2-latest-jdk17

# Kubernetes & Helm

For enterprise orchestration, deploy using our official Helm chart. It supports horizontal scaling, auto-healing, and integrated service mesh compatibility.

# Add official Helm repository
helm repo add geoserver https://charts.geoserver.io
helm repo update

# Deploy with production values
helm install geoserver geoserver/geoserver \
  --set replicaCount=2 \
  --set resources.limits.memory=2Gi \
  --set persistence.enabled=true \
  --set ingress.enabled=true \
  --set ingress.hosts[0]=geo.example.com
⚠️
GeoServer is stateful. When scaling beyond 1 replica, ensure all pods share the same persistent volume or use a distributed data store for the workspace directory.

# VM & Bare Metal

Direct deployment is ideal for air-gapped environments or legacy infrastructure. We provide DEB, RPM, and binary tarball packages.

Ubuntu/Debian Installation

sudo apt update
sudo apt install -y openjdk-17-jdk wget
wget https://download.geoserver.io/stable/geoserver-3.2.0-bin.zip
unzip geoserver-3.2.0-bin.zip -d /opt/geoserver
sudo systemctl start geoserver.service

Configuration

Modify /etc/default/geoserver to set memory, user, and log paths before starting the service.

# Cloud Providers

One-click deployments available for major cloud platforms. These templates are optimized for auto-scaling groups and managed storage.

Provider Template Type Est. Monthly Cost (S)
AWS CloudFormation / ECS Fargate ~$45
Azure ARM Template / AKS ~$42
GCP Deployment Manager / GKE ~$48

# Environment Variables

Configure GeoServer behavior without modifying XML files. All variables are prefixed with GEOSERVER_ or GEOSERVER_ in containers.

Variable Description Default
GEOSERVER_DATA_DIR Path to workspace directory /geoserver/data
GEOSERVER_ADMIN_PASSWORD Initial admin password geoserver
JAVA_OPTS JVM flags -Xms512m -Xmx1024m
GEOSERVER_MAX_MEMORY Override JVM heap size 2g

# Monitoring & Logs

Production deployments should integrate with your observability stack. GeoServer exposes standard metrics endpoints.

  • Prometheus Metrics: /geoserver/metrics/prometheus (requires JMX exporter plugin)
  • Health Check: /geoserver/web/health returns 200 OK when ready
  • Structured Logging: Enable JSON output via log4j2.xml configuration
# Example Prometheus scrape config
scrape_configs:
  - job_name: geoserver
    metrics_path: /geoserver/metrics/prometheus
    static_configs:
      - targets: ['localhost:8080']

# Troubleshooting

Common Issues

  • Out of Memory Errors: Increase GEOSERVER_MAX_MEMORY or tune G1GC flags
  • Permission Denied on Data Dir: Ensure container user matches volume UID (1000:1000)
  • CORS Errors: Enable CORS plugin or configure reverse proxy headers
  • Slow Layer Rendering: Check data source connectivity and enable WMTS caching
💡
Run docker logs geoserver --tail 50 or check webapps/geoserver/WEB-INF/logs/ for detailed error traces.

# Upgrades & Rollbacks

Follow our semantic versioning. Minor patches are backward-compatible. Major versions require data directory migration.

  1. Backup GEOSERVER_DATA_DIR and plugins directory
  2. Stop the running instance
  3. Update image/package version
  4. Run migration script if crossing major versions
  5. Verify layer rendering and WMS/WFS endpoints
# Rolling update in Kubernetes
helm upgrade geoserver geoserver/geoserver \
  --set image.tag=3.3.0-jdk17 \
  --set strategy.type=RollingUpdate