From c402583f2b6bc2f467b61b2b3abf4d809105b61e Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Fri, 21 Mar 2025 13:48:42 +0100 Subject: [PATCH] Redrafted Sphinx for CyMaIS --- 05_CUSTOMER_GUIDE.md | 11 +++-- 06_ADMINISTRATOR_GUIDE.md | 22 +++++++++ 10_DEVELOPER_GUIDE.rst | 19 +++---- README.md | 13 ++--- docs/.gitignore | 7 ++- .../docker-sphinx/files => docs}/Dockerfile | 20 +++++--- docs/Makefile | 49 +++++++++++++------ docs/generators/ansible_roles.py | 2 +- docs/output/.gitkeep | 0 docs/requirements.txt | 9 ---- docs/requirements.yml | 13 +++++ docs/requirements/.gitkeep | 0 docs/scripts/extract-requirements.sh | 38 ++++++++++++++ roles/docker-sphinx/tasks/main.yml | 6 +-- .../templates/docker-compose.yml.j2 | 10 ++-- roles/docker-sphinx/vars/main.yml | 5 +- 16 files changed, 159 insertions(+), 65 deletions(-) rename {roles/docker-sphinx/files => docs}/Dockerfile (53%) create mode 100644 docs/output/.gitkeep delete mode 100644 docs/requirements.txt create mode 100644 docs/requirements.yml create mode 100644 docs/requirements/.gitkeep create mode 100644 docs/scripts/extract-requirements.sh diff --git a/05_CUSTOMER_GUIDE.md b/05_CUSTOMER_GUIDE.md index 36dbb8df..5608f6b1 100644 --- a/05_CUSTOMER_GUIDE.md +++ b/05_CUSTOMER_GUIDE.md @@ -2,12 +2,13 @@ Are you looking for a **reliable IT infrastructure** for your business or organization? **CyMaIS** is here to help! -### Who Can Benefit? 🎯 -βœ… **Small & Medium Businesses** - Automate IT setup & security -βœ… **Enterprises** - Scale deployments with modular architecture -βœ… **NGOs & Organizations** - Secure, cost-effective infrastructure solutions +## Who Can Benefit? 🎯 +βœ… **Small & Medium Businesses** - IT infrastructure with everything included what you need. E.g. data clouds, mailservers, vpn's, homepages, documentation tools, etc. +βœ… **Enterprises** - Scale the solutions for Small & Medium Businesses up for an unlimeted amount of users +βœ… **NGOs & Organizations** - Secure, cost-effective infrastructure solutions on Open Source Base +βœ… **Journalists & Content Creators** - Host your content on your own servers, share it via the Fediverse and avoid cencorship -### Why Choose CyMaIS? πŸš€ +## Why Choose CyMaIS? πŸš€ - **Fast Deployment** - Get your IT setup running in minutes - **Security First** - Encrypted backups, 2FA, and secure logins - **Scalable & Customizable** - Adapts to your specific needs diff --git a/06_ADMINISTRATOR_GUIDE.md b/06_ADMINISTRATOR_GUIDE.md index e69de29b..c1618c01 100644 --- a/06_ADMINISTRATOR_GUIDE.md +++ b/06_ADMINISTRATOR_GUIDE.md @@ -0,0 +1,22 @@ +# Administrator Guide πŸ–₯️ + +This guide is for **system administrators** who are deploying and managing CyMaIS infrastructure. + +## Setting Up CyMaIS πŸ—οΈ +Follow these guides to install and configure CyMaIS: +- [Setup Guide](07_SETUP_GUIDE.md) +- [Configuration Guide](08_CONFIGURATION.md) +- [Deployment Guide](09_DEPLOY.md) + +## Key Responsibilities πŸ”§ +- **User Management** - Configure LDAP, Keycloak, and user permissions. +- **Security & Backups** - Set up `backup-remote-to-local`, `backup-data-to-usb`, and `system-security` roles. +- **Application Hosting** - Deploy services like `Nextcloud`, `Matrix`, `Gitea`, and more. +- **Networking & VPN** - Configure `WireGuard`, `OpenVPN`, and `Nginx Reverse Proxy`. + +## Managing & Updating CyMaIS πŸ”„ +- Regularly update services using `update-docker`, `update-pacman`, or `update-apt`. +- Monitor system health with `health-btrfs`, `health-nginx`, and `health-docker-container`. +- Automate system maintenance with `system-maintenance-lock`, `cleanup-backups-service`, and `restart-docker`. + +For more details, refer to the specific guides above. \ No newline at end of file diff --git a/10_DEVELOPER_GUIDE.rst b/10_DEVELOPER_GUIDE.rst index b3710c6e..fea09d30 100644 --- a/10_DEVELOPER_GUIDE.rst +++ b/10_DEVELOPER_GUIDE.rst @@ -3,12 +3,6 @@ Developer Guide Welcome to the **CyMaIS Developer Guide**! This guide provides essential information for developers who want to contribute to the CyMaIS open-source project. -Getting Started ---------------- -To understand the overall structure of CyMaIS, start by reviewing the available YAML configuration files: - -- :doc:`docs/generated/yaml_index` - Explore CyMaIS Solutions ------------------------ CyMaIS offers various solutions for IT infrastructure automation. Learn more about the available applications: @@ -18,17 +12,24 @@ CyMaIS offers various solutions for IT infrastructure automation. Learn more abo For Developers -------------- -### Understanding Ansible Roles + +Understanding Ansible Roles +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + CyMaIS is powered by **Ansible** roles to automate deployments. Developers can explore the technical details of our roles here: - :doc:`roles/ansible_role_glosar` -### Contributing to CyMaIS +Contributing to CyMaIS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Want to contribute to the project or explore the source code? Check out our **GitHub repository**: - `CyMaIS GitHub Repository `_ -### Contribution Guidelines +Contribution Guidelines +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + 1. **Fork the Repository** – Start by forking the CyMaIS repository. 2. **Create a New Branch** – Make changes in a dedicated branch. 3. **Follow Coding Standards** – Ensure your code is well-documented and follows best practices. diff --git a/README.md b/README.md index 2722f88a..1cdd689e 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,19 @@ -# README.md - # CyMaIS - Cyber Master Infrastructure Solution πŸš€ +[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-blue?logo=github)](https://github.com/sponsors/kevinveenbirkenbach) [![Patreon](https://img.shields.io/badge/Support-Patreon-orange?logo=patreon)](https://www.patreon.com/c/kevinveenbirkenbach) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20Coffee-Funding-yellow?logo=buymeacoffee)](https://buymeacoffee.com/kevinveenbirkenbach) [![PayPal](https://img.shields.io/badge/Donate-PayPal-blue?logo=paypal)](https://s.veen.world/paypaldonate) + Welcome to **CyMaIS (Cyber Master Infrastructure Solution)**, a powerful automation framework that simplifies IT infrastructure setup and management. Whether you are an **end-user** looking to access cloud services securely or an **administrator** responsible for deploying and maintaining infrastructure, CyMaIS provides a seamless and secure solution. ![CyMaIS Logo](assets/img/logo.png) ## What is CyMaIS? πŸ“Œ -CyMaIS leverages **Docker, Linux, and Ansible** to provide an automated and modular infrastructure solution. With more then **148 pre-configured roles**, it supports a wide range of applications, from cloud services to local server management and desktop workstation setups. +CyMaIS leverages **Docker, Linux, and Ansible** to provide an automated and modular infrastructure solution. With more then **150 pre-configured roles**, it supports a wide range of applications, from cloud services to local server management and desktop workstation setups. ## Guides πŸ“– - **[User Guide](04_USER_GUIDE.md)** - For end-users accessing cloud apps like Nextcloud, Matrix, and more. - **[Administrator Guide](06_ADMINISTRATOR_GUIDE.md)** - For system administrators deploying CyMaIS. +- **[Customer Guide](05_CUSTOMER_GUIDE.md)** - For customers which are interested in an infrastructure setup ## Key Features 🎯 - **Automated IT deployment** πŸ“¦ - Pre-built roles for server and PC setups @@ -21,6 +22,8 @@ CyMaIS leverages **Docker, Linux, and Ansible** to provide an automated and modu - **Backup & recovery solutions** πŸ’Ύ - Automate data security and prevent loss - **Infrastructure monitoring & maintenance** πŸ“Š - Keep your system running optimally +More informations about the features you will find [here](01_FEATURES.md). + ## Get Started πŸš€ 1. **Install CyMaIS** via [Kevin's Package Manager](https://github.com/kevinveenbirkenbach/package-manager) 2. **Setup CyMaIS** using: @@ -30,6 +33,4 @@ CyMaIS leverages **Docker, Linux, and Ansible** to provide an automated and modu 3. **Explore Commands** with: ```sh cymais --help - ``` - -For detailed setup instructions, check out the [Setup Guide](07_SETUP_GUIDE.md) and [Configuration Guide](08_CONFIGURATION.md). + ``` \ No newline at end of file diff --git a/docs/.gitignore b/docs/.gitignore index fb15ed80..278e4fde 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,5 +1,8 @@ assets/img/* !assets/img/.gitkeep -build/* +output/* +!output/.gitkeep generated/* -!generated/.gitkeep \ No newline at end of file +!generated/.gitkeep +requirements/* +!requirements/.gitkeep \ No newline at end of file diff --git a/roles/docker-sphinx/files/Dockerfile b/docs/Dockerfile similarity index 53% rename from roles/docker-sphinx/files/Dockerfile rename to docs/Dockerfile index b79265a3..a58f0b71 100644 --- a/roles/docker-sphinx/files/Dockerfile +++ b/docs/Dockerfile @@ -2,26 +2,30 @@ ARG DOCKER_PYTHON_VERSION FROM python:${DOCKER_PYTHON_VERSION} ARG SPHINX_SOURCE_DIR -ARG SPHINX_BUILD_DIR +ARG SPHINX_OUTPUT_DIR ARG SPHINX_EXEC_DIR -ARG SPHINX_APP_DIR +ARG SPHINX_DOCKER_EXEC_DIR ARG SPHINX_SOURCE_DIR_RELATIVE # Set the environment variables so they are available during build for Makefile ENV SPHINX_SOURCE_DIR=${SPHINX_SOURCE_DIR} -ENV SPHINX_BUILD_DIR=${SPHINX_BUILD_DIR} +ENV SPHINX_OUTPUT_DIR=${SPHINX_OUTPUT_DIR} +ENV SPHINX_REQUIREMENTS_DIR=${SPHINX_EXEC_DIR}/requirements + +# Build the requirement files +RUN cd ${SPHINX_EXEC_DIR} && make requirements # Install required packages -RUN apt-get update && apt-get install -y make curl +RUN apt-get update && xargs -a ${SPHINX_REQUIREMENTS_DIR}/apt.txt apt install -y # Set the working directory -WORKDIR ${SPHINX_APP_DIR} +WORKDIR ${SPHINX_DOCKER_EXEC_DIR} # Copy the project files into the container -COPY ${SPHINX_SOURCE_DIR_RELATIVE} ${SPHINX_APP_DIR} +COPY ${SPHINX_SOURCE_DIR_RELATIVE} ${SPHINX_DOCKER_EXEC_DIR} # Install Python packages via requirements.txt -RUN cd ${SPHINX_EXEC_DIR} && pip install --upgrade pip && pip install -r requirements.txt +RUN pip install --upgrade pip && pip install -r ${SPHINX_REQUIREMENTS_DIR}/pip.txt # Build the HTML documentation using Sphinx with the defined directories RUN cd ${SPHINX_EXEC_DIR} && make html @@ -30,4 +34,4 @@ RUN cd ${SPHINX_EXEC_DIR} && make html EXPOSE 8000 # Start a simple HTTP server to serve the built documentation -CMD python -m http.server 8000 --directory "${SPHINX_BUILD_DIR}html/" +CMD python -m http.server 8000 --directory "${SPHINX_OUTPUT_DIR}html/" diff --git a/docs/Makefile b/docs/Makefile index ae41b7bc..91249f33 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,14 +1,33 @@ -# Minimal Makefile for Sphinx documentation -# -# You can set these variables from the command line, and also -# from the environment -SPHINXOPTS ?= -c . -SPHINXBUILD ?= sphinx-build -SPHINX_SOURCE_DIR ?= ../ -SPHINX_BUILD_DIR ?= ./build -SPHINX_GENERATED_DIR = $(SPHINX_BUILD_DIR)/../generated +# PARAMETER (with default values) -.PHONY: help install copy-images apidoc remove-generated html generate Makefile +# Directory which cointains the Makefile +SPHINX_EXEC_DIR ?= . + +# Directory from which the sources will be read +SPHINX_SOURCE_DIR ?= ../ + +# Directory which contains the builded files +SPHINX_OUTPUT_DIR ?= ./output + +# Args parsed to the sphinx-build command +SPHINXOPTS ?= -c $(SPHINX_EXEC_DIR) + +# CONSTANTS + +# Sphinx build command +SPHINX_BUILD_COMMAND = sphinx-build + +# Directory which contains the auto generated files +SPHINX_GENERATED_DIR = $(SPHINX_OUTPUT_DIR)/../generated + +# Directory which contains the extracted requirement files +SPHINX_REQUIREMENTS_DIR = $(SPHINX_EXEC_DIR)/requirements + +.PHONY: help install copy-images apidoc remove-generated html generate extract-requirements Makefile + +extract-requirements: + @echo "Creating requirement files" + bash ./scripts/extract-requirements.sh "$(SPHINX_EXEC_DIR)/requirements.yml" "$(SPHINX_REQUIREMENTS_DIR)/apt.txt" "$(SPHINX_REQUIREMENTS_DIR)/pip.txt" # Copy images before running any Sphinx command (except for help) copy-images: @@ -42,20 +61,20 @@ remove-generated: - find $(SPHINX_GENERATED_DIR)/ -type f ! -name '.gitkeep' -delete help: - @$(SPHINXBUILD) -M help "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) $(O) + @$(SPHINX_BUILD_COMMAND) -M help "$(SPHINX_SOURCE_DIR)" "$(SPHINX_OUTPUT_DIR)" $(SPHINXOPTS) $(O) html: copy-images generate @echo "Building Sphinx documentation..." - $(SPHINXBUILD) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) + $(SPHINX_BUILD_COMMAND) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_OUTPUT_DIR)" $(SPHINXOPTS) just-html: - @$(SPHINXBUILD) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) + @$(SPHINX_BUILD_COMMAND) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_OUTPUT_DIR)" $(SPHINXOPTS) clean: remove-generated - @$(SPHINXBUILD) -M clean "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) $(O) + @$(SPHINX_BUILD_COMMAND) -M clean "$(SPHINX_SOURCE_DIR)" "$(SPHINX_OUTPUT_DIR)" $(SPHINXOPTS) $(O) # 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 $@ "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) $(O) + @$(SPHINX_BUILD_COMMAND) -M $@ "$(SPHINX_SOURCE_DIR)" "$(SPHINX_OUTPUT_DIR)" $(SPHINXOPTS) $(O) diff --git a/docs/generators/ansible_roles.py b/docs/generators/ansible_roles.py index 78027d5b..293fcd84 100644 --- a/docs/generators/ansible_roles.py +++ b/docs/generators/ansible_roles.py @@ -15,7 +15,7 @@ def convert_md_to_rst(md_content): return result.stdout.decode("utf-8") except subprocess.CalledProcessError as e: print("Error converting Markdown to reStructuredText:", e) - return md_content # Falls Pandoc fehlschlΓ€gt, nutze das Original als Fallback + return md_content def generate_ansible_roles_doc(roles_dir, output_dir): """Generates reStructuredText documentation for Ansible roles.""" diff --git a/docs/output/.gitkeep b/docs/output/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 56564bc5..00000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,9 +0,0 @@ -myst-parser -sphinx -sphinxawesome-theme -docutils -sphinx-jinja -sphinxcontrib-yaml -pathspec -markdown2 -pandoc \ No newline at end of file diff --git a/docs/requirements.yml b/docs/requirements.yml new file mode 100644 index 00000000..261a9cb8 --- /dev/null +++ b/docs/requirements.yml @@ -0,0 +1,13 @@ +apt: + make + curl + pandoc +pip: + myst-parser + sphinx + sphinxawesome-theme + docutils + sphinx-jinja + sphinxcontrib-yaml + pathspec + markdown2 \ No newline at end of file diff --git a/docs/requirements/.gitkeep b/docs/requirements/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/scripts/extract-requirements.sh b/docs/scripts/extract-requirements.sh new file mode 100644 index 00000000..44397439 --- /dev/null +++ b/docs/scripts/extract-requirements.sh @@ -0,0 +1,38 @@ +#!/bin/bash + +# Check if correct number of arguments is given +if [[ $# -ne 3 ]]; then + echo "Usage: $0 " + echo "Input: $0 <$1> <$2> <$3>" + exit 1 +fi + +input_file="$1" +apt_file="$2" +pip_file="$3" + +# Clear the output files +> "$apt_file" +> "$pip_file" + +current_section="" + +while IFS= read -r line; do + [[ -z "$line" ]] && continue + + if [[ "$line" == apt:* ]]; then + current_section="apt" + continue + elif [[ "$line" == pip:* ]]; then + current_section="pip" + continue + fi + + package=$(echo "$line" | sed 's/^[[:space:]]*//') + + if [[ "$current_section" == "apt" ]]; then + echo "$package" >> "$apt_file" + elif [[ "$current_section" == "pip" ]]; then + echo "$package" >> "$pip_file" + fi +done < "$input_file" \ No newline at end of file diff --git a/roles/docker-sphinx/tasks/main.yml b/roles/docker-sphinx/tasks/main.yml index 57e6985a..88c76c7a 100644 --- a/roles/docker-sphinx/tasks/main.yml +++ b/roles/docker-sphinx/tasks/main.yml @@ -26,10 +26,10 @@ domain: "{{ domains[application_id] }}" http_port: "{{ ports.localhost.http[application_id] }}" -- name: "create {{ sphinx_docker_file }}" +- name: "create {{ sphinx_host_dockerfile }}" copy: - src: "Dockerfile" - dest: "{{ sphinx_docker_file }}" + src: "{{ sphinx_control_node_dockerfile }}" + dest: "{{ sphinx_host_dockerfile }}" mode: '770' force: yes notify: docker compose project build and setup diff --git a/roles/docker-sphinx/templates/docker-compose.yml.j2 b/roles/docker-sphinx/templates/docker-compose.yml.j2 index 80aa411d..ad8cc375 100644 --- a/roles/docker-sphinx/templates/docker-compose.yml.j2 +++ b/roles/docker-sphinx/templates/docker-compose.yml.j2 @@ -4,12 +4,12 @@ services: context: . dockerfile: Dockerfile args: - SPHINX_SOURCE_DIR: {{docker_source_dir}} - SPHINX_BUILD_DIR: {{docker_output_dir}} - SPHINX_EXEC_DIR: {{docker_exec_dir}} - SPHINX_APP_DIR: {{docker_app_dir}} + SPHINX_SOURCE_DIR: {{docker_source_dir}} + SPHINX_OUTPUT_DIR: {{docker_output_dir}} + SPHINX_EXEC_DIR: {{docker_exec_dir}} + SPHINX_DOCKER_EXEC_DIR: {{docker_app_dir}} SPHINX_SOURCE_DIR_RELATIVE: {{host_sphinx_source_dir_relative}} - DOCKER_PYTHON_VERSION: {{applications[application_id].version}} + DOCKER_PYTHON_VERSION: {{applications[application_id].version}} ports: - "127.0.0.1:{{ports.localhost.http[application_id]}}:8000" healthcheck: diff --git a/roles/docker-sphinx/vars/main.yml b/roles/docker-sphinx/vars/main.yml index a87c7733..f60ec0fd 100644 --- a/roles/docker-sphinx/vars/main.yml +++ b/roles/docker-sphinx/vars/main.yml @@ -5,7 +5,8 @@ host_sphinx_source_dir_absolute: "{{docker_compose.directories.instance}}{{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_output_dir: "/output/" # Folder to which the output is fuuuucking putted! docker_exec_dir: "{{docker_app_dir}}{{applications.sphinx.sphinx_exec_dir_relative}}" # Folder which contains the sphinxs makefile and logic -sphinx_docker_file: "{{ docker_compose.directories.instance }}Dockerfile" # Path to the Dockerfile to build sphinx \ No newline at end of file +sphinx_host_dockerfile: "{{ docker_compose.directories.instance }}Dockerfile" # Path to the Dockerfile to build sphinx +sphinx_control_node_dockerfile: "{{ [ playbook_dir, 'docs/Dockerfile' ] | path_join }}" # Path to the Dockerfile on the control node \ No newline at end of file