From 9d9d07a599fab337b0e4423d7f749dd4832ed6e4 Mon Sep 17 00:00:00 2001 From: "Tobias J. Endres" Date: Tue, 2 Sep 2025 18:43:41 +0200 Subject: [PATCH] docs: Update planning and lessons learned documentation --- LESSONS_LEARNED.md | 6 ++++++ PLAN.md | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 PLAN.md diff --git a/LESSONS_LEARNED.md b/LESSONS_LEARNED.md index c1e4cbe..ee5d5ed 100644 --- a/LESSONS_LEARNED.md +++ b/LESSONS_LEARNED.md @@ -4,3 +4,9 @@ * The `gitea` and `postgres` roles use Docker Compose to deploy their respective services. * Properly managing variables, especially secrets like passwords and API keys, is crucial. Using `group_vars` and a `.gitignore`d `secrets` directory is a good practice. * It's important to have a clear plan and get user feedback before making any changes. The "planning mode" and "acting mode" paradigm is a good way to structure the workflow. +* The `docker` role proved problematic on Ubuntu 24.04 (`noble`) due to repository issues. +* Podman is a viable and simpler alternative to Docker for container management. +* Ansible modules designed for Docker (e.g., `community.docker.docker_compose_v2`, `docker_container`) are not directly compatible with Podman. +* `podman-compose` can be used with `ansible.builtin.shell` for managing `docker-compose.yml` files with Podman. +* `containers.podman.podman_container` is the direct replacement for `docker_container` for managing individual Podman containers. +* Ansible Vault is crucial for securely managing sensitive data like passwords in version control. \ No newline at end of file diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..fb0b425 --- /dev/null +++ b/PLAN.md @@ -0,0 +1,37 @@ +# Deployment Plan for Home Cloud + +## 1. Goal + +The goal is to set up a personal cloud environment on your two hosts, Mulder and Scully. This involves deploying Gitea (a self-hosted Git service) on Mulder, and Keycloak (an identity and access management solution) on Scully. All services should be accessible via HTTPS with Let's Encrypt certificates and subdomain-based routing. We will also set up a WireGuard VPN with a web interface for secure access to your network. + +## 2. Phased Deployment Plan + +### Phase 1: Network Infrastructure on Scully (Current Focus) + +* **Goal:** Deploy the `common` and `network` roles on Scully. The `network` role will set up Nginx Proxy Manager (for HTTPS and subdomain routing) and WireGuard Easy (for VPN with web UI). +* **Host and Role Assignments:** + * **Scully:** `common`, `network` +* **Configuration Files:** + * `inventory/hosts.yml`: Defines Mulder and Scully, their connection details, and role-specific variables. + * `playbooks/main.yml`: Modified to execute the `common` and `network` roles on Scully. + * `group_vars/all.yml`: Contains common variables like the domain name and service credentials. +* **Execution Plan:** + 1. Perform a dry run of the playbook to deploy the `common` and `network` roles on Scully. + 2. If the dry run is successful, execute the playbook to apply the changes. + +### Phase 2: Gitea and Keycloak Deployment (Future) + +* **Goal:** Deploy Gitea on Mulder and Keycloak on Scully, along with their respective PostgreSQL databases. +* **Host and Role Assignments:** + * **Mulder:** `common`, `postgres`, `gitea` + * **Scully:** `common`, `postgres`, `keycloak` (in addition to `network`) +* **Dependencies:** This phase depends on the successful completion of Phase 1 and the availability of the domain name. +* **Next Steps:** Once Phase 1 is complete, we will update the `playbooks/main.yml` and `group_vars/all.yml` to include the `postgres`, `gitea`, and `keycloak` roles. + +## 3. What We Still Need + +* **Your Domain Name:** Please provide the domain name you want to use for your personal cloud (e.g., `my-cloud.com`). This is the last piece of information needed to proceed with the dry run for Phase 1. + +## 4. Dry-Run + +Before executing any changes, a dry run will be performed using the `--check` flag.