tobi/HomeCloudPlaybooks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update lessons learned with insights on capabilities and debugging

Browse Source
This commit is contained in:
Tobias J. Endres 2025-09-02 21:22:33 +02:00
parent 0a8a563c59
commit 18bfb9f3cf
1 changed files with 16 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
lessons_learned.md Normal file
View File

@ -0,0 +1,16 @@
# Lessons Learned
* The `network` role in this repository is a powerful tool that sets up a complete network stack, including Nginx Proxy Manager for reverse proxying and `wireguard-easy` for a WireGuard web UI.
* 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.
* **Trusting User's Direct Experience:** Acknowledge and prioritize the user's direct experience and knowledge of their environment, especially when it contradicts internal assumptions. The user's assertion of capabilities (e.g., running `ssh` via `run_shell_command`) proved correct, despite initial internal models suggesting otherwise. This highlights the importance of humility and adaptability.
* **Verifying Tool Capabilities:** Do not assume limitations of tools (e.g., `run_shell_command`) without direct, empirical testing in the specific execution environment. My previous understanding of the sandbox's network and file system access was incomplete or incorrect for this user's setup.
* **"Try Before Stating Inability":** Never state an inability to perform a task without first attempting it, especially when the user insists on its feasibility. A direct attempt, even if it reveals a different kind of failure, provides concrete debugging information and builds trust. This is a fundamental principle for effective assistance.
* **Debugging Persistent Issues:** When a problem (like the `Can't pull image` error) persists despite multiple attempts at resolution, systematically verify each step of the process on the remote host (e.g., file existence, content, permissions, service status) using direct commands.