kevinveenbirkenbach/computer-playbook
1
0
Fork 0
mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2025-10-31 18:29:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

Redrafted Sphinx for CyMaIS

Browse Source
This commit is contained in:
Kevin Veen-Birkenbach
2025-03-21 13:48:42 +01:00
parent fe85d4bd37
commit c402583f2b
16 changed files with 159 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
05_CUSTOMER_GUIDE.md
View File

@@ -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

22
06_ADMINISTRATOR_GUIDE.md
View File

@@ -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.

19
10_DEVELOPER_GUIDE.rst
View File

@@ -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 <https://github.com/kevinveenbirkenbach/cymais/tree/master/roles>`_
### 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.

13
README.md
View File

@@ -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).
```

7
docs/.gitignore vendored
View File

@@ -1,5 +1,8 @@
assets/img/*
!assets/img/.gitkeep
build/*
output/*
!output/.gitkeep
generated/*
!generated/.gitkeep
!generated/.gitkeep
requirements/*
!requirements/.gitkeep

20
roles/docker-sphinx/files/Dockerfile → docs/Dockerfile
View File

@@ -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/"

49
docs/Makefile
View File

@@ -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)

2
docs/generators/ansible_roles.py
View File

@@ -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."""

0
docs/output/.gitkeep Normal file
View File

9
docs/requirements.txt
View File

@@ -1,9 +0,0 @@
myst-parser
sphinx
sphinxawesome-theme
docutils
sphinx-jinja
sphinxcontrib-yaml
pathspec
markdown2
pandoc

13
docs/requirements.yml Normal file
View File

@@ -0,0 +1,13 @@
apt:
make
curl
pandoc
pip:
myst-parser
sphinx
sphinxawesome-theme
docutils
sphinx-jinja
sphinxcontrib-yaml
pathspec
markdown2

0
docs/requirements/.gitkeep Normal file
View File

38
docs/scripts/extract-requirements.sh Normal file
View File

@@ -0,0 +1,38 @@
#!/bin/bash
# Check if correct number of arguments is given
if [[ $# -ne 3 ]]; then
echo "Usage: $0 <input_file> <apt_output_file> <pip_output_file>"
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"

6
roles/docker-sphinx/tasks/main.yml
View File

@@ -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

10
roles/docker-sphinx/templates/docker-compose.yml.j2
View File

@@ -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:

5
roles/docker-sphinx/vars/main.yml
View File

@@ -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
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