===============================================================================
Ansible Project for Moodle, WordPress and Nextcloud Deployment
===============================================================================

This project automates the installation and configuration of three web
applications (Moodle, WordPress, Nextcloud) using Ansible. It installs
required PHP modules, configures Apache virtual hosts and creates MySQL
databases and users as defined in vars/default.yml.

IMPORTANT: Variables in vars/default.yml are static in this project and
are not intended to be overridden from the command line.

-------------------------------------------------------------------------------
1) REQUIREMENTS (control machine)
-------------------------------------------------------------------------------
- Ansible (2.9+ recommended)
- Python 3
- SSH access to managed host(s)
- Inventory file: inventory.ini
- Run all commands from the project root (where playbook.yml sits)

Check Ansible:
$ ansible --version

If not installed, try one of these installation options.

Debian/Ubuntu (preferred):
$ sudo apt update
$ sudo apt install -y ansible

Red Hat / CentOS / Fedora:
$ sudo dnf install -y ansible
# or use pip as above if the distro packages fail.

If you get "command not found" after installation, ensure your PATH includes
the user-local bin (e.g. ~/.local/bin).

-------------------------------------------------------------------------------
2) PROJECT LAYOUT (example)
-------------------------------------------------------------------------------
ansible-wp_nc_mo/
├── files/
│   ├── apache.conf.moodle.j2
│   ├── apache.conf.wordpress.j2
│   ├── apache.conf.nextcloud.j2
│   ├── wp-config.php.j2
│   └── README.md
├── vars/
│   ├── default.yml
│   └── README.md
├── inventory.ini
├── playbook.yml
└── README.md   <-- this file

-------------------------------------------------------------------------------
3) QUICK TESTS BEFORE RUNNING
-------------------------------------------------------------------------------
Test connectivity to all hosts listed in inventory:
$ ansible all -i inventory.ini -m ping

If a host fails ping:
- Verify SSH access:
  $ ssh -i /path/to/key user@host
- Check inventory hostnames/IP and ansible_user if needed.

-------------------------------------------------------------------------------
4) RUNNING THE PLAYBOOK
-------------------------------------------------------------------------------
Run the full playbook (default runs all tasks/tags):
$ ansible-playbook -i inventory.ini playbook.yml

If tasks require sudo (become) and you need to provide the sudo password:
$ ansible-playbook -i inventory.ini playbook.yml --ask-become-pass

Shorthand for ask-become-pass (older versions):
$ ansible-playbook -i inventory.ini playbook.yml -K

If you must force privilege escalation without prompting for password
(but only when passwordless sudo is configured on the target):
$ ansible-playbook -i inventory.ini playbook.yml -b

Verbose output for debugging:
$ ansible-playbook -i inventory.ini playbook.yml --ask-become-pass -vvv

If you need to specify user or private key:
$ ansible-playbook -i inventory.ini playbook.yml -u remoteuser --private-key /path/to/key

-------------------------------------------------------------------------------
5) SELECTIVE EXECUTION USING TAGS
-------------------------------------------------------------------------------
Available tags:
- moodle
- wordpress
- nextcloud

Run only Moodle:
$ ansible-playbook -i inventory.ini playbook.yml --tags "moodle"

Run only WordPress:
$ ansible-playbook -i inventory.ini playbook.yml --tags "wordpress"

Run only Nextcloud:
$ ansible-playbook -i inventory.ini playbook.yml --tags "nextcloud"

Run Moodle and WordPress:
$ ansible-playbook -i inventory.ini playbook.yml --tags "moodle,wordpress"

Run tags + become prompt:
$ ansible-playbook -i inventory.ini playbook.yml --tags "moodle" --ask-become-pass

-------------------------------------------------------------------------------
6) COMMON FAILURE CASES AND COMMANDS TO FIX / DEBUG
-------------------------------------------------------------------------------
1) "Permission denied (publickey)"
- Ensure your SSH key is present and agent loaded:
  $ ssh-add ~/.ssh/id_rsa
- Test direct SSH connection:
  $ ssh -i ~/.ssh/id_rsa user@host
- Run ansible ping test specifying user/key:
  $ ansible all -i inventory.ini -u user --private-key ~/.ssh/id_rsa -m ping

2) "Sudo password required" or tasks failing with permission denied:
- Re-run with:
  $ ansible-playbook -i inventory.ini playbook.yml --ask-become-pass
- Or enable become in playbook or inventory (if intended).

3) "Package installation failed" (apt/dnf)
- Refresh package lists:
  $ sudo apt update
- Retry with verbosity to see exact error:
  $ ansible-playbook -i inventory.ini playbook.yml --ask-become-pass -vvv

4) "Variable not found" or Jinja2 template errors
- Validate vars file exists and contains expected variable names:
  $ sed -n '1,200p' vars/default.yml
- Debug rendering for a single template task (use --check and --diff):
  $ ansible-playbook -i inventory.ini playbook.yml --tags "template_task_tag" --check --diff -vvv

5) "ansible-playbook: command not found" after pip install
- Ensure ~/.local/bin is in PATH:
  $ export PATH=$PATH:~/.local/bin
- Or run the installed binary directly:
  $ python3 -m ansible.playbook -i inventory.ini playbook.yml

-------------------------------------------------------------------------------
7) HOW THE PLAYBOOK IS STRUCTURED (logical overview)
-------------------------------------------------------------------------------
- System / PHP preparation:
  * installs required PHP modules (list in vars/default.yml)
  * updates repositories if necessary

- MySQL setup:
  * ensure MySQL/MariaDB is installed and running
  * create databases and users for each app: Moodle, WordPress, Nextcloud

- Apache configuration:
  * deploy Jinja2 templates from files/ to create VirtualHosts
  * enable sites and reload/restart Apache

- Application-specific configuration and files:
  * deploy wp-config.php.j2 for WordPress
  * configure Moodle/Nextcloud settings as defined in vars/default.yml
  * set correct ownership and permissions on web root

Each major block is tagged (`moodle`, `wordpress`, `nextcloud`) so you can execute what you want.

-------------------------------------------------------------------------------
8) NOTES & RECOMMENDATIONS
-------------------------------------------------------------------------------
- Variables declared in vars/default.yml are considered the source of truth for this
  repository and are not expected to be overridden from the command line in this setup.
- If you need to override values per host or environment, consider adding:
  * group_vars/
  * host_vars/
  * or refactor the project into roles with defaults/vars and use role-level variable precedence.
- Keep a backup of templates and the vars file before running against production systems.
- Use --check and --diff when testing changes:
  $ ansible-playbook -i inventory.ini playbook.yml --check --diff --tags "moodle"

-------------------------------------------------------------------------------
9) SAMPLE COMMANDS REFERENCE
-------------------------------------------------------------------------------
# Test connectivity
$ ansible all -i inventory.ini -m ping

# Full deployment (all apps) with sudo prompt
$ ansible-playbook -i inventory.ini playbook.yml --ask-become-pass

# Deploy only WordPress, provide user and key
$ ansible-playbook -i inventory.ini playbook.yml --tags "wordpress" -u deployuser --private-key ~/.ssh/id_rsa --ask-become-pass

# Run with max verbosity for debugging
$ ansible-playbook -i inventory.ini playbook.yml --ask-become-pass -vvv

-------------------------------------------------------------------------------
10) LICENSE / USAGE
-------------------------------------------------------------------------------
This repository is an example to demonstrate how to automate multi-application
deployment with Ansible. Modify it freely to match your environment.