# nginx/docker-nginx architecture

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

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

## Overview

##### Project type and purpose
- This is the “official-image” repository for nginx on Docker Hub. It provides:
- Dockerfile templates for multiple base images (alpine, debian, slim, otel, perl)
- entrypoint scripts for container runtime configuration
- multi-architecture build and test harness
- CI/CD workflows to build, test, and publish nginx images

##### File structure
- Top-level directories:
- mainline/ and stable/ – different release channels, each containing per-variant Dockerfiles and entrypoint snippets
- modules/ – build recipes for dynamic modules
- entrypoint/ – scripts that run inside the container at startup
- .github/workflows/ – CI definitions (GitHub Actions)
- .test/ – integration tests invoking containers with various configs
- Root scripts (sync-awsecr.sh, update.sh) – automation for syncing images and updating library
- Patterns:
- Template-driven Dockerfile generation (generate-stackbrew-library.sh)
- Multi-arch build via both GitHub Actions and external Jenkins (badges in README)
- Separation of “build” (Dockerfiles, modules) vs “test” vs “publish”

##### README for additional insights
- Confirms multi-arch build status and channels (amd64, arm, s390x, etc.)
- Points to external docs repo for user instructions and Docker Hub page for usage

##### Main components
a. Source code repository (GitHub)
b. CI/CD pipelines
- GitHub Actions (ci.yml, sync.yml, f5_cla.yml)
- External Jenkins multi-arch pipelines
- Shell scripts (sync-awsecr.sh, update.sh)
c. Build engines
- Docker build on various base images and architectures
- modules build sub-system
d. Testing layer
- .test harness invoking built images against sample configs
e. Docker Hub / Registrierung
- Official nginx images with tags (stable, mainline, variants, arches)
f. Runtime container
- entrypoint scripts configuring nginx (IPv6, resolvers, worker tuning)

##### Relationships and interactions
- Developer pushes commits → triggers GitHub Actions
- GitHub Actions calls generate-stackbrew-library.sh, builds Dockerfiles per channel
- Actions and Jenkins build images on different architectures
- CI jobs invoke .test scripts pulling built images, running nginx with sample configs
- On success, images are pushed to Docker Hub and AWS ECR (via sync-awsecr.sh)
- At runtime, container uses entrypoint scripts to configure nginx before starting

##### Architectural patterns and principles
- Template and convention-over-configuration: one repo supports many variants
- Multi-stage and multi-arch builds driven by script generation
- Clear separation of build, test, and publish phases
- Modular entrypoint for container startup logic

