39 lines
4.1 KiB
Markdown
39 lines
4.1 KiB
Markdown
# 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.
|
|
* **General Debugging Principles:**
|
|
* Always trust the user's direct experience and observations, even if they initially contradict assumptions or playbook output.
|
|
* When a playbook reports success but the desired state isn't met, investigate deeper. Ansible's `changed` status can be misleading if the underlying application fails after the module reports success.
|
|
* Use increased verbosity (`-vvv`) for detailed debugging output from Ansible.
|
|
* Systematically verify each layer of the stack (container logs, host processes, host firewall, cloud firewall).
|
|
|
|
* **Podman Specifics & Rootless Containers:**
|
|
* Rootless Podman requires tasks managing user-specific files and containers to explicitly use `become: false`.
|
|
* Using `~` (tilde) in paths for user home directories is more robust than relying on `ansible_user_dir`, which can sometimes resolve unexpectedly.
|
|
* Fully qualifying image names (e.g., `docker.io/portainer/portainer-ce`) prevents registry ambiguity issues and avoids interactive prompts.
|
|
* Debugging container startup issues requires checking:
|
|
* `podman ps -a` (to see all containers, running or exited).
|
|
* `podman logs <container_name>` (to get application logs).
|
|
* `sudo podman ps` (to check for rootful containers that might be interfering).
|
|
* Orphaned `conmon` processes from failed container startups can block ports and require manual cleanup (`sudo kill <PID>`, `podman stop/rm`).
|
|
* Ensure `registries.conf` is correctly templated (`ansible.builtin.template`, not `ansible.builtin.copy`) and placed in `~/.config/containers/registries.conf` for rootless Podman.
|
|
* Verify Podman's actual listening port on the host with `sudo ss -tulnp | grep <port>` (or `lsof`).
|
|
|
|
* **Ansible Best Practices:**
|
|
* **Idempotency is paramount:** Always strive for idempotent tasks that describe the desired state (e.g., `ansible.posix.firewalld`, `ansible.builtin.service`) rather than imperative shell commands.
|
|
* Ensure all necessary Python libraries (`python3-firewall`) and system services (`firewalld`) are installed and running on target hosts *before* modules that depend on them are called.
|
|
* Explicitly set `become: false` on tasks that should run as the connecting user, especially when the play has `become: true` by default.
|
|
* The `ansible.builtin.template` module must be used for Jinja2 templates; `ansible.builtin.copy` does not process templates.
|
|
|
|
* **Networking & Cloud Considerations:**
|
|
* Host firewall (`firewalld`) rules are separate from cloud provider security rules (e.g., Oracle Cloud Network Security Groups/Security Lists). Both layers must be correctly configured.
|
|
* Ansible playbooks typically cannot manage cloud provider firewalls without specific cloud collections (e.g., `oracle.oci`). |