Getting Started

What is GeoServer?

GeoServer is an open-source server for sharing geospatial data. It publishes data from any major spatial data source using open standards. It's designed for interoperability and implements OGC standards including WMS, WFS, WCS, and WMTS.

With GeoServer, you can:

Serve map layers from PostGIS, GeoPackage, Shapefiles, and more
Style data using SLD, CSS, or Vector Marker styles
Protect data with role-based access control
Integrate with QGIS, Leaflet, MapLibre, and other clients

ℹ️

Recommended

If you're new to geospatial concepts, check out our Geospatial 101 primer before proceeding with this guide.

System Requirements

Before installing GeoServer, ensure your environment meets the following requirements:

Component	Minimum	Recommended
Java Runtime	Java 11	Java 17 (LTS)
RAM	2 GB	8 GB+
Storage	1 GB	SSD, 10 GB+
Web Server	Tomcat 9	Tomcat 10 / Jetty 12
Database (optional)	PostgreSQL 12	PostgreSQL 15 + PostGIS 3.3
Docker (optional)	Docker 20.10+	Docker 24+ / Podman

⚠️

Java Version Compatibility

GeoServer 2.24+ requires Java 11 or later. Using Java 17 is strongly recommended for production deployments due to performance improvements and long-term support.

Installation

GeoServer can be installed in multiple ways depending on your deployment needs. Choose the method that best fits your workflow.

Option 1: Docker (Recommended)

The fastest way to get started. This pulls the latest GeoServer stable release and runs it on port 8080.

Bash

# Run GeoServer in a container
$ docker run -d \
  --name geoserver \
  -p 8080:8080 \
  -v geoserver_data:/opt/geoserver/data_dir \
  geoserver/unstable:latest

# Verify it's running
$ docker logs geoserver
# → INFO: Started GeoServer 2.25.3

docker-compose.yml

version: "3.8"

services:
  geoserver:
    image: geoserver/unstable:latest
    container_name: geoserver
    ports:
      - "8080:8080"
    volumes:
      - geoserver_data:/opt/geoserver/data_dir
    environment:
      - GEOSERVER_MAX_MEMORY=2048m
      - GEOSERVER_ADMIN_PASSWORD=admin

  postgis:
    image: postgis/postgis:15-3.3
    container_name: postgis
    environment:
      - POSTGRES_DB=gis
      - POSTGRES_USER=geoserver
      - POSTGRES_PASSWORD=geoserver
    ports:
      - "5432:5432"

volumes:
  geoserver_data:

Option 2: Binary (WAR Deployment)

Download the standalone binary and deploy the WAR file to your servlet container.

Bash

# Download GeoServer
$ curl -L https://sourceforge.net/projects/geoserver/files/GeoServer/2.25.3/geoserver-2.25.3-bin.zip -o geoserver.zip

# Extract
$ unzip geoserver.zip -d /opt/
$ cd /opt/geoserver-2.25.3

# Start Jetty embedded server
$ bin/start.sh

# Access at http://localhost:8080/geoserver/web

Option 3: Package Managers

macOS (Homebrew)

$ brew install geoserver

Linux (apt)

# Add the GeoServer repository
$ curl -fsSL https://repo.geoserver.org/geoserver.list | sudo tee /etc/apt/sources.list.d/geoserver.list
$ sudo apt update
$ sudo apt install geoserver

Quick Start

Follow these steps to get your first map layer published in under 5 minutes.

1

Start GeoServer

Launch the server and navigate to the admin console at http://localhost:8080/geoserver/web. Default credentials are admin / geoserver.

2

Create a Workspace

Workspaces are namespaces for organizing your data. Go to Data → Workspaces and click Add new. Enter a name like myproject and a namespace URL like http://example.com/myproject.

3

Add a Data Store

Navigate to Data → Stores, select your workspace, and choose a store type. For quick testing, use a Shapefile data store and upload your .shp files.

4

Publish a Layer

After adding your store, go to Layers → Add a new resource. Select your data, configure the bounding box (GeoServer will auto-detect it), and click Save.

5

View Your Layer

Go to the Layer Preview tab and click any OGC link (e.g., OpenLayers) to see your map in the browser. Congratulations — your first layer is live!

💡

Pro Tip

Use the REST API to automate this entire workflow. See the REST API section for scripting examples with curl.

Configuration

GeoServer is highly configurable. The most important settings are located in the global.properties file and the web admin console.

Key Properties

The data directory (usually /opt/geoserver/data_dir) contains all configuration files. Here are the most commonly modified settings:

global.properties

# Memory settings for JVM (set via environment or startup script)
GEOSERVER_MAX_MEMORY=2048m
GEOSERVER_MIN_MEMORY=512m

# Proxy settings for remote data sources
proxyBaseUrl=https://maps.example.com/geoserver
onlineResources=false

# Contact information (required by OGC spec)
contactPerson=John Doe
contactEmail=john@example.com
organization=GeoServer Inc.

JVM Arguments

For production deployments, optimize the JVM with these recommended flags:

Bash

