# georchestra/docker architecture

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

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

## Overview

1. This repository is not the geOrchestra application code itself; it is the Docker-based orchestration layer for a full geOrchestra SDI stack. Its main job is to define which services run together, how they connect, what data they persist, and how the platform is exposed locally or in production-like environments.

2. The center of the repo is the Compose topology: `docker-compose.yml` defines the core geOrchestra stack, while `docker-compose.override.yml` and the extra compose files add optional or auxiliary capabilities. The README explicitly treats these files as the architectural contract for service composition, networking, and volume wiring.

3. The primary ingress path is a reverse-proxy/front door based on Caddy in `resources/caddy`. External browser traffic comes in through the public FQDN (default `georchestra-127-0-0-1.nip.io`), terminates TLS at Caddy, and is then routed to internal geOrchestra services. Caddy can use an internal cert for local dev or a real certificate from `resources/ssl`.

4. The core application boundary is the geOrchestra platform itself: a set of containerized webapps and backend services such as the security proxy and other geOrchestra modules. The README highlights that the base composition includes “all geOrchestra modules,” with services linked through Docker networking rather than exposed directly.

5. Identity and access are backed by LDAP and a database layer. The repo includes dedicated environment files for LDAP and multiple databases, which indicates that authentication/authorization and directory data are separated from the application containers. The security proxy is a key integration point between incoming requests and those identity services.

6. Search/indexing and analytics are handled by Elasticsearch, with an optional Kibana stack configured under `resources/kibana`. The README notes that Elasticsearch currently has no persistent volume in this composition, so indexes are ephemeral unless changed. Kibana is optional and is integrated into the GeoNetwork admin UI for dashboards/statistics.

7. Messaging and background interaction are present through RabbitMQ, with a dedicated `.envs-rabbitmq` file. While the README doesn’t spell out every consumer, this is a clear boundary for async communication between modules that need queue-based integration instead of direct synchronous calls.

8. Data management is split between application state and shared geodata. A named GeoServer data volume (`geoserver_geodata`) is exposed for file upload via SSH/rsync, and those files are mounted into the GeoServer container at runtime. This makes geodata a distinct storage plane from the container images and application configs.

9. Email is intentionally trapped inside the stack for development and QA. The override composition adds SMTP and webmail services so platform-generated emails, such as password reset messages, are delivered to a local mailbox rather than the public internet. That creates a closed-loop outbound mail path for testing.

10. Optional modules are separated into additive compose overlays: `docker-compose.gwc.yml` for a standalone GeoWebCache and `docker-compose.atlas.yml` for the Atlas module. The README explicitly says these are not part of the default “core” stack, so diagram them as optional branches rather than always-on dependencies.

11. Configuration is split between env files, the `config/` directory, and a `secrets/` directory. The env files are grouped by concern (`common`, `database`, `hosts`, `ldap`, `rabbitmq`, `elastic`), while `secrets/slapd_password.txt` shows that some credentials are meant to be injected from files rather than embedded in compose definitions.

12. The `resources/` directory holds supporting runtime assets rather than application code: Caddy config, Kibana config, static files, and SSL material. This repo therefore has a clear boundary between infrastructure configuration and the actual geOrchestra software images, which are pulled from Docker Hub and built upstream.

13. For developers, the repo is designed to be combined with the main geOrchestra source tree and rebuilt images from that codebase. The provided scripts (`run.sh`, `run-datafeeder-gmail.sh`) and README instructions show that this repo is primarily for local orchestration, debugging, and deployment validation, not for implementing business logic.

14. In an architecture diagram, the most important flows are: browser → Caddy/TLS → security proxy / geOrchestra webapps; webapps → LDAP/database/Elasticsearch/RabbitMQ; GeoServer ↔ shared geodata volume; platform → local SMTP/webmail; and optional Kibana/GeoWebCache/Atlas added through separate compose overlays.

