How cybertec-postgresql/patroni-windows-packaging works
This repo is not an “application” with request/response flows; it’s a Windows packaging + installer automation project for running Patroni (PostgreSQL HA manager) on Windows.
• Build/release packaging pipeline (PowerShell scripts + Inno Setup + GitHub Actions)
• Install-time behavior (what gets installed, where, and how services are registered)
• Runtime topology on Windows (Windows services: etcd, patroni, vip; and how they interact with PostgreSQL and with each other across nodes)
CI/CD and release automation
• .github/workflows/test.yml and .github/workflows/release.yml
• “Test” and “Release” pipelines producing artifacts.
• .github/dependabot.yml
• Optional: show dependency update automation if relevant.
Build scripts (local developer build)
• make.ps1, clean.ps1, globals.ps1
• These are part of the build toolchain (inputs to produce release artifacts).
Installer definition
• installer/patroni.iss
• Inno Setup script defining what files are bundled and what installer does.
Runtime payload (what gets installed)
Everything under src/ is the runtime payload/config/scripts:
• Configs: src/patroni.yaml, src/etcd.yaml, src/vip.yaml
• Windows service wrapper configs: src/patroni_service.xml, src/etcd_service.xml, src/vip_service.xml
• Install/uninstall: src/install.ps1, src/uninstall.ps1
• CLI helper: src/patronictl.bat
Documentation
• doc/setup.md, README.md
Goal: Show how source files become the downloadable release (ZIP/installer).
• Developer workstation
• Runs make.ps1 / clean.ps1 (and uses globals.ps1)
• GitHub Actions
• test.yml (validates repo)
• release.yml (builds and publishes)
• Inno Setup compiler
• Consumes installer/patroni.iss
• Output artifacts
• “Release ZIP” (per README)
• (Possibly) “Installer EXE” (implied by Inno Setup usage)
• src/* + installer/patroni.iss → Inno Setup → Release artifact
• GitHub Actions release job → GitHub Releases page
Labeling tips
• Make it explicit that this repo produces an installable bundle, not a running server.
Goal: Show what the installer does to the machine.
• “Windows Server / Windows Node”
• Installer artifact (ZIP extraction or Inno Setup EXE)
• install.ps1
• Registers services using the *_service.xml definitions
• Installs configs *.yaml
• Places helper patronictl.bat
• Windows Service Control Manager (SCM)
• Receives service registration actions
• uninstall.ps1 (reverse path)
• Installer → lays down files (configs, service XMLs, scripts)
• install.ps1 → Windows SCM (create/register/start services)
• uninstall.ps1 → Windows SCM (stop/remove services) + filesystem cleanup
Important: show “service wrapper” explicitly
• “Service Wrapper (configured by XML)” → launches actual process (etcd/patroni/vip)
Goal: Represent the actual HA system the packaging enables.
• etcd service
• Distributed coordination / DCS
• patroni service
• HA controller; talks to etcd; controls PostgreSQL
• postgresql service/process (external dependency)
• Managed by Patroni
• vip service
• Manages/announces a virtual IP (VIP) for primary routing (implementation details abstracted)
Cross-node / cluster components
• Multiple Windows nodes (Node A, Node B, Node C)
• etcd cluster communication between nodes
• Patroni instances communicate via etcd (leader election, state)
• Clients connect to VIP (or primary) to reach current leader PostgreSQL
• Patroni ⇄ etcd (state store, leader election, membership)
• Patroni → PostgreSQL (start/stop/promote/configure; health checks)
• VIP service ← Patroni state (or watches leader state indirectly) → network VIP assignment
• Client applications → VIP → active PostgreSQL primary
Make the “control plane vs data plane” explicit
• Control plane: Patroni + etcd + VIP coordination
• Data plane: application traffic to PostgreSQL (preferably through VIP)
Architectural patterns to highlight (specific to this project)
• Infrastructure packaging pattern: repo produces installer artifacts, not a long-running app.
• Service-wrapper-based Windows daemons: *_service.xml indicates processes are run as Windows services via a wrapper.
• HA orchestration: Patroni + DCS (etcd) + VIP failover routing.
• Immutable-ish payload: src/*.yaml suggests templated/default configs shipped with installer.
• make.ps1, clean.ps1, globals.ps1
• GitHub Actions: test.yml, release.yml
• Inno Setup: installer/patroni.iss
• Payload: install.ps1, uninstall.ps1, patronictl.bat
• Configs: etcd.yaml, patroni.yaml, vip.yaml
• Service definitions: etcd_service.xml, patroni_service.xml, vip_service.xml
Runtime (conceptual but essential to system truth):
• Windows SCM
• Service Wrapper (driven by XML)
• etcd / Patroni / VIP services
• PostgreSQL (external but required for Patroni’s mission)
• Clients (connect via VIP)
Don’t overthink it: “separate into as many components as possible”
For this repo, “detail” means not just “Patroni on Windows”, but explicitly showing:
• the packaging layer (PowerShell + Inno Setup + CI)
• the installation layer (install/uninstall scripts + service registration)
• the runtime layer (Windows services + cluster interactions)