# opf/openproject-docker-compose architecture

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

- Interactive diagram: https://gitdiagram.com/opf/openproject-docker-compose
- Repository: https://github.com/opf/openproject-docker-compose

## Overview

##### Project type and purpose
- This is not a source-code repository but a Docker-Compose installation kit for OpenProject (an open-source project management application).
- The goal is to spin up an OpenProject app stack (app server, database, reverse proxy) and provide “control plane” containers for backup and upgrade tasks.

##### File structure
- Top-level files:
- .env.example / .gitignore / README.md
- docker-compose.yml – main service definitions
- docker-compose.control.yml – definitions for control-plane containers (backup/upgrade)
- docker-compose.override.yml (user’s custom overrides, not in the repo)
- Directories:
- proxy/ – Dockerfile + Caddyfile.template for HTTPS reverse proxy
- control/ – Dockerfile + subfolders for backup and upgrade entrypoints and scripts
- Key patterns:
- A multi-container stack defined in Compose
- Two distinct “planes”: runtime (app + DB + proxy) and control (backup, upgrade)
- Use of named volumes for persistence, environment variables in .env

##### Extract architecture clues from README
- Runtime services:
- openproject (app)
- postgresql (database, persisted in compose_pgdata)
- proxy (Caddy server for TLS termination, optional / integrated)
- Control-plane services (launched via ‘docker-compose -f …control.yml run backup|upgrade’)
- Networks: likely a frontend (proxy ↔ openproject) and a backend (openproject ↔ postgres) network
- Volumes: opdata for uploads, pgdata for DB

##### Main components & interactions
a. Components:
1. OpenProject app container
2. PostgreSQL container
3. Caddy reverse-proxy container
4. Control-plane “backup” container
5. Control-plane “upgrade” container
6. Named Docker volumes: compose_opdata (assets), compose_pgdata (database)
7. Docker networks: front_net, back_net (names as in Compose)
8. .env file (holds environment variables injected into containers)

b. Relationships / Data flows:
- Caddy → OpenProject: HTTP(S) traffic forwarded from users to the app
- OpenProject → PostgreSQL: SQL queries over the backend network
- OpenProject → compose_opdata volume: reads/writes user-uploaded files
- PostgreSQL → compose_pgdata volume: persistent DB storage
- Control-plane containers:
- backup: mounts both volumes, runs dump scripts, writes backup artifacts (to host or another volume)
- upgrade: connects to DB and app’s code/config in container, runs upgrade scripts

##### Architectural patterns & principles
- Separation of concerns: runtime versus control plane
- Immutable infrastructure: containers built from specific images; no manual in-place modifications
- Infrastructure as code: full stack defined declaratively in docker-compose.yml files
- Sidecar/proxy pattern: Caddy as a sidecar for TLS termination

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    user["User"]:::user
    env[".env file"]:::env

    subgraph "Runtime Stack"
        direction TB
        proxy["Caddy Reverse-Proxy\n(Ports: 80/443)"]:::proxy
        openproj["OpenProject App\n(Port: 3000)"]:::app
        postgres["PostgreSQL DB\n(Port: 5432)"]:::db
        volOp[(compose_opdata)]:::volume
        volPg[(compose_pgdata)]:::volume
        netFront(("front_net")):::network
        netBack(("back_net")):::network
    end

    subgraph "Control Plane"
        direction TB
        backup["Backup Container"]:::control
        upgrade["Upgrade Container"]:::control
    end

    %% Connections - Runtime
    user -->|"HTTPS/HTTP"| proxy
    proxy -->|front_net| openproj
    openproj -->|back_net| postgres
    openproj -->|"mount"| volOp
    postgres -->|"mount"| volPg

    %% Connections - Control Plane
    backup -->|"access volumes"| volOp
    backup -->|"access volumes"| volPg
    upgrade -->|"access app code"| openproj
    upgrade -->|"access DB"| postgres

    %% Env Injection
    env --> proxy
    env --> openproj
    env --> postgres
    env --> backup
    env --> upgrade

    %% Click Events
    click openproj "https://github.com/opf/openproject-docker-compose/blob/stable/16/docker-compose.yml"
    click postgres "https://github.com/opf/openproject-docker-compose/blob/stable/16/docker-compose.yml"
    click proxy "https://github.com/opf/openproject-docker-compose/tree/stable/16/proxy/Dockerfile"
    click backup "https://github.com/opf/openproject-docker-compose/blob/stable/16/control/backup/entrypoint.sh"
    click upgrade "https://github.com/opf/openproject-docker-compose/blob/stable/16/control/upgrade/entrypoint.sh"
    click volOp "https://github.com/opf/openproject-docker-compose/blob/stable/16/docker-compose.yml"
    click netFront "https://github.com/opf/openproject-docker-compose/blob/stable/16/docker-compose.yml"
    click env "https://github.com/opf/openproject-docker-compose/blob/stable/16/.env.example"

    %% Styles
    classDef user fill:#e3f2fd,stroke:#90caf9,stroke-width:2px;
    classDef app fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef proxy fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef db fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef control fill:#c8e6c9,stroke:#43a047,stroke-width:2px;
    classDef volume fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px;
    classDef network fill:#e1bee7,stroke:#8e24aa,stroke-width:2px;
    classDef env fill:#f5f5f5,stroke:#9e9e9e,stroke-width:2px;
```
