mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2025-03-27 03:33:31 +01:00
Optimized READMEs
This commit is contained in:
parent
24cb08b358
commit
1620a3f7ed
@ -1,10 +0,0 @@
|
||||
# Installation
|
||||
|
||||
CyMaIS can be easily installed on your local host using [Kevin's Package Manager](https://github.com/kevinveenbirkenbach/package-manager). Once you have the package manager set up, simply run:
|
||||
|
||||
```bash
|
||||
pkgmgr clone cymais # downloads the cymais repository
|
||||
pkgmgr install cymais # installs cymais on your local host
|
||||
```
|
||||
|
||||
This command will install CyMaIS on your system with the alias **cymais**.
|
||||
26
03_SETUP.md
Normal file
26
03_SETUP.md
Normal file
@ -0,0 +1,26 @@
|
||||
# Setup
|
||||
|
||||
To setup CyMaIS follow this steps:
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you setup CyMaIS you need to install [Kevin's Package Manager](https://github.com/kevinveenbirkenbach/package-manager).
|
||||
Follow the installation instruction descriped [here](https://github.com/kevinveenbirkenbach/package-manager)
|
||||
|
||||
## Setup CyMaIS
|
||||
|
||||
To setup CyMaIS execute:
|
||||
|
||||
```bash
|
||||
pkgmgr setup cymais
|
||||
```
|
||||
|
||||
This command will setup CyMaIS on your system with the alias **cymais**.
|
||||
|
||||
## Get Help
|
||||
|
||||
After you setuped CyMaIS you can recieve more help by executing:
|
||||
|
||||
```bash
|
||||
cymais --help
|
||||
```
|
||||
15
README.md
15
README.md
@ -22,16 +22,19 @@ Explore the key documents for detailed information about CyMaIS:
|
||||
- [Vision](02_VISION.md)
|
||||
*Learn about the vision and long-term goals behind CyMaIS.*
|
||||
|
||||
- [Installation](03_INSTALLATION.md)
|
||||
*Step-by-step instructions for installing the system and its dependencies.*
|
||||
- [Setup](03_SETUP.md)
|
||||
*Step-by-step instructions for seting up the system and its dependencies.*
|
||||
|
||||
- [Setup](04_SETUP.md)
|
||||
*Detailed procedures for configuring and deploying CyMaIS.*
|
||||
- [Configuration](group_vars/README.md)
|
||||
*Detailed procedures for configuring CyMaIS.*
|
||||
|
||||
- [Enterprise](05_ENTERPRISE.md)
|
||||
- [Deploy](tasks/README.md)
|
||||
*Detailed procedures for deploying CyMaIS tp your servers*
|
||||
|
||||
- [Enterprise](04_ENTERPRISE.md)
|
||||
*Guidance and best practices for enterprise deployments.*
|
||||
|
||||
- [Donate](06_DONATE.md)
|
||||
- [Donate](05_DONATE.md)
|
||||
*Information on how to support and donate to the CyMaIS project.*
|
||||
|
||||
- [Code of Conduct](CODE_OF_CONDUCT.md)
|
||||
|
||||
@ -90,24 +90,7 @@ docker exec -it openldap sh -c 'ldapsearch -x -D "cn=administrator,dc=flock,dc=t
|
||||
- ❌ If results still exist, some entries were not removed.
|
||||
|
||||
|
||||
---
|
||||
|
||||
#### Manually Create the Base DN (dc=cymais,dc=cloud)
|
||||
Before importing the full LDIF file, you need to explicitly create the base DN (dc=cymais,dc=cloud) first.
|
||||
|
||||
#### Create base.ldif for dc=cymais,dc=cloud
|
||||
Save this LDIF content into a file:
|
||||
```sh
|
||||
dn: dc=cymais,dc=cloud
|
||||
objectClass: top
|
||||
objectClass: domain
|
||||
dc: cymais
|
||||
```
|
||||
#### Add the Base DN to LDAP
|
||||
Run the following command to create the base DN before importing other entries:
|
||||
```sh
|
||||
cat base.ldif | docker exec -i openldap sh -c 'ldapadd -x -D "cn=admin,dc=cymais,dc=cloud" -w "$LDAP_ADMIN_PASSWORD"'
|
||||
```
|
||||
#### Create new_database.ldif
|
||||
|
||||
docker exec -i openldap ldapadd -Y EXTERNAL -H ldapi:/// -f /dev/stdin < new_database.ldif
|
||||
|
||||
|
||||
19
roles/nginx-docker-cert-deploy/CONFIGURATION.md
Normal file
19
roles/nginx-docker-cert-deploy/CONFIGURATION.md
Normal file
@ -0,0 +1,19 @@
|
||||
# Configuration Options 📋
|
||||
|
||||
## One Wildcard Certificate for All Subdomains
|
||||
|
||||
By default, each subdomain gets its own certificate. You can **enable a wildcard certificate** by setting:
|
||||
|
||||
```yaml
|
||||
enable_wildcard_certificate: true
|
||||
```
|
||||
|
||||
## Pros & Cons of a Wildcard Certificate
|
||||
### Pros
|
||||
- ✅ **Improves performance** by reducing TLS handshakes.
|
||||
- ✅ **Simplifies certificate management** (one cert for all subdomains).
|
||||
### Cons
|
||||
- ⚠ **Requires manual DNS challenge setup** for Let's Encrypt.
|
||||
- ⚠ **Needs additional configuration for automation** (see below).
|
||||
|
||||
If enabled, update your inventory file and follow the **[manual wildcard certificate setup](SETUP.md)**.
|
||||
@ -17,25 +17,6 @@ This Ansible role simplifies the deployment of **Let's Encrypt certificates** in
|
||||
|
||||
---
|
||||
|
||||
## 📋 **Configuration Options**
|
||||
|
||||
### 🔹 **One Wildcard Certificate for All Subdomains**
|
||||
By default, each subdomain gets its own certificate. You can **enable a wildcard certificate** by setting:
|
||||
|
||||
```yaml
|
||||
enable_wildcard_certificate: true
|
||||
```
|
||||
|
||||
📌 **Pros & Cons of a Wildcard Certificate:**
|
||||
✅ **Improves performance** by reducing TLS handshakes.
|
||||
✅ **Simplifies certificate management** (one cert for all subdomains).
|
||||
⚠ **Requires manual DNS challenge setup** for Let's Encrypt.
|
||||
⚠ **Needs additional configuration for automation** (see below).
|
||||
|
||||
If enabled, update your inventory file and follow the **manual wildcard certificate setup** below.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 **Tasks Overview**
|
||||
|
||||
### **1️⃣ Main Tasks**
|
||||
@ -57,64 +38,6 @@ If enabled, update your inventory file and follow the **manual wildcard certific
|
||||
|
||||
---
|
||||
|
||||
## **🔐 Wildcard Certificate Setup with Let's Encrypt**
|
||||
If you enabled `enable_wildcard_certificate`, follow these steps to manually request a **wildcard certificate**.
|
||||
|
||||
### **1️⃣ Run the Certbot Command 🖥️**
|
||||
```sh
|
||||
certbot certonly --manual --preferred-challenges=dns --agree-tos \
|
||||
--email administrator@primary_domain -d primary_domain -d "*.primary_domain"
|
||||
```
|
||||
|
||||
### **2️⃣ Add DNS TXT Record for Validation 📜**
|
||||
Certbot will prompt you to add a DNS TXT record:
|
||||
```
|
||||
Please create a TXT record under the name:
|
||||
_acme-challenge.primary_domain.
|
||||
|
||||
with the following value:
|
||||
9oVizYIYVGlZ3VtWQIKRS5UghyXiqGoUNlCtIE7LiA
|
||||
```
|
||||
➡ **Go to your DNS provider** and create a new **TXT record**:
|
||||
- **Host:** `_acme-challenge.primary_domain`
|
||||
- **Value:** `"9oVizYIYVGlZ3VtWQIKRS5UghyXiqGoUNlCtIE7LiA"`
|
||||
- **TTL:** Set to **300 seconds (or lowest possible)**
|
||||
|
||||
✅ **Verify the DNS record** before continuing:
|
||||
```sh
|
||||
dig TXT _acme-challenge.primary_domain @8.8.8.8
|
||||
```
|
||||
|
||||
### **3️⃣ Complete the Certificate Request ✅**
|
||||
Once the DNS changes have propagated, **press Enter** in the Certbot terminal.
|
||||
If successful, Certbot will save the certificates under:
|
||||
```
|
||||
/etc/letsencrypt/live/primary_domain/
|
||||
```
|
||||
- **fullchain.pem** → The certificate
|
||||
- **privkey.pem** → The private key
|
||||
|
||||
---
|
||||
|
||||
## **📂 File & Directory Structure**
|
||||
```sh
|
||||
roles/nginx-docker-cert-deploy/
|
||||
├── files/
|
||||
│ ├── nginx-docker-cert-deploy.sh # Deployment script
|
||||
├── handlers/
|
||||
│ ├── main.yml # Restart Nginx handler
|
||||
├── meta/
|
||||
│ ├── main.yml # Dependencies
|
||||
├── tasks/
|
||||
│ ├── main.yml # Main Ansible tasks
|
||||
├── templates/
|
||||
│ ├── nginx-docker-cert-deploy.service.j2 # Systemd service template
|
||||
├── vars/
|
||||
│ ├── main.yml # Variable definitions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## **🔧 Deploying Certificates into Docker Containers**
|
||||
The role **automates copying certificates** into Docker Compose setups.
|
||||
|
||||
@ -129,20 +52,6 @@ This script:
|
||||
sh nginx-docker-cert-deploy.sh primary_domain /path/to/docker/compose
|
||||
```
|
||||
|
||||
### **2️⃣ Systemd Service & Timer**
|
||||
The role includes a **`systemd` service** that runs the deployment script whenever certificates are updated.
|
||||
|
||||
Example `nginx-docker-cert-deploy.service.j2`:
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Let's Encrypt deploy to {{docker_compose.directories.instance}}
|
||||
OnFailure=systemd-notifier.cymais@%n.service
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/bin/bash {{path_administrator_scripts}}/nginx-docker-cert-deploy.sh {{primary_domain}} {{docker_compose.directories.instance}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **Summary**
|
||||
|
||||
36
roles/nginx-docker-cert-deploy/SETUP.md
Normal file
36
roles/nginx-docker-cert-deploy/SETUP.md
Normal file
@ -0,0 +1,36 @@
|
||||
## **🔐 Wildcard Certificate Setup with Let's Encrypt**
|
||||
If you enabled `enable_wildcard_certificate`, follow these steps to manually request a **wildcard certificate**.
|
||||
|
||||
### **1️⃣ Run the Certbot Command 🖥️**
|
||||
```sh
|
||||
certbot certonly --manual --preferred-challenges=dns --agree-tos \
|
||||
--email administrator@primary_domain -d primary_domain -d "*.primary_domain"
|
||||
```
|
||||
|
||||
### **2️⃣ Add DNS TXT Record for Validation 📜**
|
||||
Certbot will prompt you to add a DNS TXT record:
|
||||
```
|
||||
Please create a TXT record under the name:
|
||||
_acme-challenge.primary_domain.
|
||||
|
||||
with the following value:
|
||||
9oVizYIYVGlZ3VtWQIKRS5UghyXiqGoUNlCtIE7LiA
|
||||
```
|
||||
➡ **Go to your DNS provider** and create a new **TXT record**:
|
||||
- **Host:** `_acme-challenge.primary_domain`
|
||||
- **Value:** `"9oVizYIYVGlZ3VtWQIKRS5UghyXiqGoUNlCtIE7LiA"`
|
||||
- **TTL:** Set to **300 seconds (or lowest possible)**
|
||||
|
||||
✅ **Verify the DNS record** before continuing:
|
||||
```sh
|
||||
dig TXT _acme-challenge.primary_domain @8.8.8.8
|
||||
```
|
||||
|
||||
### **3️⃣ Complete the Certificate Request ✅**
|
||||
Once the DNS changes have propagated, **press Enter** in the Certbot terminal.
|
||||
If successful, Certbot will save the certificates under:
|
||||
```
|
||||
/etc/letsencrypt/live/primary_domain/
|
||||
```
|
||||
- **fullchain.pem** → The certificate
|
||||
- **privkey.pem** → The private key
|
||||
@ -1,82 +1,22 @@
|
||||
# Installation
|
||||
# Deploy
|
||||
|
||||
This guide explains how to deploy and manage the Cyber Master Infrastructure Solution (CyMaIS) using Ansible. CyMaIS is based on a collection of playbooks that are designed for your servers and personal computers. The playbooks use different “modes” to control behavior such as updates, backups, resets, and cleanup tasks. This document outlines how to use Ansible Vault, describes the various operating modes, and shows example commands to run the playbooks.
|
||||
|
||||
|
||||
This guide should give you a comprehensive starting point for managing your infrastructure with CyMaIS. For further details, consult the individual role documentation and the accompanying repository README files.
|
||||
This guide explains how to deploy and manage the Cyber Master Infrastructure Solution (CyMaIS) using Ansible. CyMaIS is based on a collection of ansible tasks. The tasks use different “modes” to control behavior such as updates, backups, resets, and cleanup tasks.
|
||||
|
||||
## Prerequisites
|
||||
- **Inventory File:** Have an inventory file that lists your servers and PCs. (Paths in examples are general; adjust them to your environment.)
|
||||
- **Cymais Installed:** CyMaIS is installed via [Kevin's Package-Manager](https://github.com/kevinveenbirkenbach/package-manager).
|
||||
- **Vault Password File (Optional):** Prepare a file with your vault password if you prefer not to enter it interactively.
|
||||
|
||||
## Operating Modes
|
||||
|
||||
CyMaIS playbooks support several modes that control which tasks are executed:
|
||||
|
||||
- **mode_reset** (`true`/`false`):
|
||||
When enabled, cleans up all CyMaIS-related files. Use this mode when you need to reinitialize the system completely. _Note: Run the full playbook when using reset mode._
|
||||
|
||||
- **mode_test** (`true`/`false`):
|
||||
Executes test routines instead of production routines. Useful for staging or validation.
|
||||
|
||||
- **mode_update** (`true`/`false`):
|
||||
Enables update tasks to upgrade packages and Docker images. Set to `false` if you want to skip updates.
|
||||
|
||||
- **mode_backup** (`true`/`false`):
|
||||
Activates backup procedures before applying updates. This ensures your data is backed up prior to any changes.
|
||||
|
||||
- **mode_cleanup** (`true`/`false`):
|
||||
Performs cleanup of unused files and configurations (e.g., removing obsolete certificates or Docker volumes).
|
||||
|
||||
These modes are defined in your group variables (e.g., in a file like `group_vars/all/01_modes.yml`) and can be overridden via extra variables when running playbooks.
|
||||
|
||||
---
|
||||
|
||||
## Deploying on Servers
|
||||
|
||||
To deploy CyMaIS on your servers, use an Ansible playbook that targets your server inventory. Below are some example commands:
|
||||
|
||||
### Configure All Servers
|
||||
```bash
|
||||
ansible-playbook -i /path/to/your/inventory/servers.yml "$(pkgmgr path cymais)playbook.servers.yml" --ask-vault-pass
|
||||
To get detailled information how to use CyMaIS to deploy software to your server execute:
|
||||
```sh
|
||||
cymais --help
|
||||
```
|
||||
|
||||
### Configure a Specific Server
|
||||
For example, to target a server named `galaxyserver`:
|
||||
```bash
|
||||
ansible-playbook -i /path/to/your/inventory/servers.tmp "$(pkgmgr path cymais)playbook.servers.yml" --limit galaxyserver --ask-vault-pass
|
||||
```
|
||||
|
||||
### Run in Temporary Mode Without Update
|
||||
```bash
|
||||
ansible-playbook -i /path/to/your/inventory/servers.tmp "$(pkgmgr path cymais)playbook.servers.yml" --limit galaxyserver -e "mode_update=false" --ask-vault-pass
|
||||
```
|
||||
|
||||
### Run Without Update and Backup
|
||||
```bash
|
||||
ansible-playbook -i /path/to/your/inventory/servers.tmp "$(pkgmgr path cymais)playbook.servers.yml" --limit galaxyserver -e "mode_update=false" -e "mode_backup=false" --ask-vault-pass
|
||||
```
|
||||
|
||||
### Run with Cleanup and Debug (Using a Vault Password File)
|
||||
```bash
|
||||
ansible-playbook -i /path/to/your/inventory/servers.tmp "$(pkgmgr path cymais)playbook.servers.yml" --limit galaxyserver -e "mode_update=false" -e "mode_backup=false" -e "mode_cleanup=true" -e "enable_debug=true" -v --vault-password-file /path/to/your/vault_pass.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Using a Password File
|
||||
|
||||
To avoid entering your vault password interactively every time, use the `--vault-password-file` option:
|
||||
To avoid entering your vault password interactively every time, use the `--password-file` option:
|
||||
```bash
|
||||
--vault-password-file /path/to/your/vault_pass.txt
|
||||
--password-file /path/to/your/vault_pass.txt
|
||||
```
|
||||
Ensure the vault password file is stored securely.
|
||||
|
||||
---
|
||||
|
||||
## Final Notes
|
||||
- **Combining Modes:**
|
||||
The different modes (reset, test, update, backup, cleanup) can be combined by passing extra variables (using `-e`) on the command line. This flexibility allows you to tailor the playbook run to your current needs.
|
||||
|
||||
- **Debugging:**
|
||||
If you need more verbose output or troubleshooting information, add the `-v` (or `-vvv`) option when running the playbook.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user