$ export JAVA_OPTS="\
  -Xms1024m \
  -Xmx2048m \
  -XX:+UseG1GC \
  -XX:MaxGCPauseMillis=200 \
  -XX:+ParallelRefProcEnabled \
  -Dorg.geotools.shapefile.datetime=true \
  -DGEOSERVER_DATA_DIR=/opt/geoserver/data_dir"

Workspaces

Workspaces provide a namespace for your data, separating layers from different projects or teams. Each workspace has a unique name and namespace URI.

Creating via REST API

Bash (curl)

$ curl -v -u admin:geoserver \
  -X POST \
  -H "Content-type: text/xml" \
  -d <workspace><name>myproject</name></workspace> \
  http://localhost:8080/geoserver/rest/workspaces

Creating via Web UI

Log in to the admin console
Navigate to Data → Workspaces
Click Add new
Fill in the Name and Namespace URI
Click Save

Data Stores

Data stores are the connection points between GeoServer and your actual data. GeoServer supports many store types:

Store Type	Best For	Plugin Required
`PostGIS`	Production databases, large datasets	Built-in
`GeoPackage`	Portable, file-based OGC standard	Built-in
`Shapefile`	Quick testing, legacy data	Built-in
`GeoTIFF`	Raster imagery, elevation data	Built-in
`MySQL / MariaDB`	Existing MySQL infrastructure	Plugin
`ArcSDE`	Enterprise Esri environments	Plugin

Connecting to PostGIS

Bash (curl)

$ curl -v -u admin:geoserver \
  -X POST \
  -H "Content-type: text/xml" \
  -d \\n    <dataStore>\\n      <name>myproject-db</name>\\n      <connectionParameters>\\n        <host>localhost</host>\\n        <port>5432</port>\\n        <database>gis</database>\\n        <user>geoserver</user>\\n        <password>geoserver</password>\\n        <dbtype>postgis</dbtype>\\n      </connectionParameters>\\n    </dataStore> \
  http://localhost:8080/geoserver/rest/workspaces/myproject/datastores

Layers

A layer is a single dataset published through GeoServer. After adding a data store, you publish individual tables or files as layers.

Layer Properties

When publishing a layer, you configure:

Native & Declared SRS — Coordinate reference systems (e.g., EPSG:4326)
Lat/Lon Bounding Box — Geographic extent for discovery
Style — Default SLD or CSS styling rules
Metadata — Title, abstract, keywords for OGC discovery

⚠️

Always define the bounding box

If the bounding box is incorrect, your layer may not appear in map clients. Use the Compute from native bounds and Compute from declared bounds buttons to auto-calculate.

Styles & SLD

GeoServer uses Styled Layer Descriptor (SLD) documents to define how vector and raster data appears on maps. You can also use CSS-based styling for vector layers.

Basic Point Style (SLD)

XML (SLD)

<StyledLayerDescriptor version="1.1.0"
  xmlns="http://www.opengis.net/sld"
  xmlns:sld="http://www.opengis.net/sld">

  <NamedLayer>
    <Name>my-points</Name>
    <UserStyle>
      <FeatureTypeStyle>
        <Rule>
          <PointSymbolizer>
            <Graphic>
              <Mark>
                <WellKnownName>circle</WellKnownName>
                <Fill>
                  <CssParameter name="fill">
                    <ogc:Literal>#00b4d8</ogc:Literal>
                  </CssParameter>
                </Fill>
              </Mark>
              <Size>8</Size>
            </Graphic>
          </PointSymbolizer>
        </Rule>
      </FeatureTypeStyle>
    </UserStyle>
  </NamedLayer>
</StyledLayerDescriptor>

Basic Vector Style (CSS)

CSS

/* Simple line style */
* {
  stroke: #00b4d8;
  stroke-width: 2;
}

/* Conditional styling based on attribute */
*[highway = "motorway"] {
  stroke: #f0c040;
  stroke-width: 4;
}

*[highway = "residential"] {
  stroke: #c8d6e5;
  stroke-width: 1;
}

Security

GeoServer provides built-in security for authentication, authorization, and data protection.

Security Layers

Authentication — Verify user identity (LDAP, Database, Keycloak, etc.)
Authorization — Define who can access what (ROLE_ADMIN, ROLE_GUEST, custom roles)
Data Security — Filter features and properties per user/role
Service Security — Restrict access to WMS, WFS, and REST endpoints

💡

Production Security Checklist

Always change default credentials, disable anonymous access, enable HTTPS, and set up proper firewall rules before deploying to production.

Getting Started with GeoServer

What is GeoServer?

System Requirements

Installation

Option 1: Docker (Recommended)

Option 2: Binary (WAR Deployment)

Option 3: Package Managers

Quick Start

Start GeoServer

Create a Workspace

Add a Data Store

Publish a Layer

View Your Layer

Configuration

Key Properties

JVM Arguments

Workspaces

Creating via REST API

Creating via Web UI

Data Stores

Connecting to PostGIS

Layers

Layer Properties

Styles & SLD

Basic Point Style (SLD)

Basic Vector Style (CSS)

Security

Security Layers