# lxwulf/cw-role architecture

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

- Interactive diagram: https://gitdiagram.com/lxwulf/cw-role
- Repository: https://github.com/lxwulf/cw-role

## Overview

##### Project type and purpose
- This is an Ansible-based automation repository (“CW-ROLE”) that installs and configures a complete Nextcloud stack on Fedora Server with SELinux enabled.
- It’s an open-source DevOps tool/playbook, not a traditional web app. It automates provisioning of NGINX, Redis, PHP, PostgreSQL, SELinux rules, firewall, and Nextcloud itself.

##### File structure
Top-level artifacts and their roles:
- ansible.cfg, hosts, group_vars/ – Ansible control-node configuration and inventory
- cw-role_playbook.yml – Entry-point playbook that applies the CW-ROLE to target hosts
- CW-ROLE/
- defaults/main.yml – fallback variables
- vars/main/… – variable definitions (task_vars, template_vars)
- tasks/01_* → 09_* – sequential tasks: host prep, firewall, packages, nginx, redis, php, postgresql, ACL/SELinux, Nextcloud config (nc)
- handlers/main.yml – service restarts/triggers
- templates/ – Jinja2 templates for nginx, php-fpm, php.ini, redis.conf, postgresql.conf, pg_hba.conf, and Nextcloud DB schema
- lib/gen_db.sql.j2 – DB initialization script
- docs/ – supporting documentation and logo
- cw-role_playbook.yml – orchestrates the role on hosts.

##### README for additional insights
- Target OS: Fedora Server with SELinux
- Stack acronym LNPP: Linux (Fedora), NGINX, PHP (8.1), PostgreSQL (14), plus Redis and Nextcloud
- Emphasis on idempotent, secure, performant configuration
- Variables driven via two YAML files under vars/main: one for tasks, one for templates

a. Main components
- Ansible Control Node (local machine running ansible-playbook)
- Inventory (hosts file + group_vars)
- CW-ROLE (role code: defaults, vars, tasks, handlers, templates)
- Managed Node (remote Fedora Server)
- Services on Managed Node:
‣ NGINX
‣ PHP-FPM (with php.ini, opcache)
‣ Redis
‣ PostgreSQL
‣ Nextcloud application
‣ SELinux & Firewall

b. Relationships and interactions
- Control Node uses ansible-playbook → reads inventory → loads group_vars/host_vars
- Playbook calls CW-ROLE → executes tasks in order on Managed Node via SSH and Ansible modules
- Tasks render Jinja2 templates → write config files for each service
- Handlers triggered by tasks → restart or reload services
- Nextcloud application (PHP + NGINX) communicates with PostgreSQL (SQL) and Redis (caching)
- SELinux contexts and ACLs applied after service config

c. Architectural patterns & design principles
- Infrastructure as Code (IaC) with Ansible roles and playbooks
- Role-based decomposition: each major concern (firewall, web server, caching, DB, app) in its own task file
- Idempotency: tasks use variables, handlers and checks to avoid repeated work
- Layered configuration:
– defaults < vars < group_vars override
– templates define reusable configuration fragments
- Sequential orchestration: tasks numbered 01…09 enforce order

