Added sphinx docker role draft

filter_plugins/configuration_filters.py

@@ -19,10 +19,21 @@ def get_css_enabled(applications, application_id):
     enabled = app.get('css', {}).get('enabled', True)
     return bool(enabled)
 
+def get_database_central_storage(applications, application_id):
+    """
+    Retrieve the type of the database from the application dictionary.
+    The expected key structure is: applications[application_id]['database']['central_storage'].
+    If not defined, None is returned.
+    """
+    app = applications.get(application_id, {})
+    db_type = app.get('database', {}).get('central_storage', False)
+    return db_type
+
 class FilterModule(object):
     def filters(self):
         return {
             'get_css_enabled': get_css_enabled,
             'get_oidc_enabled': get_oidc_enabled,
-            'get_oauth2_enabled': get_oauth2_enabled
+            'get_oauth2_enabled': get_oauth2_enabled,
+            'get_database_central_storage': get_database_central_storage,
         }

group_vars/all/03_domains.yml

@@ -38,6 +38,7 @@ defaults_domains:
   portfolio:               "{{primary_domain}}"
   roulette-wheel:          "roulette.{{primary_domain}}"
   snipe_it:                "inventory.{{primary_domain}}"
+  sphinx:                  "docs.{{primary_domain}}"
   taiga:                   "kanban.{{primary_domain}}"
   yourls:                  "s.{{primary_domain}}"
   # ATTENTION: Will be owerwritten by the values in domains. Not merged.

group_vars/all/07_applications.yml

@@ -547,6 +547,13 @@ defaults_applications:
     database:
       central_storage:  True    # Activate Central Database Storage
 
+  ## Sphinx
+  sphinx:
+    version:            "3.9-slim"                        # Use latest docker image
+    volumes:
+      source_dir:       "{ansible_playbook_dir}"          # Path from which sphinx reads the documentation
+      
+
   ## Taiga
   taiga:
     version:           "latest"

group_vars/all/09_ports.yml

@@ -46,6 +46,7 @@ ports:
       ldap:           8033
       phpmyadmin:     8034
       snipe_it:       8035
+      sphinx:         8036
       bigbluebutton:  48087 # This port is predefined by bbb. @todo Try to change this to a 8XXX port
   # Ports which are exposed to the World Wide Web
   public:

group_vars/all/10_networks.yml

@@ -70,6 +70,8 @@ defaults_networks:
       subnet: 192.168.102.192/28
     discourse:
       subnet: 192.168.102.208/28
+    sphinx:
+      subnet: 192.168.102.224/28
     # /24 Networks / 254 Usable Clients
     bigbluebutton:
       subnet: 10.7.7.0/24 # This variable does not have an impact. It's just there for documentation reasons, because this network is used in bbb
@@ -79,5 +81,4 @@ defaults_networks:
       subnet: 192.168.201.0/24
     central_ldap:
       subnet: 192.168.202.0/24
-
   

playbook.servers.yml

@@ -230,6 +230,12 @@
   roles:
    -  role: docker-snipe_it
 
+- name: setup sphinx
+  hosts: sphinx
+  become: true
+  roles:
+   -  role: docker-sphinx
+
 # Native Webserver Roles
 - name: setup nginx-serve-htmls
   hosts: nginx-serve-htmls

roles/docker-portfolio/templates/config.yaml.j2

@@ -387,6 +387,19 @@ cards:
   link_text: "Soar with Bluesky Today!"
 
 {% endif %}
+
+{% if "sphinx" in group_names %}
+
+- icon:
+    class: "fa-solid fa-book"
+  title: "Documentation"
+  text: "Unlock comprehensive insights with our extensive documentation. Explore guides, tutorials, and support resources designed to help you navigate our software effortlessly."
+  url: https://{{domains.sphinx}}
+  link_text: "Explore Documentation Now!"
+
+{% endif %}
+
+
 {% if "phpmyadmin" in group_names %}
 
 - icon: 
@@ -688,6 +701,13 @@ navigation:
           icon:
             class: fa-brands fa-github
           url: https://s.veen.world/githubsponsors
