# netbox-community/netbox-docker architecture

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

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

## Overview

##### Project type and purpose
- This is not a traditional full-stack application you write from scratch, but a **containerization/packaging project** for an existing Django app (NetBox).
- Its primary purpose is to **build, configure, and publish** Docker images for NetBox, and to **orchestrate** those images (plus backing services) via Docker Compose.

##### File structure
- Top-level build artifacts and configuration:
- `Dockerfile` + `docker/` directory (entrypoint & housekeeping scripts, nginx-unit config)
- `build.sh`, `build-latest.sh`, `build-functions/` (shell functions for image building)
- `configuration/` (Python modules that generate NetBox’s settings inside the container)
- Orchestration manifests:
- `docker-compose.yml` + override examples for production, test, and development (`.override.yml`, `.test.yml`)
- `env/` directory with environment files for NetBox, Postgres, Redis
- CI/CD and metadata:
- `.github/workflows/` for build & release pipelines
- `release.sh`, `test.sh`, `pyproject.toml`, `requirements-container.txt`
- Tests:
- `test-configuration/` runs quick unit tests against the `configuration` Python code

##### README for additional insights
- Images are **rebuilt daily** and pushed to **three container registries**
- The runtime stack consists of **NetBox**, **PostgreSQL**, **Redis (cache + task queue)**, optional **LDAP**, all wired via Docker Compose
- Build pipeline lives in GitHub Actions, invoking local shell scripts (`build.sh`, `build-latest.sh`)

##### Every essential element
- Review against `docker-compose.yml` and `Dockerfile` to verify you included all services and scripts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source and CI/CD
    subgraph "Source & CI/CD" 
        direction TB
        Repo["Source Code Repository"]:::source
        PushWF["push.yml"]:::ci
        ReleaseWF["release.yml"]:::ci
        Repo -->|triggers| PushWF
        Repo -->|triggers| ReleaseWF
    end

    %% Build System
    subgraph "Build System" 
        direction TB
        BuildSH["build.sh"]:::build
        BuildLatest["build-latest.sh"]:::build
        BuildFuncs["build-functions/"]:::build
        Repo -->|uses| BuildSH
        Repo -->|uses| BuildLatest
        Repo -->|uses| BuildFuncs
    end

    %% Configuration Layer
    subgraph "Configuration Layer" 
        direction TB
        ConfigModule["configuration/"]:::config
        Repo -->|includes| ConfigModule
    end

    %% Container Config
    subgraph "Container Configuration" 
        direction TB
        DockerfileNode["Dockerfile"]:::config
        DockerDir["docker/"]:::config
        Repo -->|contains| DockerfileNode
        Repo -->|contains| DockerDir
    end

    %% CI/CD Scripts & Tests
    subgraph "CI/CD Scripts & Tests"
        direction TB
        ReleaseSH["release.sh"]:::ci
        TestSH["test.sh"]:::ci
        TestConfig["test-configuration/test_config.py"]:::test
        Repo --> ReleaseSH
        Repo --> TestSH
        Repo --> TestConfig
    end

    %% Registries
    subgraph "Container Registries"
        direction TB
        DockerHub["Docker Hub"]:::registry
        Quay["Quay.io"]:::registry
        GHCR["GitHub Container Registry"]:::registry
        BuildSH -->|push images| DockerHub
        BuildSH -->|push images| Quay
        BuildSH -->|push images| GHCR
        BuildLatest -->|push images| DockerHub
    end

    %% Runtime Orchestration
    subgraph "Runtime Orchestration"
        direction TB
        Compose["docker-compose.yml"]:::runtime
        ComposeOvr["docker-compose.override.yml.example"]:::runtime
        ComposeTest["docker-compose.test.yml"]:::runtime
        EnvDir["env/"]:::runtime
        Compose -->|pull images| DockerHub
        Compose -->|pull images| Quay
        Compose -->|pull images| GHCR
        Compose -->|reads| EnvDir

        subgraph "Docker Host"
            direction TB
            subgraph "NetBox Stack"
                direction TB
                Netbox["netbox:8080 (nginx-unit + Django)"]:::service
                Postgres["postgres"]:::service
                Redis["redis"]:::service
                LDAP["optional LDAP"]:::service
                Netbox -->|connects| Postgres
                Netbox -->|connects| Redis
                Netbox -->|queries| LDAP
            end
            DockerDirEntry["docker/docker-entrypoint.sh"]:::script
            Housekeeping["docker/housekeeping.sh"]:::script
            LaunchNB["docker/launch-netbox.sh"]:::script
            Netbox -->|entrypoint| DockerDirEntry
            Netbox -->|housekeeping| Housekeeping
            Netbox -->|launch| LaunchNB
        end
    end

    %% Paths for click events
    click Repo "https://github.com/netbox-community/netbox-docker/tree/release//"
    click PushWF "https://github.com/netbox-community/netbox-docker/blob/release/.github/workflows/push.yml"
    click ReleaseWF "https://github.com/netbox-community/netbox-docker/blob/release/.github/workflows/release.yml"
    click BuildSH "https://github.com/netbox-community/netbox-docker/blob/release/build.sh"
    click BuildLatest "https://github.com/netbox-community/netbox-docker/blob/release/build-latest.sh"
    click BuildFuncs "https://github.com/netbox-community/netbox-docker/tree/release/build-functions/"
    click ConfigModule "https://github.com/netbox-community/netbox-docker/tree/release/configuration/"
    click DockerfileNode "https://github.com/netbox-community/netbox-docker/tree/release/Dockerfile"
    click DockerDir "https://github.com/netbox-community/netbox-docker/tree/release/docker/"
    click ReleaseSH "https://github.com/netbox-community/netbox-docker/blob/release/release.sh"
    click TestSH "https://github.com/netbox-community/netbox-docker/blob/release/test.sh"
    click TestConfig "https://github.com/netbox-community/netbox-docker/blob/release/test-configuration/test_config.py"
    click Compose "https://github.com/netbox-community/netbox-docker/blob/release/docker-compose.yml"
    click ComposeOvr "https://github.com/netbox-community/netbox-docker/blob/release/docker-compose.override.yml.example"
    click ComposeTest "https://github.com/netbox-community/netbox-docker/blob/release/docker-compose.test.yml"
    click EnvDir "https://github.com/netbox-community/netbox-docker/tree/release/env/"

    %% Styles
    classDef source fill:#FFD580,stroke:#333,stroke-width:1px
    classDef ci fill:#FFB3B3,stroke:#333,stroke-width:1px
    classDef build fill:#B3D9FF,stroke:#333,stroke-width:1px
    classDef config fill:#D9B3FF,stroke:#333,stroke-width:1px
    classDef registry fill:#C2F0C2,stroke:#333,stroke-width:1px
    classDef runtime fill:#FFE6B3,stroke:#333,stroke-width:1px
    classDef service fill:#B3FFCC,stroke:#333,stroke-width:1px
    classDef script fill:#FFCCE5,stroke:#333,stroke-width:1px
    classDef test fill:#E6E6E6,stroke:#333,stroke-width:1px
```
