# kartoza/docker-geoserver architecture

> Architecture diagram of the GitHub repository kartoza/docker-geoserver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kartoza/docker-geoserver
- Repository: https://github.com/kartoza/docker-geoserver

## Overview

##### Project type and purpose
- This is a Docker‐based deployment project (“Kartoza docker-geoserver”) that packages GeoServer (a Java/Tomcat GIS server) with configurable extensions and optional clustering using PostGIS and ActiveMQ.
- Its purpose is to provide a production-ready GeoServer container, backed by PostGIS, with environment variables and mountable configs to customize behavior, enable extensions, clustering, SSL, reverse proxy, backups, etc.

##### File structure
- Top-level Docker assets:
- Dockerfile, docker-compose.yml variants, .env, .dockerignore
- build_data/ – default GeoServer and Tomcat configs, plugins lists, SQL scripts, XML templates
- scripts/ – container entrypoint, setup and helper shell scripts
- clustering/ – example Dockerfiles and compose files for JMS/ActiveMQ clustering
- sites-enabled/nginx.conf – sample Nginx reverse-proxy config
- CI/CD:
- .github/workflows/ – build and deploy-image pipelines
- Scenario tests:
- scenario_tests/ – end-to-end tests using docker-compose for various features (backup, clustering, disk quota, JNDI, etc.)
- Documentation:
- docs/ – static HTML docs for usage, environment variables, Kubernetes, mounting configs
- Resources & overlays for custom file overlays

##### README for additional insights
- Describes main runtime components: GeoServer on Tomcat, PostGIS backend, optional Nginx or Kubernetes front ends, JMS clustering plugin with ActiveMQ broker.
- Describes how environment variables drive plugin activation, disk quota, SSL, JNDI, proxy settings, context root.
- Mentions Helm charts for Kubernetes, CI scanning with Trivy, upgrade scripts.

##### Elements
- Clear labels: container names (geoserver, db, broker), protocol (HTTP, JDBC, JMS)
- Containers (rectangles in blue)

##### Detail
- Config files in build_data vs override mount points
- How environment variables (from .env) map to container startup behavior
- Scenario tests as a separate component that spins up compose stacks and connects to the services
- Don’t overcrowd: group similar items (all .yml files under clustering as “clustering examples”)