+{% if "spinx" in group_names %}   
+    - name: Documentation & Support
+      description: Access our comprehensive documentation and support resources to help you get the most out of the software.
+      icon:
+        class: fas fa-book
+      url: https://{{domains.sphinx}}
+{% endif %}
     - name: Imprint
       description: Check out the imprint information
       icon:

roles/docker-sphinx/README.md

@@ -0,0 +1,21 @@
+# Sphinx Documentation Role
+
+## Description
+
+This Ansible role automates the building and deployment of Sphinx documentation using Docker. It pulls the CyMaIS repository, builds the documentation with Sphinx, and serves the generated HTML files via a lightweight HTTP server.
+
+## 📌 Overview
+
+Optimized for containerized environments, this role ensures that your documentation is consistently built and deployed with minimal manual intervention. It leverages Docker and Docker Compose for reproducible builds, enabling dynamic configuration of source and output directories.
+
+## Purpose
+
+The primary purpose of this role is to streamline the documentation workflow for your project. By automating the Sphinx build process and containerizing the deployment, the role reduces manual overhead and ensures that the latest documentation is always available for review and distribution.
+
+## Features
+
+- **Automated Build:** Triggers the Sphinx build process automatically via a Makefile.
+- **Docker Integration:** Uses Docker and Docker Compose to containerize the documentation build and serve process.
+- **Dynamic Configuration:** Allows customizable source and output directories through variables.
+- **Consistent Deployment:** Ensures that the generated documentation is served reliably with minimal configuration.
+- **Easy Updates:** Pulls the latest version of the project repository and rebuilds the documentation seamlessly.

roles/docker-sphinx/meta/main.yml

@@ -0,0 +1,28 @@
+---
+galaxy_info:
+  author: "Marko Pjevac, Kevin Veen-Birkenbach"
+  description: "Automates building and serving Sphinx documentation. Ideal for any project, it pulls your repository, builds the docs, and serves them with ease."
+  license: "CyMaIS NonCommercial License (CNCL)"
+  license_url: "https://s.veen.world/cncl"
+  company: | 
+    Kevin Veen-Birkenbach
+    Consulting & Coaching Solutions
+    https://www.veen.world
+  min_ansible_version: "2.9"
+  platforms:
+    - name: Docker
+      versions:
+        - all
+    - name: Linux
+      versions:
+        - all
+  galaxy_tags:
+    - documentation
+    - sphinx
+    - docker
+    - automation
+    - deployment
+  repository: "https://s.veen.world/cymais"
+  issue_tracker_url: "https://s.veen.world/cymaisissues"
+  documentation: "https://s.veen.world/cymais"
+dependencies: []

roles/docker-sphinx/tasks/main.yml

@@ -0,0 +1,31 @@
+---
+# Docker Routines
+- name: "include docker-compose role"
+  include_role: 
+    name: docker-compose
+
+- name: pull cymais repository
+  git:
+    repo: "{{ repository_address_cymais }}"
+    dest: "{{ host_cymais_volume_dir_absolute }}"
+    update: yes
+  notify: docker compose project setup
+  become: true
+
+- name: "include role nginx-domain-setup for {{application_id}}"
+  include_role:
+    name: nginx-domain-setup
+  vars:
+    domain: 	"{{ domains[application_id] }}"
+    http_port: 	"{{ ports.localhost.http[application_id] }}"
+
+- name: "create {{ sphinx_docker_file }}"
+  template:
+    src: "Dockerfile.j2"
+    dest: "{{ sphinx_docker_file }}"
+    mode: '770'
+    force: yes
+  notify: docker compose project setup
+
+- name: "copy docker-compose.yml and env file"
+  include_tasks: copy-docker-compose-and-env.yml

roles/docker-sphinx/templates/Dockerfile.j2