d. Relevant technologies & frameworks
- Ansible (core automation engine)
- Jinja2 (templating engine)
- Fedora Server + SELinux
- NGINX (web server)
- PHP-FPM 8.1 (application runtime)
- Redis (cache layer)
- PostgreSQL 14 (database)
- Nextcloud (PHP-based cloud application)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Node and Inventory
    subgraph "Ansible Control Node"
        A_cfg["ansible.cfg"]:::ansible
        A_hosts["hosts"]:::ansible
        A_groupvars["group_vars/"]:::ansible
        A_playbook["cw-role_playbook.yml"]:::ansible
    end

    subgraph "Inventory"
        I_hosts["hosts"]:::ansible
        I_groupvars["group_vars/tes.yml"]:::ansible
    end

    A_playbook -->|"reads"| I_hosts
    A_playbook -->|"reads"| I_groupvars

    %% CW-ROLE Role Structure
    subgraph "CW-ROLE (Ansible Role Root)"
        direction TB
        subgraph "Defaults"
            D_main["defaults/main.yml"]:::ansible
        end
        subgraph "Variables"
            V_tasks["task_vars/task_variable_list.yml"]:::ansible
            V_templates["template_vars/template_variable_list.yml"]:::ansible
        end
        subgraph "Tasks (01 → 09)"
            direction TB
            T_main["main.yml"]:::ansible
            T1["01_configure_host.yml"]:::ansible
            T2["02_configure_firewall.yml"]:::ansible
            T3["03_installing_packages.yml"]:::ansible
            T4["04_configure_nginx.yml"]:::ansible
            T5["05_configure_redis.yml"]:::ansible
            T6["06_configure_php.yml"]:::ansible
            T7["07_configure_postgresql.yml"]:::ansible
            T8["08_set_permissions_for_acl_and_selinux.yml"]:::ansible
            T9["09_configure_nc.yml"]:::ansible
        end
        subgraph "Handlers"
            H_main["handlers/main.yml"]:::ansible
        end
        subgraph "Templates"
            TP_nginx["nginx/*.j2"]:::ansible
            TP_php["php/*.j2"]:::ansible
            TP_redis["redis/redis.conf.j2"]:::ansible
            TP_postgres["postgresql/*.j2"]:::ansible
        end
        L_dbinit["lib/gen_db.sql.j2"]:::ansible
    end

    A_playbook -->|"calls"| D_main
    A_playbook -->|"calls"| V_tasks
    A_playbook -->|"calls"| V_templates
    A_playbook -->|"executes"| T_main
    T_main -->|includes| T1 & T2 & T3 & T4 & T5 & T6 & T7 & T8 & T9
    T1 & T2 & T3 & T4 & T5 & T6 & T7 & T8 & T9 -->|notify| H_main
    T4 -->|uses| TP_nginx
    T6 -->|uses| TP_php
    T5 -->|uses| TP_redis
    T7 -->|uses| TP_postgres
    T9 -->|uses| L_dbinit

    %% Deployment to Managed Node
    A_playbook -->|"SSH/Ansible Modules"| Managed["Managed Node (Fedora Server)"]:::service

    %% Services on Managed Node
    subgraph "Managed Node Services"
        direction TB
        S_selinux["SELinux & Firewall"]:::security
        S_nginx["NGINX"]:::service
        S_php["PHP-FPM"]:::service
        S_redis["Redis"]:::db
        S_postgres["PostgreSQL"]:::db
        S_nextcloud["Nextcloud Application"]:::app
    end

    Managed -->|applies configs| S_selinux
    Managed -->|applies configs| S_nginx
    Managed -->|applies configs| S_php
    Managed -->|applies configs| S_redis
    Managed -->|applies configs| S_postgres
    Managed -->|deploys| S_nextcloud

    %% Handlers triggering restarts
    H_main -->|restart/reload| S_nginx
    H_main -->|restart/reload| S_php
    H_main -->|restart/reload| S_redis
    H_main -->|restart/reload| S_postgres

    %% Application interactions
    S_nginx -->|forwards PHP requests| S_php
    S_php -->|executes Nextcloud| S_nextcloud
    S_nextcloud -->|reads/writes| S_postgres
    S_nextcloud -->|cache| S_redis

    %% Click Events
    click A_cfg "https://github.com/lxwulf/cw-role/blob/master/ansible.cfg"
    click A_hosts "https://github.com/lxwulf/cw-role/tree/master/hosts"
    click A_groupvars "https://github.com/lxwulf/cw-role/tree/master/group_vars/"
    click A_playbook "https://github.com/lxwulf/cw-role/blob/master/cw-role_playbook.yml"
    click I_hosts "https://github.com/lxwulf/cw-role/tree/master/hosts"
    click I_groupvars "https://github.com/lxwulf/cw-role/blob/master/group_vars/tes.yml"
    click D_main "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/defaults/main.yml"
    click V_tasks "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/vars/main/task_vars/task_variable_list.yml"
    click V_templates "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/vars/main/template_vars/template_variable_list.yml"
    click T1 "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/tasks/01_configure_host.yml"
    click T2 "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/tasks/02_configure_firewall.yml"
    click T3 "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/tasks/03_installing_packages.yml"
    click T4 "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/tasks/04_configure_nginx.yml"
    click T5 "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/tasks/05_configure_redis.yml"
    click T6 "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/tasks/06_configure_php.yml"
    click T7 "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/tasks/07_configure_postgresql.yml"
    click T8 "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/tasks/08_set_permissions_for_acl_and_selinux.yml"
    click T9 "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/tasks/09_configure_nc.yml"
    click H_main "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/handlers/main.yml"
    click TP_nginx "https://github.com/lxwulf/cw-role/tree/master/CW-ROLE/templates/nginx/"
    click TP_php "https://github.com/lxwulf/cw-role/tree/master/CW-ROLE/templates/php/"
    click TP_redis "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/templates/redis/redis.conf.j2"
    click TP_postgres "https://github.com/lxwulf/cw-role/tree/master/CW-ROLE/templates/postgresql/"
    click L_dbinit "https://github.com/lxwulf/cw-role/blob/master/CW-ROLE/lib/gen_db.sql.j2"

    %% Styles
    classDef ansible fill:#FFA500,stroke:#333,stroke-width:1px
    classDef service fill:#8FBC8F,stroke:#333,stroke-width:1px
    classDef db fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef app fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef security fill:#90EE90,stroke:#333,stroke-width:1px
```
