Deployment Guide

A comprehensive guide to deploying GeoServer in any environment — Docker, Kubernetes, cloud, or on-premise. Get your geospatial infrastructure running in minutes.

System Requirements

Before deploying GeoServer, ensure your environment meets the minimum requirements. These specs vary based on deployment type and expected workload.

Docker Deployment

The fastest way to get GeoServer running locally or in a containerized environment. Use the official geoserver/geoserver image from Docker Hub.

Copydocker pull geoserver/geoserver:latest

Copydocker pull geoserver/geoserver:3.1.0

Copydocker run -d \
  --name geoserver \
  -p 8080:8080 \
  -v geoserver-data:/geoserver/data_dir \
  -e GEOSERVER_ADMIN_PASSWORD=ChangeMe! \
  geoserver/geoserver:latest

Copydocker ps | grep geoserver
# Expected output:
# CONTAINER ID   IMAGE                        STATUS          PORTS
# abc123def456   geoserver/geoserver:latest   Up 2 minutes    0.0.0.0:8080->8080/tcp

curl -s http://localhost:8080/geoserver/web | grep -o "GeoServer" | head -1
# Expected output: GeoServer

Kubernetes / Helm Deployment

For production environments, deploy GeoServer on Kubernetes using our official Helm chart. This provides auto-scaling, rolling updates, and high availability.

Copyhelm repo add geoserver https://charts.geoserver.io
helm repo update

Copy# values.yaml
replicaCount: 3

image:
  repository: geoserver/geoserver
  tag: "3.1.0"
  pullPolicy: IfNotPresent

service:
  type: LoadBalancer
  port: 8080

resources:
  requests:
    cpu: "2"
    memory: "4Gi"
  limits:
    cpu: "4"
    memory: "8Gi"

persistence:
  enabled: true
  size: 100Gi
  storageClass: "gp3"

environment:
  GEOSERVER_ADMIN_PASSWORD: "<secure-password>"
  GEOSERVER_DATA_DIR: "/geoserver/data_dir"
  JAVA_OPTS: "-Xms2g -Xmx4g"

ingress:
  enabled: true
  host: geoserver.example.com
  tls:
    enabled: true
    secretName: geoserver-tls

Copyhelm install geoserver geoserver/geoserver \
  -f values.yaml \
  --namespace geoserver \
  --create-namespace \
  --version 2.5.0

Copykubectl get pods -n geoserver
kubectl get svc -n geoserver
kubectl get ingress -n geoserver

CopyapiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: geoserver-hpa
  namespace: geoserver
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: geoserver
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80

Terraform / Cloud Deployment

Deploy GeoServer infrastructure as code on AWS, GCP, or Azure using our Terraform modules.

Copy# Clone the module
git clone https://github.com/geoserver/terraform-aws-geoserver.git
cd terraform-aws-geoserver

# Initialize
terraform init

Copy# variables.tf example
variable "instance_type" {
  default = "r5.xlarge"
}

variable "vpc_cidr" {
  default = "10.0.0.0/16"
}

variable "enable_postgis" {
  default = true
}

variable "geoserver_version" {
  default = "3.1.0"
}

Copy# Review the plan
terraform plan -var-file=environments/production.tfvars

# Apply
terraform apply -var-file=environments/production.tfvars

# Outputs
terraform output
# geoserver_endpoint: https://geoserver.prod.example.com
# admin_username: admin
# admin_password: <stored-in-secrets-manager>

On-Premise Deployment

For organizations requiring full control over infrastructure, GeoServer can be deployed directly on bare metal or virtual machines.

Copy# Ubuntu 22.04 / Debian 12
sudo apt update && sudo apt install -y openjdk-17-jdk \
  nginx git curl wget

# Verify Java
java -version
# openjdk version "17.0.9" 2023-10-17

CopyVERSION=3.1.0
cd /opt
wget https://sourceforge.net/projects/geoserver/files/GeoServer/${VERSION}/geoserver-${VERSION}.war
sudo mkdir -p /opt/geoserver
cp geoserver-${VERSION}.war /opt/geoserver/

Copy# Install Tomcat 10
sudo apt install -y tomcat10 tomcat10-admin

# Deploy the WAR file
sudo cp /opt/geoserver/geoserver-${VERSION}.war \
  /var/lib/tomcat10/webapps/

# Configure JVM memory
sudo nano /etc/default/tomcat10
# JAVA_OPTS="-Xms2048m -Xmx4096m -XX:+UseG1GC"

# Start and enable
sudo systemctl enable tomcat10
sudo systemctl start tomcat10
sudo systemctl status tomcat10

Copy# Install Jetty
sudo apt install -y jetty11

# Deploy
sudo cp /opt/geoserver/geoserver-${VERSION}.war \
  /var/lib/jetty/webapps/geoserver.war

# Configure
sudo nano /etc/jetty/start.ini
# Add: -Xmx4096m

# Start
sudo systemctl enable jetty11
sudo systemctl start jetty11