@@ -0,0 +1,22 @@
+FROM python:{{applications[application_id].version}}
+
+# Install required packages including 'make'
+RUN apt-get update && apt-get install -y make
+
+# Set the working directory
+WORKDIR {{docker_app_dir}}
+
+# Copy the project files into the container
+COPY {{host_cymais_volume_dir_relative}} {{docker_app_dir}}
+
+# Install Python packages via requirements.txt
+RUN cd {{docker_sphinx_dir}} && pip install --upgrade pip && pip install -r requirements.txt
+
+# Build the HTML documentation using Sphinx with the defined directories
+RUN cd {{docker_sphinx_dir}} && make html
+
+# Expose port 8000 where the HTTP server will run
+EXPOSE 8000
+
+# Start a simple HTTP server to serve the built documentation
+CMD ["python", "-m", "http.server", "8000", "--directory", "${BUILD_DIR}"]

roles/docker-sphinx/templates/docker-compose.yml.j2

@@ -0,0 +1,13 @@
+services:
+  application:
+    build: .
+    ports:
+      - "127.0.0.1:{{ports.localhost.http[application_id]}}:8000"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://127.0.0.1:8000"]
+      interval: 1m
+      timeout: 10s
+      retries: 3
+{% include 'templates/docker/container/networks.yml.j2' %}
+
+{% include 'templates/docker/compose/networks.yml.j2' %}

roles/docker-sphinx/templates/env.j2

@@ -0,0 +1,2 @@
+SOURCE_DIR={{docker_source_dir}}
+BUILD_DIR={{docker_output_dir}}

roles/docker-sphinx/vars/main.yml

@@ -0,0 +1,13 @@
+application_id:               "sphinx"
+
+repository_address_cymais:    "https://github.com/kevinveenbirkenbach/cymais.git"     # Repository address to pull cymais from
+
+host_cymais_volume_dir_absolute:  "{{docker_compose.directories.volumes}}cymais/"     # Place where the cymais repository is stored on the host
+host_cymais_volume_dir_relative:  "volumes/cymais/"                                   # Place where the cymais repository is stored on the host
+
+docker_app_dir:               "/app/"                                                 # Folder in which the application is running
+docker_source_dir:            "{{docker_app_dir}}"                                    # Folder which is used to be screened
+docker_output_dir:            "/docs/"                                                 # Folder to which the output is fuuuucking putted!
+docker_sphinx_dir:            "{{docker_app_dir}}/sphinx/"                             # Folder which contains the sphinxs makefile and logic
+
+sphinx_docker_file:           "{{ docker_compose.directories.instance }}/Dockerfile"

roles/user-administrator/meta/main.yml

@@ -24,5 +24,4 @@ galaxy_info:
   issue_tracker_url: "https://s.veen.world/cymaisissues"
   documentation: "https://s.veen.world/cymais"
 dependencies:
-  - sudo
-  - user
+  - sudo

roles/user-root/meta/main.yml

@@ -23,5 +23,3 @@ galaxy_info:
   repository: "https://s.veen.world/cymais"
   issue_tracker_url: "https://s.veen.world/cymaisissues"
   documentation: "https://s.veen.world/cymais"
-dependencies:
-  - user

sphinx/Makefile

@@ -5,16 +5,16 @@
 # from the environment for the first two.
 SPHINXOPTS    ?= -c .
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = ../
-BUILDDIR      = ../docs
+SOURCE_DIR     = ../
+BUILD_DIR      = ../docs
 
 # Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M help "$(SOURCE_DIR)" "$(BUILD_DIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help install Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCE_DIR)" "$(BUILD_DIR)" $(SPHINXOPTS) $(O)

templates/docker/compose/networks.yml.j2

@@ -1,6 +1,6 @@
 {# This template needs to be included in docker-compose.yml #}
 networks:
-{% if applications[application_id].database.central_storage | bool and database_type is defined %}
+{% if applications | get_database_central_storage(application_id) | bool and database_type is defined %}
   central_{{ database_type }}:
     external: true
 {% endif %}

templates/docker/container/networks.yml.j2

@@ -1,6 +1,6 @@
 {# This template needs to be included in docker-compose.yml containers #}
     networks:
-{% if applications[application_id].database.central_storage | bool and database_type is defined %}
+{% if applications | get_database_central_storage(application_id) | bool and database_type is defined %}
       central_{{ database_type }}:
 {% endif %}
 {% if applications[application_id].get('ldap', {}).get('enabled', false)|bool and applications.ldap.openldap.network.local|bool %}