# nginxinc/nginx-basics-workshops architecture

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

- Interactive diagram: https://gitdiagram.com/nginxinc/nginx-basics-workshops
- Repository: https://github.com/nginxinc/nginx-basics-workshops

## Overview

##### Project Type and Purpose
- This repository is a hands-on **workshop/lab** environment for teaching NGINX (both OSS and Plus) using **Docker Compose**.
- It is **not** a typical full-stack web application but a **training topology**: NGINX front-ends, backend web servers, and monitoring tools (Prometheus/Grafana) orchestrated via Docker.
- The README and lab folders (OSS/labs and Plus/labs) clearly describe sequential exercises (lab0 → lab7) to build, configure, and extend NGINX configurations.

##### File Structure Analysis
- Top-level: README, CONTRIBUTING, LICENSE, media assets.
- Two parallel lab trees: `OSS/labs` and `Plus/labs`, each containing subfolders `lab0`–`lab7`.
- Each lab folder has a `docker-compose.yml` and a container build context (`nginx-oss` or `nginx-plus`).
- Within each NGINX build context you find `Dockerfile`, `/etc/nginx` configs, `/usr/share/nginx/html` sample pages, SSL artifacts, include files, etc.
- Monitoring labs add Prometheus configs and sometimes Grafana.
- Older (`old/`) directories show legacy examples (API gateway, caching), but the active path is under `OSS/labs` and `Plus/labs`.

##### Key README Insights
- Topology: one NGINX proxy/load-balancer, three backend web servers, Prometheus, Grafana.
- Containers:
- `nginx-oss` or `nginx-plus` – the front-end
- `web1`, `web2`, `web3` – simple NGINX demo servers
- `prometheus`, `grafana` – monitoring
- Docker network: bridged, internal DNS (127.0.0.11) for container name resolution.
- Exercises demonstrate: HTTP proxy, SSL termination, load balancing, logging, rate limiting, API management, metrics scraping.

##### Main Components
a. **User/Client (Browser, CLI Tools)**
b. **Docker Host** (the developer laptop/VM running Docker)
c. **Docker Network** (bridge with DNS)
d. **Front-end Proxy** – NGINX OSS or NGINX Plus container
e. **Backend Web Servers** – containers `web1`, `web2`, `web3`
f. **Monitoring Stack** – Prometheus (scrape targets), Grafana (visualization)
g. **External Services** – optional (e.g., external DNS resolution, certificate authority)

##### Component Relationships & Interactions
- Client → (HTTP/HTTPS) → NGINX
- NGINX → (upstream load balancing) → web1/web2/web3
- NGINX → (exported metrics endpoint) → Prometheus
- Prometheus → (data storage + query) → Grafana
- (In TLS labs) Client → NGINX terminates SSL → unencrypted upstream
- (In API-gateway labs) NGINX applies JWT auth, rate limits, proxy_pass to API backends.

##### Architectural Patterns & Design Principles
- **Edge Proxy Pattern**: NGINX as a reverse proxy/load-balancer at the edge.
- **Service Discovery**: Docker DNS internally resolves container names.
- **Separation of Concerns**: front-end proxy vs. backend web servers vs. monitoring.
- **Immutable Infrastructure**: containers are built with specific Dockerfiles and configuration included at build time.
- **Incremental Complexity**: each lab layer adds features (SSL, caching, monitoring, API management).