Copysudo tee /etc/nginx/sites-available/geoserver <<'EOF'
server {
    listen 80;
    server_name geoserver.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name geoserver.example.com;

    ssl_certificate     /etc/letsencrypt/live/geoserver.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/geoserver.example.com/privkey.pem;

    client_max_body_size 500M;

    location /geoserver {
        proxy_pass http://127.0.0.1:8080/geoserver;
        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;
        proxy_read_timeout 300;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/geoserver /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Environment Variables

GeoServer supports extensive configuration via environment variables. Here are the most important ones:

Storage & Database

GeoServer's data directory stores all configurations, styles, layers, and cached tiles. For production, we recommend storing it on persistent volume or in a PostgreSQL database.

Option A: Persistent Volume (Docker/K8s)

Copy# Docker volume
docker volume create geoserver-data

# Verify
docker volume inspect geoserver-data

Option B: PostgreSQL Data Directory

Store your data directory in a PostgreSQL database for easier backups and replication:

Copy# 1. Create the database
createdb -U postgres geoserver

# 2. Run the migration script
docker exec geoserver \
  /geoserver/bin/pgsql-migrate.sh \
  --host=db.example.com \
  --database=geoserver \
  --user=geoserver_admin \
  --password=secret

# 3. Set environment variable
export GEOSERVER_DB_TYPE=postgresql

Networking

GeoServer exposes several ports. Ensure your firewall and security group rules allow the necessary traffic:

Security

Security is critical for geospatial infrastructure. Follow these best practices:

• Always use HTTPS — configure SSL/TLS via your reverse proxy or ingress controller.
• Change default credentials — never ship with admin/geoserver in production.
• Enable authentication — GeoServer supports LDAP, Active Directory, OAuth2, and JWT.
• Set resource quotas — limit WFS feature counts, WMS bounding box sizes, and request timeouts.
• Disable unused services — turn off WFS-T, REST config API, or other endpoints not in use.
• Apply security headers — use your reverse proxy to inject CSP, HSTS, and X-Frame-Options headers.
• Network segmentation — place GeoServer in a private subnet with only required ports exposed.

Enable OAuth2 Authentication

Copy# In your values.yaml or environment
GEOSERVER_SECURITY_AUTH_MODULE=oauth2
OAUTH2_ISSUER_URI=https://auth.example.com
OAUTH2_CLIENT_ID=geoserver-client
OAUTH2_CLIENT_SECRET=secret_value_here
OAUTH2_SCOPES=openid profile

Monitoring

GeoServer ships with built-in metrics endpoints compatible with Prometheus and Grafana.

Prometheus Configuration

Copy# prometheus.yml
scrape_configs:
  - job_name: 'geoserver'
    metrics_path: '/geoserver/rest/metrics'
    scrape_interval: 15s
    static_configs:
      - targets: ['geoserver:8080']

Key Metrics to Monitor

Scaling

GeoServer supports both horizontal and vertical scaling:

Horizontal Scaling

• Deploy multiple GeoServer instances behind a load balancer
• Use a shared data directory (PostgreSQL or NFS)
• Enable sticky sessions for long-running WFS-T transactions
• Configure Redis for distributed tile caching

Vertical Scaling

• Increase JVM heap: JAVA_OPTS="-Xms4g -Xmx8g"
• Use G1GC for large heaps: -XX:+UseG1GC -XX:MaxGCPauseMillis=200
• Enable map tile caching to reduce rendering load

Backup & Restore

Backup (File-Based)

Copy# Docker
docker exec geoserver \
  tar czf /tmp/geoserver-backup-$(date +%F).tar.gz \
  /geoserver/data_dir/

docker cp geoserver:/tmp/geoserver-backup-$(date +%F).tar.gz ./

# Kubernetes
kubectl exec -n geoserver geoserver-pod \
  -- tar czf /tmp/backup.tar.gz /geoserver/data_dir/

Restore

Copy# Stop GeoServer
docker stop geoserver

# Copy backup back
docker cp ./geoserver-backup-2025-01-15.tar.gz \
  geoserver:/tmp/

# Extract
docker exec geoserver \
  tar xzf /tmp/geoserver-backup-2025-01-15.tar.gz \
  -C /

# Restart
docker start geoserver

Troubleshooting

Common Issues

GeoServer Fails to Start

Copy# Check container logs
docker logs geoserver --tail 50

# Common causes:
# 1. Port 8080 already in use → change with -p 9090:8080
# 2. Insufficient memory → increase JVM heap
# 3. Permission denied on data_dir → fix ownership
# 4. Java version mismatch → use OpenJDK 17+

Layers Not Rendering

• Check the logs/geoserver.log file for CRS errors
• Verify the data store connection is working
• Ensure the layer's bounding box is correctly set
• Check if the style (SLD) references valid attributes

High Memory Usage

Copy# Check JVM memory
docker exec geoserver jcmd 1 VM.gc_heap_info

# Tune GC settings
JAVA_OPTS="-Xms4g -Xmx8g \
  -XX:+UseG1GC \
  -XX:MaxGCPauseMillis=200 \
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:HeapDumpPath=/geoserver/logs/"

Slow Map Rendering

• Enable tile caching (GeoWebCache is bundled)
• Optimize SLD styles — avoid complex filters
• Use vector tiles instead of WMS for large datasets
• Check database query performance for feature stores

Upgrades

When upgrading GeoServer, follow these steps to ensure a smooth transition:

1. Back up your data directory and database
2. Read the release notes for breaking changes
3. Test in staging before upgrading production
4. Update the image/container to the new version
5. Verify all layers, styles, and services work correctly

Copy# Docker upgrade
docker pull geoserver/geoserver:3.1.0
docker stop geoserver && docker rm geoserver
docker run -d \
  --name geoserver \
  -p 8080:8080 \
  -v geoserver-data:/geoserver/data_dir \
  geoserver/geoserver:3.1.0

# Helm upgrade
helm upgrade geoserver geoserver/geoserver \
  -f values.yaml \
  --set image.tag="3.1.0" \
  --namespace geoserver