##### Elements
- Clear labels: “GitHub Repo,” “GitHub Actions,” “Jenkins Multi-arch,” “Docker Hub,” “AWS ECR,” “.test Harness,” “Container Runtime”
- Rectangles for code repositories and scripts
- Clouds for CI services
- Containers for runtime

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Development Layer
    subgraph "Development" 
        direction TB
        GitHubRepo["GitHub Repo"]:::code
        Generate["generate-stackbrew-library.sh"]:::code
        SyncScript["sync-awsecr.sh"]:::code
        UpdateScript["update.sh"]:::code
    end

    %% CI/CD Layer
    subgraph "CI/CD" 
        direction TB
        GitHubActions["GitHub Actions"]:::ci
        CI_YML["ci.yml"]:::ci
        SYNC_YML["sync.yml"]:::ci
        F5CLA_YML["f5_cla.yml"]:::ci
        Jenkins["Jenkins Multi-arch"]:::ci
    end

    %% Build Layer
    subgraph "Build" 
        direction TB
        Mainline["mainline/ channel"]:::build
        Stable["stable/ channel"]:::build
        Templates["Template Dockerfiles"]:::build
        ModulesBuild["modules/ build subsystem"]:::build
        Images["Built Docker Images (multi-arch)"]:::build
    end

    %% Test Layer
    subgraph "Test Harness" 
        direction TB
        TestHarness[".test/ integration tests"]:::test
    end

    %% Registry Layer
    subgraph "Registry" 
        direction TB
        DockerHub["Docker Hub"]:::registry
        AWSECR["AWS ECR"]:::registry
    end

    %% Runtime Layer
    subgraph "Runtime" 
        direction TB
        Container["Container Runtime"]:::runtime
        subgraph "Entrypoint Scripts"
            direction TB
            S10["10-listen-on-ipv6-by-default.sh"]:::runtime
            S15["15-local-resolvers.envsh"]:::runtime
            S20["20-envsubst-on-templates.sh"]:::runtime
            S30["30-tune-worker-processes.sh"]:::runtime
            EntryPoint["docker-entrypoint.sh"]:::runtime
        end
        Nginx["nginx Process"]:::runtime
    end

    %% Connections
    GitHubRepo -->|push commits| GitHubActions
    GitHubRepo -->|runs| Generate
    GitHubRepo -->|runs| SyncScript
    GitHubRepo -->|runs| UpdateScript

    GitHubActions --> CI_YML
    GitHubActions --> SYNC_YML
    GitHubActions --> F5CLA_YML
    GitHubActions -->|triggers builds| Mainline
    GitHubActions -->|triggers builds| Stable
    Jenkins -->|builds arch images| Images

    Generate --> Templates
    Mainline --> Templates
    Stable --> Templates
    Templates --> Images
    ModulesBuild --> Images

    Images --> TestHarness
    TestHarness -->|on success| DockerHub
    DockerHub -->|sync| AWSECR
    SyncScript --> AWSECR

    DockerHub -->|pull image| Container
    Container --> S10
    S10 --> S15
    S15 --> S20
    S20 --> S30
    S30 --> EntryPoint
    EntryPoint --> Nginx

    %% Click Events
    click CI_YML "https://github.com/nginx/docker-nginx/blob/master/.github/workflows/ci.yml"
    click SYNC_YML "https://github.com/nginx/docker-nginx/blob/master/.github/workflows/sync.yml"
    click F5CLA_YML "https://github.com/nginx/docker-nginx/blob/master/.github/workflows/f5_cla.yml"
    click Generate "https://github.com/nginx/docker-nginx/blob/master/generate-stackbrew-library.sh"
    click SyncScript "https://github.com/nginx/docker-nginx/blob/master/sync-awsecr.sh"
    click UpdateScript "https://github.com/nginx/docker-nginx/blob/master/update.sh"
    click Mainline "https://github.com/nginx/docker-nginx/tree/master/mainline/"
    click Stable "https://github.com/nginx/docker-nginx/tree/master/stable/"
    click Templates "https://github.com/nginx/docker-nginx/blob/master/Dockerfile-alpine.template"
    click Templates "https://github.com/nginx/docker-nginx/blob/master/Dockerfile-alpine-slim.template"
    click Templates "https://github.com/nginx/docker-nginx/blob/master/Dockerfile-alpine-otel.template"
    click Templates "https://github.com/nginx/docker-nginx/blob/master/Dockerfile-alpine-perl.template"
    click Templates "https://github.com/nginx/docker-nginx/blob/master/Dockerfile-debian.template"
    click Templates "https://github.com/nginx/docker-nginx/blob/master/Dockerfile-debian-otel.template"
    click Templates "https://github.com/nginx/docker-nginx/blob/master/Dockerfile-debian-perl.template"
    click ModulesBuild "https://github.com/nginx/docker-nginx/tree/master/modules/"
    click TestHarness "https://github.com/nginx/docker-nginx/tree/master/.test/"
    click S10 "https://github.com/nginx/docker-nginx/blob/master/entrypoint/10-listen-on-ipv6-by-default.sh"
    click S15 "https://github.com/nginx/docker-nginx/blob/master/entrypoint/15-local-resolvers.envsh"
    click S20 "https://github.com/nginx/docker-nginx/blob/master/entrypoint/20-envsubst-on-templates.sh"
    click S30 "https://github.com/nginx/docker-nginx/blob/master/entrypoint/30-tune-worker-processes.sh"
    click EntryPoint "https://github.com/nginx/docker-nginx/blob/master/entrypoint/docker-entrypoint.sh"

    %% Styles
    classDef code fill:#cce5ff,stroke:#004085,color:#004085;
    classDef ci fill:#ffe5cc,stroke:#873800,color:#873800;
    classDef build fill:#e8ffe5,stroke:#155724,color:#155724;
    classDef test fill:#f5e5ff,stroke:#6f42c1,color:#6f42c1;
    classDef registry fill:#d4edda,stroke:#155724,color:#155724;
    classDef runtime fill:#e5ccff,stroke:#5a32a3,color:#5a32a3;
```
