# liferay/liferay-docker architecture

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

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

## Overview

##### Project Type and Purpose
- This is a DevOps tooling repository for building, testing, and orchestrating Liferay Docker images and related services.
- It comprises:
- A “build system” (shell scripts, GitHub Actions) to produce Docker images from templates.
- A “template library” of Dockerfiles and resources for each service (Liferay, DB, search, monitoring, etc.).
- Orchestration frameworks (narwhal, orca) offering docker-compose setups, Puppet modules, and deployment scripts.
- Release tooling to generate BOMs, run tests, and publish images/BOMs.

##### File Structure & Patterns
- Top‐level “build_*” and “_common” shell scripts invoke Docker builds, test harnesses, and release workflows.
- “templates/” contains subdirs for each image type—each is a Docker build context.
- “narwhal/” and “orca/” are two orchestration layers:
- narwhal: sample docker-compose demos, Puppet modules, CI templates, release‐builder, tang-server, etc.
- orca: configs, scripts, and templates to install multi-container environments via Docker/Puppet.
- “release/” holds scripts to generate BOMs, releases.json, tests for release logic.
- CI config in “.github/workflows” automates builds and releases.

##### Main Components & Their Roles
a. Build & CI Layer
- Shell scripts (build_*.sh, run_tests.sh) orchestrate:
- Docker build → images from “templates/…” contexts
- Unit/integration tests for images
- Release logic (BOM generation, versioning)
- GitHub Actions workflows call these scripts on push/tag.
b. Docker Image Library
- Templates per service:
- liferay-bundle, dxp, portal
- db, search, monitoring, backup, vault, caddy, squid, zabbix, job-runner, node-runner, jar-runner, batch
- Each template folder: Dockerfile + “resources/” with entrypoint scripts, configs.
c. Orchestration & Environment Provisioning
- narwhal:
- demo applications (docker-compose demos)
- Puppet modules to bootstrap servers (liferay, CI, DB, etc.)
- “templates/ci” and “templates/release-builder” for CI container definitions
- orca:
- Config YAMLs for environment definitions (demo, single_server)
- Scripts to validate, build, and install orca-managed stacks
- Templates for each service container in an orca-deployed cluster
d. Release & Publishing
- release/: scripts to assemble and publish release artifacts
- Generates BOM POMs, JSON artifacts, and pushes images to Docker Hub
e. Testing & Validation
- test/*.sh harnesses for each image type
- run_tests.sh aggregates all tests

##### Relationships & Data Flows
- Developers → commit to GitHub → triggers CI (GitHub Actions) → invokes build scripts
- Build scripts → use Docker CLI + template contexts → produce images → push to Docker Hub
- Release scripts → read images and metadata → generate BOMs and publish releases
- Orchestration layers (narwhal/orca) consume published images + Puppet modules → deploy demo or production stacks
- Monitoring & backup containers interact at runtime with Liferay and DB containers

##### Architectural Patterns & Principles
- Modular Docker build contexts: one template per service.
- Single‐responsibility containers (web, db, search, monitoring, backup).
- Shell‐script “pipeline” calling Docker + tests + release tasks.
- Declarative environment definitions (docker-compose + Puppet + YAML configs).
- Reuse via common scripts (“_common.sh”) and shared Puppet modules.

##### Technologies & Frameworks
- Docker, Docker Compose
- Bash shell scripts
- GitHub Actions (release.yml)
- Puppet (modules under narwhal/puppet)
- YAML config files (orca/configs)
- Docker Hub for image registry

##### Essential Elements
- Clear, self-explanatory labels on every component
- Callouts for key scripts (build_all_images.sh, generate_release_notes.sh, orca.sh)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & CI Layer
    subgraph "Build & CI Layer" 
        direction TB
        CI_Workflows["GitHub Actions\n(.github/workflows/release.yml)"]:::build
        Shell_Scripts["Shell Scripts\n(build_all_images.sh, build_*.sh,\n_common.sh, _liferay_common.sh,\n_release_common.sh, _test_common.sh)"]:::build
        run_tests["run_tests.sh\n(Test Aggregator)"]:::build
    end

    CI_Workflows -->|"triggers"| Shell_Scripts
    Shell_Scripts -->|"invokes"| run_tests

    click CI_Workflows "https://github.com/liferay/liferay-docker/blob/master/.github/workflows/release.yml"
    click Shell_Scripts "https://github.com/liferay/liferay-docker/blob/master//_common.sh"
    click Shell_Scripts "https://github.com/liferay/liferay-docker/blob/master//_liferay_common.sh"
    click Shell_Scripts "https://github.com/liferay/liferay-docker/blob/master//_release_common.sh"
    click Shell_Scripts "https://github.com/liferay/liferay-docker/blob/master//_test_common.sh"
    click Shell_Scripts "https://github.com/liferay/liferay-docker/blob/master//build_all_images.sh"

    %% Docker Template Library
    subgraph "Docker Template Library" 
        direction TB
        Templates["_common\n_jdk\nbase\nbatch\nbundle\ncaddy\njar-runner\njob-runner\nnode-runner\nnoop\nsquid\nzabbix-server\nzabbix-web\n_byoos"]:::tmpl
    end

    run_tests -->|"uses Docker contexts"| Templates

    click Templates "https://github.com/liferay/liferay-docker/tree/master//templates/_common"
    click Templates "https://github.com/liferay/liferay-docker/tree/master//templates/_jdk"
    click Templates "https://github.com/liferay/liferay-docker/tree/master//templates/base"
    click Templates "https://github.com/liferay/liferay-docker/tree/master//templates/batch"
    click Templates "https://github.com/liferay/liferay-docker/tree/master//templates/bundle"
    click Templates "https://github.com/liferay/liferay-docker/tree/master//templates/caddy"
    click Templates "https://github.com/liferay/liferay-docker/tree/master//templates/jar-runner"
    click Templates "https://github.com/liferay/liferay-docker/tree/master//templates/job-runner"
    click Templates "https://github.com/liferay/liferay-docker/tree/master//templates/node-runner"
    click Templates "https://github.com/liferay/liferay-docker/tree/master//templates/noop"
    click Templates "https://github.com/liferay/liferay-docker/tree/master//templates/squid"
    click Templates "https://github.com/liferay/liferay-docker/tree/master//templates/zabbix-server"
    click Templates "https://github.com/liferay/liferay-docker/tree/master//templates/zabbix-web"
    click Templates "https://github.com/liferay/liferay-docker/tree/master//templates/_byoos"

    %% Build & Push Images
    Build_Images["Docker Build\n→ Images"]:::build
    Templates -->|"build"| Build_Images
    Build_Images -->|"push"| Registry

    %% Registry
    Registry["Docker Hub\n(Image Registry)"]:::registry

    %% Release & Publishing
    subgraph "Release & Publishing"
        direction TB
        Release_Scripts["release/_*.sh\n(build_release.sh, clean.sh,\nrebuild_bom_files.sh,\nrebuild_releases_json.sh)"]:::release
        BOM_Templates["templates/*.pom.tpl"]:::release
        Release_Tests["test_*.sh"]:::release
    end

    Shell_Scripts -->|"calls"| Release_Scripts
    Release_Scripts -->|"generate BOMs"| BOM_Templates
    Release_Scripts -->|"run"| Release_Tests
    Release_Scripts -->|"publish artifacts"| Registry

    click Release_Scripts "https://github.com/liferay/liferay-docker/blob/master//release/_bom.sh"
    click Release_Scripts "https://github.com/liferay/liferay-docker/blob/master//release/_publishing.sh"
    click Release_Scripts "https://github.com/liferay/liferay-docker/blob/master//release/_releases_json.sh"
    click Release_Scripts "https://github.com/liferay/liferay-docker/blob/master//release/build_release.sh"
    click Release_Scripts "https://github.com/liferay/liferay-docker/blob/master//release/clean.sh"
    click Release_Scripts "https://github.com/liferay/liferay-docker/blob/master//release/rebuild_bom_files.sh"
    click Release_Scripts "https://github.com/liferay/liferay-docker/blob/master//release/rebuild_releases_json.sh"
    click BOM_Templates "https://github.com/liferay/liferay-docker/blob/master//release/templates/*.pom.tpl"
    click Release_Tests "https://github.com/liferay/liferay-docker/blob/master//release/test_bom.sh"
    click Release_Tests "https://github.com/liferay/liferay-docker/blob/master//release/test_ci.sh"

    %% Orchestration Layers
    subgraph "Orchestration & Provisioning"
        direction TB
        subgraph "narwhal" 
            direction TB
            Narw_Demos["compose_samples (docker-compose demos)"]:::orches
            Narw_Puppet["puppet (Puppetfile, manifests, modules)"]:::orches
            Narw_Templates["templates/ci, release-builder, tang-server"]:::orches
            Narw_Scripts["run_*.sh"]:::orches
        end
        subgraph "orca"
            direction TB
            Orca_Configs["configs/demo.yml, single_server.yml"]:::orches
            Orca_Scripts["_common.sh, build_services.sh,\ninstall_orca.sh, orca.sh, validate_environment.sh"]:::orches
            Orca_Templates["templates/liferay, db, backup,\nvault, web-server, etc."]:::orches
        end
    end

    Registry -->|"consumed by"| Narw_Demos
    Registry -->|"retrieves"| Orca_Scripts
    Narw_Scripts --> Narw_Puppet
    Orca_Scripts --> Orca_Configs
    Orca_Scripts --> Orca_Templates

    click Narw_Demos "https://github.com/liferay/liferay-docker/tree/master//narwhal/compose_samples/"
    click Narw_Puppet "https://github.com/liferay/liferay-docker/tree/master//narwhal/puppet/"
    click Narw_Templates "https://github.com/liferay/liferay-docker/tree/master//narwhal/templates/ci"
    click Narw_Templates "https://github.com/liferay/liferay-docker/tree/master//narwhal/templates/release-builder"
    click Narw_Templates "https://github.com/liferay/liferay-docker/tree/master//narwhal/templates/tang-server"
    click Narw_Scripts "https://github.com/liferay/liferay-docker/blob/master//narwhal/run_release_builder.sh"
    click Orca_Configs "https://github.com/liferay/liferay-docker/blob/master//orca/configs/demo.yml"
    click Orca_Configs "https://github.com/liferay/liferay-docker/blob/master//orca/configs/single_server.yml"
    click Orca_Scripts "https://github.com/liferay/liferay-docker/blob/master//orca/scripts/_common.sh"
    click Orca_Scripts "https://github.com/liferay/liferay-docker/blob/master//orca/scripts/build_services.sh"
    click Orca_Scripts "https://github.com/liferay/liferay-docker/blob/master//orca/scripts/install_orca.sh"
    click Orca_Scripts "https://github.com/liferay/liferay-docker/blob/master//orca/scripts/orca.sh"
    click Orca_Scripts "https://github.com/liferay/liferay-docker/blob/master//orca/scripts/validate_environment.sh"
    click Orca_Templates "https://github.com/liferay/liferay-docker/tree/master//orca/templates/"

    %% Runtime Stack
    subgraph "Runtime Stack" 
        direction TB
        Liferay["Liferay Container"]:::runtime
        Database["Database Container"]:::runtime
        Search["Search Container"]:::runtime
        Monitoring["Monitoring Container"]:::runtime
        Backup["Backup Container"]:::runtime
    end

    Narw_Demos -->|"deploy"| Liferay
    Orca_Scripts -->|"deploy"| Liferay
    Liferay --> Database
    Liferay --> Search
    Liferay --> Monitoring
    Liferay --> Backup

    %% Styles
    classDef build fill:#B3CDE0,stroke:#1F4E79,color:#000
    classDef tmpl fill:#C7E9B4,stroke:#2E7D32,color:#000
    classDef registry fill:#FFD87D,stroke:#BF360C,color:#000
    classDef release fill:#F4AAFF,stroke:#6A1B9A,color:#000
    classDef orches fill:#FFCC80,stroke:#E65100,color:#000
    classDef runtime fill:#D7CCC8,stroke:#4E342E,color:#000
```
