Installing PostGIS and GeoServer with Docker

Introduction

Setting up PostGIS and GeoServer in Geographic Information Systems (GIS) projects can be confusing due to the complexities of the configuration. Especially when using Docker, we frequently encounter questions like “I’m accessing from the outside, but the containers can’t see each other” or “Which port should I use?”

In this guide, we’ll create a clean PostGIS + GeoServer setup based on the Docker networking logic, which you can get up and running in just a few minutes. We’ll look behind the scenes of port mapping, eliminating the confusion.

1- Architecture & Network Flow

The system’s communication logic can be broken down into two distinct layers:

A. External Access (Host to Container)

These are the ports used to access the services from your host machine or external tools:

• Web Browser → localhost:8081 → GeoServer
• DB Tools (DBeaver, psql, etc.) → localhost:5433 → PostGIS

B. Internal Communication (Container to Container)

This is how the containers communicate with each other within the private Docker network (geonet):

• GeoServer → postgis_db:5432 → PostGIS

2- Create Project Folder

mkdir postgis-geoserver
cd postgis-geoservermkdir postgis-geoserver cd postgis-geoserve

3- Create docker-compose.yml

version: '3.8'

services:

  postgis:
    image: postgis/postgis:15-3.3
    container_name: postgis_db
    environment:
      POSTGRES_DB: geodata
      POSTGRES_USER: geouser
      POSTGRES_PASSWORD: geopassword
    ports:
      - "5433:5432"   # Host:5433 → Container:5432
    volumes:
      - postgis_data:/var/lib/postgresql/data
    networks:
      - geonet
    restart: unless-stopped

  geoserver:
    image: kartoza/geoserver:2.23.0
    container_name: geoserver_app
    environment:
      GEOSERVER_ADMIN_USER: admin
      GEOSERVER_ADMIN_PASSWORD: geoserver
      INITIAL_MEMORY: 512M
      MAXIMUM_MEMORY: 1G
    ports:
      - "8081:8080"   # Host:8081 → Container:8080
    volumes:
      - geoserver_data:/opt/geoserver/data_dir
    depends_on:
      - postgis
    networks:
      - geonet
    restart: unless-stopped

volumes:
  postgis_data:
  geoserver_data:

networks:
  geonet:
    driver: bridge

4- Run services using docker-compose.yml

docker compose up -d

Check that both containers are running:

docker compose ps

Then open GeoServer in the browser:

http://localhost:8081/geoserver

5- Connecting to PostGIS from the Machine

If you want to connect directly from your host machine (outside the containers), user the published port:

psql -h localhost -p 5433 -U geouser -d geodata

6- Connecting GeoServer to PostGIS

When you create the store in GeoServer:

• host: postgis_db
• port: 5432
• database: geodata
• user: geouser
• passwd: geopassword

Heads up: Even though you mapped 5433:5432, GeoServer is talking to PostGIS inside the Docker network. That means it uses the container's actual port, which is still 5432. Only use 5433 when you're connecting from outside Docker (like from your local terminal or IDE).

How the Port Mapping Works

5433:5432
8081:8080

• Left side = your machine (host)
• Right side = inside the container
• When containers talk to each other over the shared network, they always use the right side.
• When you talk to them from your browser or terminal, you use the left side.

That’s it. GeoServer UI: http://localhost:8081/geoserver PostGIS (from host): localhost:5433

Originally published at https://github.com.