# cvarad96/pi-hosted architecture

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

- Interactive diagram: https://gitdiagram.com/cvarad96/pi-hosted
- Repository: https://github.com/cvarad96/pi-hosted

## Overview

##### Project type and purpose
- This is an open-source “app template” library and set of helper scripts for hosting Dockerized services on Portainer (primarily on Raspberry Pi OS).
- It provides JSON template definitions, Docker-Compose stacks, configuration files, build scripts (to auto-generate lists and READMEs), installation tools, and documentation to simplify deploying dozens of services via Portainer.

##### File structure
- Top-level “template/” directory holds JSON definitions that Portainer will fetch as “App Templates.”
- “configs/” holds service‐specific config files (e.g., Caddy, bind9, Drupal settings) that get mounted into containers.
- “build/” houses generators and templates for auto-creating the Markdown docs and JSON lists.
- “tools/” comprises shell scripts for installing Docker, Portainer, and individual services on the host OS.
- “docs/” is the human-readable documentation generated (and maintained) alongside the templates.
- CI/CD workflows in “.github/workflows/” automatically lint, generate, and publish artifacts when the repository is updated.

##### README for additional insights
- The README confirms the target OS (Raspberry Pi OS Buster/Bullseye, Debian) and details the install/update scripts.
- It points out the two primary outputs: the Portainer App Template URLs (JSON) for each architecture, and the installation scripts for host preparation.
- It references GitHub Actions that run the “build/generators” scripts to keep docs & lists in sync.

a. Main components:
- Host OS (Raspberry Pi OS / Debian)
- Docker Engine (daemon)
- Portainer CE container (and optional Portainer Agent container)
- GitHub repo (source code, JSON templates, build & tool scripts)
- CI/CD pipeline (GitHub Actions workflows)
- Build generators (shell scripts in build/)
- App Template endpoint (JSON served via raw.githubusercontent.com)
- Tooling scripts (install_docker.sh, install_portainer.sh, tools/install_*.sh)
- Docker-Compose stacks (stack/*.yml)
- Config file directory (configs/)
- Documentation site or local docs/ folder
b. Relationships & interactions:
1. Developer pushes changes → GitHub Actions trigger “generateAppList.sh” etc. → updates docs/ and template/app lists.
2. Portainer UI (in the Portainer CE container) is configured to fetch the JSON App Template URLs from the raw GitHub URLs.
3. End user selects a template in Portainer → Portainer instructs Docker Engine to pull the appropriate Docker image (from Docker Hub) and mount volumes (using configs/ if necessary).
4. tool scripts on the host OS can be run manually or by CI to install prerequisites (Docker, libseccomp, Portainer) prior to using Portainer.
5. Standalone stacks in stack/ can be deployed either via Portainer’s “Stacks” feature or via docker-compose CLI.
c. Architectural patterns & principles:
- Pipeline style: Source repo + CI → auto-generated artifacts → consumed at runtime by Portainer
- Separation of concerns:
- Build scripts vs. templates vs. runtime components
- Host-level installation scripts vs. containerized services
d. Key technologies & frameworks:
- Docker Engine & Docker-Compose
- Portainer CE (container management UI)
- GitHub Actions for CI/CD
- Shell scripting (Bash) for build & install scripts
- Markdown docs generated from templates

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Source Repository
  subgraph "Source Repository"
    GH["GitHub Repo"]:::source
    CI["GitHub Actions CI/CD Pipeline"]:::build
  end

  GH -->|push triggers| CI
  click CI "https://github.com/cvarad96/pi-hosted/tree/master/.github/workflows/"

  %% Build Pipeline
  subgraph "Build Pipeline"
    subgraph "Environment & Helpers"
      ENV_ENV["env.sh"]:::build
      ENV_JOIN["joinApps.sh"]:::build
      ENV_SPLIT["splitJson.sh"]:::build
    end
    subgraph "Generators"
      GEN["Build Generators"]:::build
    end
    subgraph "Templates"
      TMP["Build Templates"]:::build
    end
    ENV_ENV --> GEN
    ENV_JOIN --> GEN
    ENV_SPLIT --> GEN
    GEN --> TMP
    click ENV_ENV "https://github.com/cvarad96/pi-hosted/blob/master/build/env.sh"
    click ENV_JOIN "https://github.com/cvarad96/pi-hosted/blob/master/build/joinApps.sh"
    click ENV_SPLIT "https://github.com/cvarad96/pi-hosted/blob/master/build/splitJson.sh"
    click GEN "https://github.com/cvarad96/pi-hosted/tree/master/build/generators/"
    click TMP "https://github.com/cvarad96/pi-hosted/tree/master/build/templates/"
  end

  CI -->|runs| ENV_ENV
  CI -->|runs| ENV_JOIN
  CI -->|runs| ENV_SPLIT
  CI -->|runs| GEN
  CI -->|renders| TMP

  %% Generated Outputs
  DDocs["Generated Documentation (docs/)"]:::build
  JSON["App Template Definitions (template/apps/)"]:::build
  DDocs -->|published| JSON
  CI -->|updates| DDocs
  CI -->|generates| JSON
  click DDocs "https://github.com/cvarad96/pi-hosted/tree/master/docs/"
  click JSON "https://github.com/cvarad96/pi-hosted/tree/master/template/apps/"

  %% External Endpoint
  RAW["App Templates JSON (raw.githubusercontent.com)"]:::external
  JSON -->|served via| RAW

  %% Runtime Environment
  subgraph "Runtime Environment"
    HOST["Host OS (Raspberry Pi OS/Debian)"]:::runtime
    TOOLS["Host Installation & Tooling Scripts"]:::runtime
    DOCKER["Docker Engine"]:::runtime
    PORT["Portainer CE Container"]:::runtime
    AGENT["Portainer Agent (optional)"]:::runtime
    STACKS["Standalone Docker-Compose Stacks (stack/)"]:::runtime
    CONFIGS["Service Configuration Files (configs/)"]:::runtime
    SERVICES["Service Containers"]:::runtime
  end

  HOST -->|runs| TOOLS
  click TOOLS "https://github.com/cvarad96/pi-hosted/tree/master/tools/"
  HOST -->|provides| DOCKER
  DOCKER -->|hosts| PORT
  PORT -->|manages| SERVICES
  PORT -->|fetches templates from| RAW
  PORT -->|optional connects to| AGENT
  SERVICES -->|mounts| CONFIGS
  click STACKS "https://github.com/cvarad96/pi-hosted/tree/master/stack/"
  SERVICES -->|deployed via stacks| STACKS
  click CONFIGS "https://github.com/cvarad96/pi-hosted/tree/master/configs/"

  %% Relationships between Build and Runtime
  RAW -->|fetched by| PORT

  %% Styles
  classDef source fill:#ADD8E6,stroke:#333,stroke-width:1px
  classDef build fill:#B0E0E6,stroke:#333,stroke-width:1px
  classDef runtime fill:#98FB98,stroke:#333,stroke-width:1px
  classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