When drawing, start with a high‐level overview (User → Proxy → GeoServer → DB) then drill into container internals (Tomcat, build_data, scripts, plugins, env vars) as needed. Use layering: Network layer, Container layer, File/Volume layer, CI/CD layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Network Layer
    subgraph "Network Layer"
        direction TB
        User["User / Client"]:::external
        User -->|"HTTP/HTTPS"| Nginx["Nginx Reverse Proxy"]:::container
    end

    %% Container Layer
    subgraph "Container Layer"
        direction TB
        Nginx --> GeoServer["GeoServer Container"]:::container
        GeoServer -->|"JDBC"| PostGIS["PostGIS Database"]:::db
        GeoServer -->|"JMS"| ActiveMQ["ActiveMQ Broker"]:::broker
    end

    %% Volume Layer
    subgraph "Volume / Config Layer"
        direction TB
        Settings["/settings (override configs)"]:::volume
        DataDir["/data (persistent data)"]:::volume
        Fonts["/opt/fonts"]:::volume
        GeoServer --> Settings
        GeoServer --> DataDir
        GeoServer --> Fonts
    end

    %% CI/CD Layer
    subgraph "CI/CD Pipeline" 
        direction TB
        GitRepo["Git Repository"]:::external
        Actions["GitHub Actions"]:::cicd
        DockerHub["DockerHub Registry"]:::external
        Scenario["Scenario Tests"]:::cicd
        GitRepo --> Actions
        Actions -->|"build & deploy"| DockerHub
        Actions -->|"trigger tests"| Scenario
    end

    %% Kubernetes Deployment
    subgraph "Kubernetes Cluster"
        direction TB
        Helm["Helm Charts"]:::k8s
        Kubernetes["K8s Environment"]:::k8s
        DockerHub --> Helm
        Helm --> Kubernetes
    end

    %% Click Events: Docker Assets
    click Dockerfile "https://github.com/kartoza/docker-geoserver/tree/develop/Dockerfile"
    click EnvFile "https://github.com/kartoza/docker-geoserver/blob/develop/.env"
    click Dockerignore "https://github.com/kartoza/docker-geoserver/blob/develop/.dockerignore"
    click DCYml "https://github.com/kartoza/docker-geoserver/blob/develop/docker-compose.yml"
    click DCBuild "https://github.com/kartoza/docker-geoserver/blob/develop/docker-compose-build.yml"
    click DCNginx "https://github.com/kartoza/docker-geoserver/blob/develop/docker-compose-nginx.yml"
    click BuildData "https://github.com/kartoza/docker-geoserver/tree/develop/build_data/"

    %% Click Events: GeoServer Startup Scripts
    click Entry "https://github.com/kartoza/docker-geoserver/blob/develop/scripts/entrypoint.sh"
    click Setup "https://github.com/kartoza/docker-geoserver/blob/develop/scripts/setup.sh"
    click Start "https://github.com/kartoza/docker-geoserver/blob/develop/scripts/start.sh"
    click EnvData "https://github.com/kartoza/docker-geoserver/blob/develop/scripts/env-data.sh"
    click Functions "https://github.com/kartoza/docker-geoserver/blob/develop/scripts/functions.sh"
    click UpdatePw "https://github.com/kartoza/docker-geoserver/blob/develop/scripts/update_passwords.sh"

    %% Click Events: PostGIS Service Definitions
    click DCYml "https://github.com/kartoza/docker-geoserver/blob/develop/docker-compose.yml"
    click DCBuild "https://github.com/kartoza/docker-geoserver/blob/develop/docker-compose-build.yml"
    click DCNginx "https://github.com/kartoza/docker-geoserver/blob/develop/docker-compose-nginx.yml"

    %% Click Events: ActiveMQ Clustering
    click AMQDockerfile "https://github.com/kartoza/docker-geoserver/tree/develop/clustering/activemq-docker/Dockerfile"
    click AMQConfig "https://github.com/kartoza/docker-geoserver/blob/develop/clustering/activemq-docker/activemq.xml"
    click AMQSetup "https://github.com/kartoza/docker-geoserver/blob/develop/clustering/activemq-docker/setup-jars.sh"
    click CCMQ "https://github.com/kartoza/docker-geoserver/blob/develop/clustering/docker-compose.yml"
    click CCMQExt "https://github.com/kartoza/docker-geoserver/blob/develop/clustering/docker-compose-external.yml"

    %% Click Events: Clustering Config
    click ClusterProps "https://github.com/kartoza/docker-geoserver/blob/develop/build_data/cluster.properties"
    click Hazelcast "https://github.com/kartoza/docker-geoserver/tree/develop/build_data/hazelcast_cluster/"

    %% Click Events: Nginx Config
    click NginxConf "https://github.com/kartoza/docker-geoserver/blob/develop/sites-enabled/nginx.conf"

    %% Click Events: CI/CD Workflows
    click BuildWorkflow "https://github.com/kartoza/docker-geoserver/blob/develop/.github/workflows/build-latest.yaml"
    click DeployWorkflow "https://github.com/kartoza/docker-geoserver/blob/develop/.github/workflows/deploy-image.yaml"

    %% Click Events: Scenario Tests
    click ScenarioTests "https://github.com/kartoza/docker-geoserver/tree/develop/scenario_tests/"

    %% Click Events: Documentation
    click Docs "https://github.com/kartoza/docker-geoserver/tree/develop/docs/"

    %% Click Events: Custom Overlays
    click Overlays "https://github.com/kartoza/docker-geoserver/tree/develop/resources/overlays/"

    %% Click Events: Upgrade Script
    click Upgrade "https://github.com/kartoza/docker-geoserver/blob/develop/upgrade_geoserver_version.sh"

    %% Styles
    classDef container fill:#cce5ff,stroke:#339,stroke-width:2px
    classDef db fill:#d4edda,stroke:#396,stroke-width:2px
    classDef broker fill:#d4edda,stroke:#396,stroke-width:2px
    classDef volume fill:#fff3cd,stroke:#cc9900,stroke-width:2px
    classDef cicd fill:#f8d7da,stroke:#d63333,stroke-width:2px
    classDef k8s fill:#e2e3e5,stroke:#6c757d,stroke-width:2px
    classDef external fill:#f1f1f1,stroke:#bbb,stroke-width:2px
```