##### Technologies & Frameworks
- Docker & Docker Compose for orchestration.
- NGINX OSS (Alpine) and NGINX Plus (Debian) images.
- NGINX configuration includes `conf.d/`, `includes/`, SSL assets.
- Prometheus (YAML scrape config) and Grafana (dashboard container).
- Sample web server images based on `nginxinc/ingress-demo`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client (Browser/CLI)"]

    subgraph "Docker Host"
        subgraph "Docker Network" 
            style Docker_Network fill:#f0f0f0,stroke:#666,stroke-width:1px
        end
        subgraph "Containers"
            ProxyOSS["NGINX OSS Proxy\\nPorts: 80/443"]:::proxy
            ProxyPlus["NGINX Plus Proxy\\nPorts: 80/443"]:::proxy
            subgraph "Backend Web Servers"
                web1["web1"]:::backend
                web2["web2"]:::backend
                web3["web3"]:::backend
            end
            Prometheus["Prometheus\\nPort: 9090"]:::monitor
            TSDB[(TSDB)]:::monitor
            Grafana["Grafana UI\\nPort: 3000"]:::monitor
        end
    end

    Client -->|HTTP/HTTPS| ProxyOSS
    Client -->|HTTP/HTTPS| ProxyPlus

    ProxyOSS -->|load balances| web1
    ProxyOSS -->|load balances| web2
    ProxyOSS -->|load balances| web3

    ProxyPlus -->|load balances| web1
    ProxyPlus -->|load balances| web2
    ProxyPlus -->|load balances| web3

    ProxyOSS -->|export metrics| Prometheus
    web1 -->|metrics scrape| Prometheus
    web2 -->|metrics scrape| Prometheus
    web3 -->|metrics scrape| Prometheus

    Prometheus --> TSDB
    Grafana -->|queries| Prometheus

    classDef proxy fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef monitor fill:#FFA500,stroke:#000,stroke-width:1px

    click ProxyOSS "https://github.com/nginxinc/nginx-basics-workshops/tree/master/OSS/labs/lab1/nginx-oss"
    click ProxyOSS "https://github.com/nginxinc/nginx-basics-workshops/tree/master/OSS/labs/lab1/nginx-oss/Dockerfile"
    click ProxyOSS "https://github.com/nginxinc/nginx-basics-workshops/blob/master/OSS/labs/lab1/nginx-oss/etc/nginx/nginx.conf"
    click ProxyOSS "https://github.com/nginxinc/nginx-basics-workshops/blob/master/OSS/labs/lab1/nginx-oss/etc/nginx/conf.d/stub_status.conf"

    click ProxyPlus "https://github.com/nginxinc/nginx-basics-workshops/tree/master/Plus/labs/lab5/nginx-plus"
    click ProxyPlus "https://github.com/nginxinc/nginx-basics-workshops/tree/master/Plus/labs/lab5/nginx-plus/Dockerfile"
    click ProxyPlus "https://github.com/nginxinc/nginx-basics-workshops/blob/master/Plus/labs/lab5/nginx-plus/etc/nginx/nginx.conf"
    click ProxyPlus "https://github.com/nginxinc/nginx-basics-workshops/tree/master/Plus/labs/lab5/nginx-plus/etc/nginx/conf.d/"

    click web1 "https://github.com/nginxinc/nginx-basics-workshops/tree/master/OSS/labs/lab2/nginx-oss/usr/share/nginx/html/"
    click web1 "https://github.com/nginxinc/nginx-basics-workshops/tree/master/Plus/labs/lab2/nginx-plus/usr/share/nginx/html/"
    click web2 "https://github.com/nginxinc/nginx-basics-workshops/tree/master/OSS/labs/lab2/nginx-oss/usr/share/nginx/html/"
    click web2 "https://github.com/nginxinc/nginx-basics-workshops/tree/master/Plus/labs/lab2/nginx-plus/usr/share/nginx/html/"
    click web3 "https://github.com/nginxinc/nginx-basics-workshops/tree/master/OSS/labs/lab2/nginx-oss/usr/share/nginx/html/"
    click web3 "https://github.com/nginxinc/nginx-basics-workshops/tree/master/Plus/labs/lab2/nginx-plus/usr/share/nginx/html/"

    click Prometheus "https://github.com/nginxinc/nginx-basics-workshops/blob/master/OSS/labs/lab6/nginx-plus/etc/prometheus/prometheus.yml"
    click Prometheus "https://github.com/nginxinc/nginx-basics-workshops/blob/master/OSS/labs/lab6/docker-compose.yml"

    click Grafana "https://github.com/nginxinc/nginx-basics-workshops/blob/master/OSS/labs/lab6/docker-compose.yml"
    click Grafana "https://github.com/nginxinc/nginx-basics-workshops/tree/master/OSS/labs/media"
```
