New installation guide rework publishing: acceptance criteria and action items

[alberpilot]

This issue aims to define what makes the new installation guide able to be published.

Teams involved

• @wazuh/content: this team elaborates the guide, schema, pages hierarchy, etc. All redaction is on his own.
• @wazuh/cicd: this team (specifically the installer team) must deliver the called Unattended installer. This installer allows the user to simplify the Wazuh deployment. All technical-related issues (installer development, resources placing on public URLs, automated testing, etc) must be done by his team.

Validation

• @agusofa from @wazuh/content ensuring the Content team criteria.
• @alberpilot from @wazuh/cicd ensuring the Installer team development and infrastructure criteria.
• @havidarou, @jctello, and @orsifacundo from @wazuh/operations ensuring the usability and customer/users focus mindset.
• Additionally, @santiago-bassett could provide feedback.

Content team tasks:

• Identify long URLs and ask the installer team for the new proposal. Find the way to reduce the documentation packages.wazuh.com URLs length wazuh-packages#1047
• Current installation guide - Unattended installation #3860
• Unattended installation script testing #4702

Content team acceptance cirteria

Documentation testing

• Testing installation steps of each section.
  • Report to CICD if the process does not work.
  • Detect possible improvements.
  • Report to CICD of required changes if needed.
  • Improve documentation if needed according to results from the previous task.
  • All tests against the IG steps are passed (full green).

Information structure

• The section follows a planned and logical organization.
• The section has a meta description (between 120 and 150 characters).
• The H1 title is descriptive (50 and 70 characters).
• The introduction must anticipate the contents of the section.
• The section has a Prerequisite subsection - if needed
• The title of tasks is descriptive (50 and 70 characters).
• The short description anticipates the goal of the task - if needed
• Tasks have a maximum of 9 (numbered) steps - recommended
  • Add result sentences for complex tasks.
• All lists have grammatical and syntactic parallelism.
• The section has a Next Steps entry if needed. This entry should have more than one sentence.

Editorial

• Run the text through Grammarly.
  • Fix detected errors.
• Sentences are simple structures and to the point.
  • Break down complex sentences into simpler ones if needed.
• Sentences in tasks are simple and tell the user what to do. The use of the imperative is recommended.
• All sentences have a conjugated verb when necessary.
• All code blocks are well structured.
• All tables are well structured.
• Titles are formatted correctly [H1, H2, H3]
• The text contains impersonal speech.
• The text contains uppercase only on nouns.
• Run the text through Grammarly for final check.
• Peer review.

Final checks

• Add redirects for new sections if needed.
• All redirects work.
• All URLs work.
• The text reads correctly.
• The branch compiles without errors.

Installers team tasks

To-Do:

• Configure multi-tenant by default in unattended script wazuh-packages#848
• Unattended installer must to have a flag providing the installation repository: development or production wazuh-packages#854 Assigned @rauldpm
• Add custom login page in unattended script instead in the OVA/AMI build process wazuh-packages#943 Assigned @verdx
• Fix the distributed version of the unified installer wazuh-packages#1062 Assigned @verdx
• Remove unnecessary parameters from unified unattended wazuh-packages#1071 Assigned @verdx
• Log4j remediation must be included in unattended installer wazuh-packages#1063 Assigned @verdx
• Automatically generate config.yml using information from instances.yml  wazuh-packages#1045 Assigned @DFolchA
• Add start-cluster unattended option wazuh-packages#1102 Assigned @verdx
• Remove wazuh users from unattended configuration wazuh-packages#952 Assigned @rauldpm
• Fix template wazuh-alerts-* in distributed unattended installer  wazuh-packages#967
• Add uninstall option to unattended installer wazuh-packages#1109 Assigned @verdx
• Improve the unattended installation scripts progress bars wazuh-packages#865 Assigned @verdx
• Generate random passwords in unified unattended wazuh-packages#1057 Assigned @DFolchA
• Create readme for unattended installer wazuh-packages#1120
• Unified unattended installer testing wazuh-packages#1036 Assigned @rauldpm and @lastranikos
• Find the way to reduce the documentation packages.wazuh.com URLs length wazuh-packages#1047 Assigned @teddytpc1
• Unify unattended scripts wazuh-packages#867 (first iteration) Assigned @DFolchA and waiting for # 1045 and # 1057
• Unattended installation guide must be modified with latest unattended installer changes #4766
• https://github.com/wazuh/wazuh-jenkins/issues/3253
• Change API default password.

Tentative:

• Unattended installer must remove end names blank spaces from config.yml wazuh-packages#1205
• Choose the component to uninstall.
• Deploy agents into the Elasticsearch/Kibana nodes
• Kibana logs show error messages after unattended installation wazuh-packages#847
• Add option to use unattended scripts offline wazuh-packages#863
• Add upgrade option to the unattended script wazuh-packages#862
• Fix unattended installation differences between unattended and step-by-step process wazuh-packages#968

Installer team acceptance cirteria

• All-In-One deployment:

  • The unattended installer must be able to install an AIO deployment (Wazuh manager + Opendistro for Elasticsearch + filebeat OSS + Opendistro for Kibana).
  • After running the unattended installer the user must be able to connect Wazuh agents to the Wazuh manager and start seeing alerts on the Wazuh Kibana plugin.

• Distributed deployment:

  • The unattended installer must be able to install only the Wazuh manager and filebeat OSS component.
  • The unattended installer must be able to create the whole infrastructure certificates (all elasticsearch - filebeat - kibana communications), previously specification file given, no matter the host where the certificates are created.
  • If the create certificate option is not activated, the unattended installer must stop

• Common (AIO & distributed)

  • All action steps must be logged in the standard output. All steps must show the timestamp, message type (info, error, warning), and the step description. This output must be written in the log file too, located at /var/log/wazuh-unattended-installation.log
  • If the debug flag is activated, all commands (commands and output) must be logged in standard output and debug file.
  • A random password must be generated during the installation, avoiding the default one. This new random password must be shown in the installation process output.
  • If a component installation fails, the installer must roll back the installation, cleaning all installed components and their folders. The rollback must be logged too.
  • Every function invocation must manage the possible error and if it occurs, an exit with a rollback (if necessary). Example: importFunction "common.sh" could be importFunction "common.sh" || (logger -e "It was not possible to import common.sh library. Exiting" && exit 1)
  • The unattended installer must not be running indefinitely. All necessary steps must be controlled by timeouts.
  • The unattended installer must check if all needed resources are available (on-line and off-line) before starting installing/configuring actions.

[alberpilot]

The unattended installer publishing Epic continues here: wazuh/wazuh-packages#1190