How cvarad96/pi-hosted works
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