# cherif47/cluster_pgsql_docker architecture

> Architecture diagram of the GitHub repository cherif47/cluster_pgsql_docker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cherif47/cluster_pgsql_docker
- Repository: https://github.com/cherif47/cluster_pgsql_docker

## Overview

This repository is an Ansible deployment for a three-node Docker Swarm hosting etcd and a Patroni-managed PostgreSQL 18 cluster, plus Portainer, PgBouncer, and a HAProxy/Keepalived virtual-IP entry point. An operator runs `playbook.yml`; its documented plays bootstrap hosts, install Docker, form the Swarm, prepare nodes, then deploy services. The graph follows those documented responsibilities and major capabilities. Source excerpts were unavailable, so relationships are limited to those stated in the README; implementation details within the roles are not inferred.

Main entry points: [`playbook.yml`](https://github.com/cherif47/cluster_pgsql_docker/blob/main/playbook.yml) (Deployment plays), [`roles/portainer/tasks/main.yml`](https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/portainer/tasks/main.yml) (Portainer deployment), [`roles/etcd/tasks/main.yml`](https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/etcd/tasks/main.yml) (etcd deployment), [`files/etcd-stack.yml`](https://github.com/cherif47/cluster_pgsql_docker/blob/main/files/etcd-stack.yml) (etcd stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Deployment orchestration"]
  node_playbook["Deployment plays<br/>[playbook.yml]"]
  node_inventory["Host inventory<br/>[inventory.ini]"]
  node_variables["Shared settings<br/>[vars.yml]"]
end

subgraph group_cluster["Host and Swarm"]
  node_bootstrap["Host bootstrap<br/>[main.yml]"]
  node_docker["Docker installation<br/>[main.yml]"]
  node_swarm_init["Swarm initialization<br/>[main.yml]"]
  node_swarm_join["Manager joining<br/>[main.yml]"]
end

subgraph group_database["Database platform"]
  node_node_prep["Node preparation<br/>[main.yml]"]
  node_etcd_role["etcd deployment<br/>[main.yml]"]
  node_etcd_stack["etcd stack<br/>[etcd-stack.yml]"]
  node_etcd_cluster[("etcd cluster")]
  node_patroni_role["Patroni deployment<br/>[main.yml]"]
  node_patroni_stack["Patroni stack<br/>[patroni-stack.yml]"]
  node_postgres[("PostgreSQL HA")]
end

subgraph group_access["Access and management"]
  node_pgbouncer["PgBouncer<br/>[main.yml]"]
  node_portainer_role["Portainer deployment<br/>[main.yml]"]
  node_portainer_agent["Portainer agent stack"]
  node_portainer_stack["Portainer server stack"]
  node_haproxy["HAProxy<br/>[main.yml]"]
  node_keepalived["Keepalived VIP<br/>[main.yml]"]
end

node_operator(("Operator"))

node_operator -->|"runs"| node_playbook
node_playbook -->|"targets hosts"| node_inventory
node_playbook -->|"uses settings"| node_variables
node_playbook -->|"runs first"| node_bootstrap
node_playbook -->|"installs Docker"| node_docker
node_playbook -->|"initializes Swarm"| node_swarm_init
node_playbook -->|"joins managers"| node_swarm_join
node_playbook -->|"prepares nodes"| node_node_prep
node_playbook -->|"deploys etcd"| node_etcd_role
node_etcd_role -->|"deploys stack"| node_etcd_stack
node_etcd_stack -->|"defines services"| node_etcd_cluster
node_playbook -->|"deploys Patroni"| node_patroni_role
node_patroni_role -->|"deploys stack"| node_patroni_stack
node_patroni_stack -->|"defines services"| node_postgres
node_playbook -->|"deploys Portainer"| node_portainer_role
node_portainer_role -->|"deploys agent"| node_portainer_agent
node_portainer_role -->|"deploys server"| node_portainer_stack
node_playbook -->|"deploys PgBouncer"| node_pgbouncer
node_playbook -->|"deploys HAProxy"| node_haproxy
node_playbook -->|"deploys Keepalived"| node_keepalived

click node_playbook "https://github.com/cherif47/cluster_pgsql_docker/blob/main/playbook.yml"
click node_inventory "https://github.com/cherif47/cluster_pgsql_docker/blob/main/inventory.ini"
click node_variables "https://github.com/cherif47/cluster_pgsql_docker/blob/main/group_vars/all/vars.yml"
click node_bootstrap "https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/bootstrap/tasks/main.yml"
click node_docker "https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/docker/tasks/main.yml"
click node_swarm_init "https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/swarm-manager/tasks/main.yml"
click node_swarm_join "https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/swarm-join-manager/tasks/main.yml"
click node_node_prep "https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/node_prepare/tasks/main.yml"
click node_etcd_role "https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/etcd/tasks/main.yml"
click node_etcd_stack "https://github.com/cherif47/cluster_pgsql_docker/blob/main/files/etcd-stack.yml"
click node_patroni_role "https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/patroni/tasks/main.yml"
click node_patroni_stack "https://github.com/cherif47/cluster_pgsql_docker/blob/main/files/patroni-stack.yml"
click node_pgbouncer "https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/pgbouncer/tasks/main.yml"
click node_portainer_role "https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/portainer/tasks/main.yml"
click node_portainer_agent "https://github.com/cherif47/cluster_pgsql_docker/blob/main/files/portainer-agent.yml"
click node_portainer_stack "https://github.com/cherif47/cluster_pgsql_docker/blob/main/files/portainer-stack.yml"
click node_haproxy "https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/haproxy/tasks/main.yml"
click node_keepalived "https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/keepalived/tasks/main.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_playbook,node_inventory,node_variables toneBlue
class node_bootstrap,node_docker,node_swarm_init,node_swarm_join toneAmber
class node_node_prep,node_etcd_role,node_etcd_stack,node_etcd_cluster,node_patroni_role,node_patroni_stack,node_postgres toneMint
class node_pgbouncer,node_portainer_role,node_portainer_agent,node_portainer_stack,node_haproxy,node_keepalived toneRose
class node_operator toneIndigo
```

## Components

### Deployment orchestration

- [Deployment plays](https://github.com/cherif47/cluster_pgsql_docker/blob/main/playbook.yml): `playbook.yml`
- [Host inventory](https://github.com/cherif47/cluster_pgsql_docker/blob/main/inventory.ini): `inventory.ini`
- [Shared settings](https://github.com/cherif47/cluster_pgsql_docker/blob/main/group_vars/all/vars.yml): `group_vars/all/vars.yml`

### Host and Swarm

- [Host bootstrap](https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/bootstrap/tasks/main.yml): `roles/bootstrap/tasks/main.yml`
- [Docker installation](https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/docker/tasks/main.yml): `roles/docker/tasks/main.yml`
- [Swarm initialization](https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/swarm-manager/tasks/main.yml): `roles/swarm-manager/tasks/main.yml`
- [Manager joining](https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/swarm-join-manager/tasks/main.yml): `roles/swarm-join-manager/tasks/main.yml`

### Database platform

- [Node preparation](https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/node_prepare/tasks/main.yml): `roles/node_prepare/tasks/main.yml`
- [etcd deployment](https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/etcd/tasks/main.yml): `roles/etcd/tasks/main.yml`
- [etcd stack](https://github.com/cherif47/cluster_pgsql_docker/blob/main/files/etcd-stack.yml): `files/etcd-stack.yml`
- **etcd cluster**
- [Patroni deployment](https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/patroni/tasks/main.yml): `roles/patroni/tasks/main.yml`
- [Patroni stack](https://github.com/cherif47/cluster_pgsql_docker/blob/main/files/patroni-stack.yml): `files/patroni-stack.yml`
- **PostgreSQL HA**

### Access and management

- [PgBouncer](https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/pgbouncer/tasks/main.yml): `roles/pgbouncer/tasks/main.yml`
- [Portainer deployment](https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/portainer/tasks/main.yml): `roles/portainer/tasks/main.yml`
- [Portainer agent stack](https://github.com/cherif47/cluster_pgsql_docker/blob/main/files/portainer-agent.yml): `files/portainer-agent.yml`
- [Portainer server stack](https://github.com/cherif47/cluster_pgsql_docker/blob/main/files/portainer-stack.yml): `files/portainer-stack.yml`
- [HAProxy](https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/haproxy/tasks/main.yml): `roles/haproxy/tasks/main.yml`
- [Keepalived VIP](https://github.com/cherif47/cluster_pgsql_docker/blob/main/roles/keepalived/tasks/main.yml): `roles/keepalived/tasks/main.yml`

### Other components

- **Operator**

## Connections

- Operator → Deployment plays: runs (evidence: `README.md`)
- Deployment plays → Host inventory: targets hosts (evidence: `README.md`)
- Deployment plays → Shared settings: uses settings (evidence: `README.md`)
- Deployment plays → Host bootstrap: runs first (evidence: `README.md`)
- Deployment plays → Docker installation: installs Docker (evidence: `README.md`)
- Deployment plays → Swarm initialization: initializes Swarm (evidence: `README.md`)
- Deployment plays → Manager joining: joins managers (evidence: `README.md`)
- Deployment plays → Node preparation: prepares nodes (evidence: `README.md`)
- Deployment plays → etcd deployment: deploys etcd (evidence: `README.md`)
- etcd deployment → etcd stack: deploys stack (evidence: `README.md`)
- etcd stack → etcd cluster: defines services (evidence: `README.md`)
- Deployment plays → Patroni deployment: deploys Patroni (evidence: `README.md`)
- Patroni deployment → Patroni stack: deploys stack (evidence: `README.md`)
- Patroni stack → PostgreSQL HA: defines services (evidence: `README.md`)
- Deployment plays → Portainer deployment: deploys Portainer (evidence: `README.md`)
- Portainer deployment → Portainer agent stack: deploys agent (evidence: `README.md`)
- Portainer deployment → Portainer server stack: deploys server (evidence: `README.md`)
- Deployment plays → PgBouncer: deploys PgBouncer (evidence: `README.md`)
- Deployment plays → HAProxy: deploys HAProxy (evidence: `README.md`)
- Deployment plays → Keepalived VIP: deploys Keepalived (evidence: `README.md`)
