Get Started Guide

System Requirements

Minimum Specifications

Java 11+ (OpenJDK or Oracle recommended)
2GB RAM (4GB+ for production workloads)
PostgreSQL 13+ or SQLite for spatial databases
Node.js 18+ (optional, for CLI tools)
500MB free disk space

Installation

Choose your operating system and follow the corresponding setup commands. We recommend using the official Docker image for isolated environments.

bash
# Install dependencies
sudo apt update && sudo apt install -y openjdk-17-jdk postgresql postgresql-contrib

# Download GeoServer binary
wget https://downloads.osgeo.org/live/geoserver/geoserver-latest-bin.zip

# Extract and run
unzip geoserver-latest-bin.zip -d /opt/geoserver
sudo /opt/geoserver/bin/startup.sh

zsh
# Using Homebrew
brew install openjdk postgresql

# Install GeoServer via formula
brew install --cask geoserver

# Launch service
brew services start geoserver

powershell
# Using winget
winget install EclipseAdoptium.Temurin.17.JDK

# Download and extract GeoServer
Invoke-WebRequest -Uri \"https://downloads.osgeo.org/live/geoserver/geoserver-latest-bin.zip\" -OutFile \"geoserver.zip\"
Expand-Archive -Path \"geoserver.zip\" -DestinationPath \"C:\\Program Files\\GeoServer\"

# Run startup script
& \"C:\\Program Files\\GeoServer\\bin\\startup.bat\"

bash
# Pull and run official image
docker run -d --name geoserver \\
  -p 8080:8080 \\
  -v geodata:/opt/geoserver/data_dir \\
  geoserver/geoserver:latest

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

Initial Configuration

1

Access the Admin Console

Navigate to http://localhost:8080/geoserver/web/. Use the default credentials: admin / geoserver. Change these immediately in Production Mode.

2

Create a Workspace & Data Store

Go to Data → Workspaces to create your organization namespace. Then configure a Data Store pointing to your PostgreSQL/PostGIS database or file system.

3

Set Caches & Logging

Enable Image Caching for WMS tiles under Services → WMS. Configure logging levels in Server → Logging for debugging.

Create Your First Layer

Once your data store is connected, publish a layer using the CLI or web UI. Here's a quick Python snippet using geoapi:

python
# Publish a GeoJSON layer via REST API
import requests
import json

payload = {
    "workspace": "default",
    "name": "sample_points",
    "nativeCRS": "EPSG:4326",
    "srs": "EPSG:4326"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Basic YWRtaW46Z2Vvc2VydmVy"
}

response = requests.post(
    "http://localhost:8080/geoserver/rest/workspaces/default/datastores/mystore/featuretypes",
    json=payload, headers=headers
)
print(response.status_code, response.text)

API Quickstart

GeoServer exposes OGC-compliant endpoints alongside a REST administrative API. Common starting points:

Endpoint	Method	Use Case
`/ows`	GET	Service discovery & capabilities
`/wms`	GET	Render map images (PNG/JPEG/TIFF)
`/wfs`	GET / POST	Query & edit feature data
`/rest/config`	POST / PUT	Programmatic admin configuration

Verification Checklist

Track your progress. Checked items are saved locally in your browser.

Java environment verified (`java -version`)
GeoServer process running on port 8080
Admin console accessible & credentials changed
PostGIS/SQLite data store connected
First layer published & visible in layer preview
WMS/WFS endpoints responding with valid XML

Troubleshooting

Common Issues & Fixes

Port 8080 in use: Run netstat -tulpn | grep 8080 or change `
Permission denied on data_dir: Ensure the runtime user owns `/opt/geoserver/data_dir` recursively: sudo chown -R $USER:$GROUP /opt/geoserver/data_dir.
WMS blank tiles: Verify CRS matches layer projection, check logging for `java.lang.OutOfMemoryError`, and increase JVM heap in `startup.sh`.

Still stuck? Check the server logs or open an issue on GitHub.