Main entry points: [`docker-compose.yml`](https://github.com/georchestra/docker/blob/master/docker-compose.yml) (Core Compose), [`docker-compose.override.yml`](https://github.com/georchestra/docker/blob/master/docker-compose.override.yml) (Override), [`resources`](https://github.com/georchestra/docker/tree/master/resources) (Resources), [`resources/caddy/etc/Caddyfile`](https://github.com/georchestra/docker/tree/master/resources/caddy/etc/Caddyfile) (Caddy Front Door)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_orchestration["Orchestration"]
  node_node_compose_core["Core Compose<br/>compose stack<br/>[docker-compose.yml]"]
  node_node_compose_override["Override<br/>compose overlay"]
  node_node_run_sh["Run Script<br/>launcher script<br/>[run.sh]"]
  node_node_run_datafeeder["Mail Run Script<br/>launcher script"]
end

subgraph group_group_runtime["Runtime Stack"]
  node_node_caddy["Caddy Front Door<br/>reverse proxy"]
  node_node_georchestra["geOrchestra Apps<br/>webapp platform<br/>[docker-compose.yml]"]
  node_node_security_proxy["Security Proxy<br/>auth gateway<br/>[docker-compose.yml]"]
  node_node_ldap[("LDAP<br/>identity directory<br/>[.envs-ldap]")]
  node_node_database[("Database<br/>relational store")]
  node_node_elasticsearch[("Elasticsearch<br/>search index<br/>[.envs-elastic]")]
  node_node_rabbitmq["RabbitMQ<br/>message broker<br/>[.envs-rabbitmq]"]
  node_node_geoserver["GeoServer<br/>map service<br/>[docker-compose.yml]"]
  node_node_geodata[("Geodata Volume<br/>shared data<br/>[docker-compose.yml]")]
  node_node_smtp["Local SMTP<br/>mail sink"]
  node_node_webmail["Webmail<br/>mail UI"]
end

subgraph group_group_optional["Optional Add-ons"]
  node_node_kibana["Kibana<br/>analytics ui<br/>[kibana.yml]"]
  node_node_gwc["GeoWebCache<br/>tile cache"]
  node_node_atlas["Atlas<br/>optional module"]
end

subgraph group_group_support["Support Assets"]
  node_node_config["Config Files<br/>runtime config"]
  node_node_secrets["Secrets<br/>secret files<br/>[slapd_password.txt]"]
  node_node_resources["Resources<br/>support assets"]
end

node_node_run_sh -->|"starts"| node_node_compose_core
node_node_run_datafeeder -->|"starts"| node_node_compose_override
node_node_compose_core -->|"includes"| node_node_caddy
node_node_compose_core -->|"includes"| node_node_georchestra
node_node_compose_core -->|"includes"| node_node_security_proxy
node_node_compose_core -->|"includes"| node_node_geoserver
node_node_compose_core -->|"connects to"| node_node_ldap
node_node_compose_core -->|"connects to"| node_node_database
node_node_compose_core -->|"connects to"| node_node_elasticsearch
node_node_compose_core -->|"connects to"| node_node_rabbitmq
node_node_compose_core -->|"reads"| node_node_config
node_node_compose_core -->|"reads"| node_node_secrets
node_node_compose_core -->|"mounts"| node_node_resources
node_node_caddy -->|"routes to"| node_node_security_proxy
node_node_security_proxy -->|"authenticates against"| node_node_ldap
node_node_georchestra -->|"persists to"| node_node_database
node_node_georchestra -->|"indexes in"| node_node_elasticsearch
node_node_georchestra -->|"publishes to"| node_node_rabbitmq
node_node_geoserver -->|"mounts"| node_node_geodata
node_node_georchestra -->|"sends mail to"| node_node_smtp
node_node_smtp -->|"delivers to"| node_node_webmail
node_node_compose_override -->|"adds"| node_node_smtp
node_node_compose_override -->|"adds"| node_node_webmail
node_node_compose_core -.->|"optionally extends"| node_node_kibana
node_node_compose_core -.->|"optionally extends"| node_node_gwc
node_node_compose_core -.->|"optionally extends"| node_node_atlas
node_node_resources -->|"provides config"| node_node_caddy
node_node_resources -->|"provides config"| node_node_kibana

click node_node_compose_core "https://github.com/georchestra/docker/blob/master/docker-compose.yml"
click node_node_compose_override "https://github.com/georchestra/docker/blob/master/docker-compose.override.yml"
click node_node_run_sh "https://github.com/georchestra/docker/blob/master/run.sh"
click node_node_run_datafeeder "https://github.com/georchestra/docker/blob/master/run-datafeeder-gmail.sh"
click node_node_caddy "https://github.com/georchestra/docker/tree/master/resources/caddy/etc/Caddyfile"
click node_node_georchestra "https://github.com/georchestra/docker/blob/master/docker-compose.yml"
click node_node_security_proxy "https://github.com/georchestra/docker/blob/master/docker-compose.yml"
click node_node_ldap "https://github.com/georchestra/docker/blob/master/.envs-ldap"
click node_node_database "https://github.com/georchestra/docker/blob/master/.envs-database-georchestra"
click node_node_elasticsearch "https://github.com/georchestra/docker/blob/master/.envs-elastic"
click node_node_rabbitmq "https://github.com/georchestra/docker/blob/master/.envs-rabbitmq"
click node_node_geoserver "https://github.com/georchestra/docker/blob/master/docker-compose.yml"
click node_node_geodata "https://github.com/georchestra/docker/blob/master/docker-compose.yml"
click node_node_smtp "https://github.com/georchestra/docker/blob/master/docker-compose.override.yml"
click node_node_webmail "https://github.com/georchestra/docker/blob/master/docker-compose.override.yml"
click node_node_kibana "https://github.com/georchestra/docker/blob/master/resources/kibana/kibana.yml"
click node_node_gwc "https://github.com/georchestra/docker/blob/master/docker-compose.gwc.yml"
click node_node_atlas "https://github.com/georchestra/docker/blob/master/docker-compose.atlas.yml"
click node_node_config "https://github.com/georchestra/docker/tree/master/config"
click node_node_secrets "https://github.com/georchestra/docker/blob/master/secrets/slapd_password.txt"
click node_node_resources "https://github.com/georchestra/docker/tree/master/resources"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_compose_core,node_node_compose_override,node_node_run_sh,node_node_run_datafeeder toneBlue
class node_node_caddy,node_node_georchestra,node_node_security_proxy,node_node_ldap,node_node_database,node_node_elasticsearch,node_node_rabbitmq,node_node_geoserver,node_node_geodata,node_node_smtp,node_node_webmail toneAmber
class node_node_kibana,node_node_gwc,node_node_atlas toneMint
class node_node_config,node_node_secrets,node_node_resources toneRose
```

## Components

### Orchestration

Compose files and scripts that define how the stack is assembled and run.

- [Core Compose](https://github.com/georchestra/docker/blob/master/docker-compose.yml): compose stack · Primary service topology for the geOrchestra stack. · `docker-compose.yml`
- [Override](https://github.com/georchestra/docker/blob/master/docker-compose.override.yml): compose overlay · Local/dev overrides and auxiliary services. · `docker-compose.override.yml`
- [Run Script](https://github.com/georchestra/docker/blob/master/run.sh): launcher script · Entry point for bringing up the stack in a standard local workflow. · `run.sh`
- [Mail Run Script](https://github.com/georchestra/docker/blob/master/run-datafeeder-gmail.sh): launcher script · Specialized run script for the datafeeder/gmail scenario. · `run-datafeeder-gmail.sh`

### Runtime Stack

Core platform services and shared backend dependencies.

- [Caddy Front Door](https://github.com/georchestra/docker/tree/master/resources/caddy/etc/Caddyfile): reverse proxy · Public ingress, TLS termination, and request routing to internal services. · `resources/caddy/etc/Caddyfile`
- [geOrchestra Apps](https://github.com/georchestra/docker/blob/master/docker-compose.yml): webapp platform · Core containerized geOrchestra modules served behind the proxy. · `docker-compose.yml`
- [Security Proxy](https://github.com/georchestra/docker/blob/master/docker-compose.yml): auth gateway · Request boundary that mediates access to protected services. · `docker-compose.yml`
- [LDAP](https://github.com/georchestra/docker/blob/master/.envs-ldap): identity directory · User and group directory backing authentication and authorization. · `.envs-ldap`
- [Database](https://github.com/georchestra/docker/blob/master/.envs-database-georchestra): relational store · Persistent application database layer for geOrchestra services. · `.envs-database-georchestra`
- [Elasticsearch](https://github.com/georchestra/docker/blob/master/.envs-elastic): search index · Indexing and search backend used by platform services. · `.envs-elastic`
- [RabbitMQ](https://github.com/georchestra/docker/blob/master/.envs-rabbitmq): message broker · Async messaging boundary for background and cross-service interaction. · `.envs-rabbitmq`
- [GeoServer](https://github.com/georchestra/docker/blob/master/docker-compose.yml): map service · Spatial data service with mounted shared geodata. · `docker-compose.yml`
- [Geodata Volume](https://github.com/georchestra/docker/blob/master/docker-compose.yml): shared data · Named volume holding GeoServer data uploaded via SSH/rsync. · `docker-compose.yml`
- [Local SMTP](https://github.com/georchestra/docker/blob/master/docker-compose.override.yml): mail sink · Closed-loop mail delivery for development and QA. · `docker-compose.override.yml`
- [Webmail](https://github.com/georchestra/docker/blob/master/docker-compose.override.yml): mail UI · Mailbox interface for inspecting platform-generated emails locally. · `docker-compose.override.yml`

### Optional Add-ons

Overlay stacks enabled only for specific use cases.

- [Kibana](https://github.com/georchestra/docker/blob/master/resources/kibana/kibana.yml): analytics ui · Optional dashboards and statistics UI for Elasticsearch data. · `resources/kibana/kibana.yml`
- [GeoWebCache](https://github.com/georchestra/docker/blob/master/docker-compose.gwc.yml): tile cache · Optional standalone cache layer enabled through a separate compose file. · `docker-compose.gwc.yml`
- [Atlas](https://github.com/georchestra/docker/blob/master/docker-compose.atlas.yml): optional module · Optional geOrchestra add-on enabled through a dedicated compose overlay. · `docker-compose.atlas.yml`

### Support Assets

Runtime configuration, secrets, and static assets used by containers.

- [Config Files](https://github.com/georchestra/docker/tree/master/config): runtime config · Environment files and config directory used to parameterize services. · `config`
- [Secrets](https://github.com/georchestra/docker/blob/master/secrets/slapd_password.txt): secret files · File-injected credentials such as the LDAP password. · `secrets/slapd_password.txt`
- [Resources](https://github.com/georchestra/docker/tree/master/resources): support assets · Caddy, Kibana, SSL, and static assets mounted into containers. · `resources`

## Connections

- Run Script → Core Compose: starts · Standard startup path invokes the core compose stack.
- Mail Run Script → Override: starts · Specialized workflow brings up the datafeeder/mail override.
- Core Compose → Caddy Front Door: includes · Defines the public ingress proxy as part of the stack.
- Core Compose → geOrchestra Apps: includes · Defines the main geOrchestra application services.
- Core Compose → Security Proxy: includes · Includes the security boundary in front of protected services.
- Core Compose → GeoServer: includes · Runs GeoServer as a core service.
- Core Compose → LDAP: connects to · Uses LDAP for identity and directory lookups.
- Core Compose → Database: connects to · Uses the relational database for persistent state.
- Core Compose → Elasticsearch: connects to · Uses Elasticsearch for search and indexing.
- Core Compose → RabbitMQ: connects to · Uses RabbitMQ for asynchronous integration.
- Core Compose → Config Files: reads · Loads environment and config values from repo-managed files.
- Core Compose → Secrets: reads · Injects sensitive values from secret files.
- Core Compose → Resources: mounts · Mounts supporting runtime assets into containers.
- Caddy Front Door → Security Proxy: routes to · Forwards browser traffic to internal application gateways.
- Security Proxy → LDAP: authenticates against · Checks user identity and authorization data.
- geOrchestra Apps → Database: persists to · Stores application state in the database layer.
- geOrchestra Apps → Elasticsearch: indexes in · Writes searchable content and metadata.
- geOrchestra Apps → RabbitMQ: publishes to · Uses queues for background and cross-service work.
- GeoServer → Geodata Volume: mounts · Reads and writes shared geodata from the named volume.
- geOrchestra Apps → Local SMTP: sends mail to · Platform-generated mail is trapped in the local SMTP service.
- Local SMTP → Webmail: delivers to · Mail can be inspected through the local webmail UI.
- Override → Local SMTP: adds · Override composition enables local mail services.
- Override → Webmail: adds · Override composition enables mailbox inspection UI.
- Core Compose → Kibana: optionally extends · Kibana is an optional analytics companion for Elasticsearch.
- Core Compose → GeoWebCache: optionally extends · GeoWebCache is enabled through a separate overlay.
- Core Compose → Atlas: optionally extends · Atlas is enabled through a separate overlay.
- Resources → Caddy Front Door: provides config · Supplies Caddy configuration and TLS material.
- Resources → Kibana: provides config · Supplies Kibana runtime configuration.
