From f04ed6e6088a8a099dd35d15a0c0e2a9036a8e21 Mon Sep 17 00:00:00 2001 From: Jesus Garcia Date: Mon, 22 Dec 2025 08:36:09 -0500 Subject: [PATCH] Update documentation for Wazuh Docker image builder and workflow usage --- - All relevant content of README.md files was migrated to docs/ section in their respective section. - These README files has been deleted (4 files) - All README.md files (additional to the project's root and docs/) have been edited. --- - Both files build-docker-images/README.md and docs/dev/build-image.md have almost same content, so it was discarded the README file - As the directory and docker image are going to be disused, the certs-gen documentation contents of indexer-certs-creator/README.md was not mig> - The 'bash' command added to the docs/dev/build-image.md was removed - Added workflow usage docs file to the the SUMMARY.md file --- - Removed '$' parameter and added 'bash' to all markdown code blocks headings (```) --- --- CHANGELOG.md | 1 + build-docker-images/README.md | 34 ---------- docs/SUMMARY.md | 1 + docs/dev/build-image.md | 37 ++++++----- docs/dev/run-tests.md | 2 + docs/dev/workflow-usage.md | 61 ++++++++++++++++++ .../getting-started/deployment/deployment.md | 4 +- .../getting-started/deployment/multi-node.md | 63 ++++++++++++++++--- .../getting-started/deployment/single-node.md | 56 +++++++++++++---- indexer-certs-creator/README.md | 9 --- multi-node/README.md | 62 ------------------ single-node/README.md | 53 ---------------- 12 files changed, 188 insertions(+), 195 deletions(-) delete mode 100644 build-docker-images/README.md create mode 100644 docs/dev/workflow-usage.md delete mode 100644 indexer-certs-creator/README.md delete mode 100644 multi-node/README.md delete mode 100644 single-node/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 74b1b78e..2b4bccec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ All notable changes to this project will be documented in this file. ### Changed +- Update documentation for Wazuh Docker image builder and workflow usage ([#2136](https://github.com/wazuh/wazuh-puppet/issues/2136)) - Configure deployment with environment variables ([#2081](https://github.com/wazuh/wazuh-puppet/issues/2081)) - Modify Wazuh components install method ([#2058](https://github.com/wazuh/wazuh-puppet/issues/2058)) - Image builder Workflow Rebuild ([#2054](https://github.com/wazuh/wazuh-puppet/issues/2054)) diff --git a/build-docker-images/README.md b/build-docker-images/README.md deleted file mode 100644 index f0a1e338..00000000 --- a/build-docker-images/README.md +++ /dev/null @@ -1,34 +0,0 @@ -# Wazuh Docker Image Builder - -The creation of the images for the Wazuh stack deployment in Docker is done with the build-images.yml script - -To execute the process, the following must be executed in the root of the wazuh-docker repository: - -``` -$ build-docker-images/build-images.sh -``` - -This script initializes the environment variables needed to build each of the images. - -The script allows you to build images from other versions of Wazuh, to do this you must use the -v or --version argument: - -``` -$ build-docker-images/build-images.sh -v 5.0.0 -``` - -To get all the available script options use the -h or --help option: - -``` -$ build-docker-images/build-images.sh -h - -Usage: build-docker-images/build-images.sh [OPTIONS] - - -d, --dev [Optional] Set the development stage you want to build, example rc1 or beta1, not used by default. - -r, --revision [Optional] Package revision. By default 1 - -ref, --reference [Optional] Set the Wazuh reference to build development images. By default, the latest stable release. - -rg, --registry [Optional] Set the Docker registry to push the images. - -v, --version [Optional] Set the Wazuh version should be builded. By default, 5.0.0. - -m, --multiarch [Optional] Enable multi-architecture builds. - -h, --help Show this help. - -``` \ No newline at end of file diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index fa09fd2c..be59f772 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -8,6 +8,7 @@ - [Setup Environment](dev/setup.md) - [Build Image](dev/build-image.md) - [Run Tests](dev/run-tests.md) +- [Workflow Usage](dev/workflow-usage.md) # Reference Manual diff --git a/docs/dev/build-image.md b/docs/dev/build-image.md index 4c2c4512..a9a95edd 100644 --- a/docs/dev/build-image.md +++ b/docs/dev/build-image.md @@ -1,31 +1,40 @@ # Wazuh Docker Image Builder -The creation of the images for the Wazuh stack deployment in Docker is done with the build-images.yml script - -To execute the process, the following must be executed in the root of the wazuh-docker repository: - -``` -$ build-docker-images/build-images.sh -``` +The creation of the images for the Wazuh stack deployment in Docker is done with the `build-docker-images/build-images.sh` script This script initializes the environment variables needed to build each of the images. -The script allows you to build images from other versions of Wazuh, to do this you must use the -v or --version argument: +To execute it, make sure to be in the `build-docker-images` directory: -``` -$ build-docker-images/build-images.sh -v 5.0.0 +```bash +cd build-docker-images ``` -To get all the available script options use the -h or --help option: +Then execute: +```bash +./build-images.sh ``` -$ build-docker-images/build-images.sh -h -Usage: build-docker-images/build-images.sh [OPTIONS] +The script also allows to build images from other versions of Wazuh by using the `-v` or `--version` argument: + +```bash +./build-images.sh -v 5.0.0 +``` + +To get all the available script options use the `-h` or `--help` option: + +```bash +./build-images.sh -h + +Usage: build-images.sh [OPTIONS] -d, --dev [Optional] Set the development stage you want to build, example rc2 or beta1, not used by default. -r, --revision [Optional] Package revision. By default 1 + -ref, --reference [Optional] Set the Wazuh reference to build development images. By default, the latest stable release. + -rg, --registry [Optional] Set the Docker registry to push the images. -v, --version [Optional] Set the Wazuh version should be builded. By default, 5.0.0. + -m, --multiarch [Optional] Enable multi-architecture builds. -h, --help Show this help. -``` \ No newline at end of file +``` diff --git a/docs/dev/run-tests.md b/docs/dev/run-tests.md index e4b1a9d3..c9718f10 100644 --- a/docs/dev/run-tests.md +++ b/docs/dev/run-tests.md @@ -2,6 +2,8 @@ This repository includes automated tests designed to validate the correct deployment of Wazuh using Docker. These tests are executed on every pull request (PR) to ensure the integrity and stability of the system when changes are introduced. +Check more information on the [Workflow usage](workflow-usage.md) page. + ## Purpose The main objective of the tests is to verify that the Wazuh Docker environment can be successfully deployed and that all its core components (Wazuh Manager, Indexer, Dashboard, and Agents) operate as expected after any modification in the codebase. diff --git a/docs/dev/workflow-usage.md b/docs/dev/workflow-usage.md new file mode 100644 index 00000000..236786d2 --- /dev/null +++ b/docs/dev/workflow-usage.md @@ -0,0 +1,61 @@ +# Workflow usage + +The Procedure_push_docker_images.yml workflow builds and pushes multi-architecture Docker images (amd64/arm64) of Wazuh core components (Indexer, Manager, Dashboard, and Agent) to container registries. + +## Input Parameters + +| Parameter | Description | Default | Required | +|-----------|-------------|---------|----------| +| `image_tag` | Docker image version tag | `5.0.0` | Yes | +| `docker_reference` | Branch/tag to build from | - | Yes | +| `revision` | Package revision number | `1` | Yes | +| `reference` | Dev reference (for pre-release builds) | `latest` | No | +| `id` | Workflow run identifier | - | No | +| `dev` | Enable development mode (adds `-dev` suffix) | `false`/`true` | No | + +## Development vs Production Mode + +**Development Mode** (`dev: true`): + +- Pushes to AWS ECR (Elastic Container Registry) +- Uses pre-signed S3 URLs for packages +- Generates dynamic `artifact_urls.yml` from S3 bucket +- Adds development reference to image tags +- Authenticates via AWS IAM role + +**Production Mode** (`dev: false`): + +- Pushes to Docker Hub +- Uses public package repositories +- Authenticates with Docker Hub credentials +- Supports version stages (rc, beta, etc.) + +## Build Process + +1. **Artifact Resolution**: + - Dev mode: Creates pre-signed URLs for all Wazuh packages from S3 + - Prod mode: Uses packages from public repositories + +2. **Multi-architecture Build**: + - Uses Docker Buildx with QEMU for cross-platform builds + - Builds for `linux/amd64` and `linux/arm64` + - Leverages `build-images.yml` for build configuration + +3. **Image Publishing**: + - Tags images appropriately based on mode + - Pushes to the configured registry + - Generates .env file with build metadata + +## Log Collection Feature + +When tests fail, the workflows automatically collect and display relevant logs to help diagnose issues quickly. + +This is implemented via two scripts, executed depending on the test setup: +Single-node: `single-node-log-check.sh` +Multi-node: `multi-node-log-check.sh` + +Capabilities include: + +- Collects ERROR, WARNING, and CRITICAL messages from all nodes. +- Automatically gathers logs on test failures for faster debugging. + diff --git a/docs/ref/getting-started/deployment/deployment.md b/docs/ref/getting-started/deployment/deployment.md index 48360ef6..61fcb922 100644 --- a/docs/ref/getting-started/deployment/deployment.md +++ b/docs/ref/getting-started/deployment/deployment.md @@ -22,11 +22,11 @@ Wazuh-Docker offers flexibility in how you can deploy the Wazuh stack. The prima Ensure you have: -- Met all the [System Requirements](ref/getting-started/requirements.md). +- Met all the [System Requirements](../requirements.md). - Installed Docker and Docker Compose on your host(s). - Cloned the `wazuh-docker` repository (version `5.0.0`) or downloaded the necessary deployment files. ```bash - git clone [https://github.com/wazuh/wazuh-docker.git](https://github.com/wazuh/wazuh-docker.git) + git clone https://github.com/wazuh/wazuh-docker.git cd wazuh-docker git checkout v5.0.0 ``` diff --git a/docs/ref/getting-started/deployment/multi-node.md b/docs/ref/getting-started/deployment/multi-node.md index 19f9e968..6ee10934 100644 --- a/docs/ref/getting-started/deployment/multi-node.md +++ b/docs/ref/getting-started/deployment/multi-node.md @@ -2,31 +2,74 @@ ## Deploying Wazuh Docker in a Multi-Node Configuration -This deployment utilizes the `multi-node/docker-compose.yml` file, which defines a cluster setup with two Wazuh manager containers, three Wazuh indexer containers, and one Wazuh dashboard container. Follow these steps to deploy this configuration: +This deployment utilizes the `multi-node/docker-compose.yml` file, which defines a cluster setup with two Wazuh Manager, three Wazuh Indexer, and one Wazuh Dashboard containers. Follow these steps to deploy this configuration: + +1. Increase `vm.max_map_count` on each Docker host that will run a Wazuh Indexer container (Linux). This setting is crucial for Wazuh Indexer to operate correctly. This command requires root permissions: + + ```bash + sudo sysctl -w vm.max_map_count=262144 + ``` + + **Note:** This change is temporary and will revert upon reboot. To make it permanent on each relevant host, you'll need to edit the `/etc/sysctl.conf` file, add `vm.max_map_count=262144`, and then apply the change with `sudo sysctl -p`. + +2. Navigate to the `multi-node` directory within your repository: -1. Navigate to the `multi-node` directory within your repository: ```bash cd multi-node ``` -2. Increase `vm.max_map_count` on each Docker host that will run a Wazuh Indexer container (Linux). This setting is crucial for Wazuh Indexer to operate correctly. This command requires root permissions: - ```bash - sudo sysctl -w vm.max_map_count=262144 - ``` - **Note:** This change is temporary and will revert upon reboot. To make it permanent on each relevant host, you'll need to edit the `/etc/sysctl.conf` file, add `vm.max_map_count=262144`, and then apply the change with `sudo sysctl -p`. +3. Download the certificate creation script and config.yml file: -3. Run the script to generate the necessary certificates for the Wazuh Stack. This ensures secure communication between the nodes: ```bash - docker compose -f generate-indexer-certs.yml run --rm generator + curl -sO https://packages.wazuh.com/5.0/wazuh-certs-tool.sh + curl -sO https://packages.wazuh.com/5.0/config.yml ``` -4. Start the Wazuh environment using `docker compose`: +4. Edit the `config.yml` file with the configuration of the Wazuh components to be deployed + + ```bash + nodes: + # Wazuh indexer server nodes + indexer: + - name: wazuh1.indexer + ip: wazuh1.indexer + - name: wazuh2.indexer + ip: wazuh2.indexer + - name: wazuh3.indexer + ip: wazuh3.indexer + + # Wazuh server nodes + # Use node_type only with more than one Wazuh manager + server: + - name: wazuh.master + ip: wazuh.master + node_type: master + - name: wazuh.worker + ip: wazuh.worker + node_type: worker + + # Wazuh dashboard node + dashboard: + - name: wazuh.dashboard + ip: wazuh.dashboard + ``` + +5. Run the certificate creation script: + + ```bash + bash ./wazuh-certs-tool.sh -A + ``` + +6. Start the Wazuh environment using `docker compose`: * To run in the foreground (logs will be displayed in your current terminal; press `Ctrl+C` to stop): + ```bash docker compose up ``` + * To run in the background (detached mode, allowing the containers to run independently of your terminal): + ```bash docker compose up -d ``` diff --git a/docs/ref/getting-started/deployment/single-node.md b/docs/ref/getting-started/deployment/single-node.md index f5ab7eb8..f058fe3b 100644 --- a/docs/ref/getting-started/deployment/single-node.md +++ b/docs/ref/getting-started/deployment/single-node.md @@ -2,34 +2,68 @@ ## Deploying Wazuh Docker in a Single-Node Configuration -This deployment uses the `single-node/docker-compose.yml` file, which defines a setup with one Wazuh manager container, one Wazuh indexer container, and one Wazuh dashboard container. Follow these steps to deploy it: +This deployment uses the `single-node/docker-compose.yml` file, which defines a setup with one Wazuh Manager, one Wazuh Indexer, and one Wazuh Dashboard container. Follow these steps to deploy it: + +1. Increase `vm.max_map_count` on each Docker host that will run a Wazuh Indexer container (Linux). This setting is crucial for Wazuh Indexer to operate correctly. This command requires root permissions: + + ```bash + sudo sysctl -w vm.max_map_count=262144 + ``` + + **Note:** This change is temporary and will revert upon reboot. To make it permanent, you'll need to edit the `/etc/sysctl.conf` file and add `vm.max_map_count=262144`, then apply with `sudo sysctl -p`. + +2. Navigate to the `single-node` directory within your repository: -1. Navigate to the `single-node` directory within your repository: ```bash cd single-node ``` -2. Increase `vm.max_map_count` on each Docker host that will run a Wazuh Indexer container (Linux). This setting is crucial for Wazuh Indexer to operate correctly. This command requires root permissions: - ```bash - sudo sysctl -w vm.max_map_count=262144 - ``` - **Note:** This change is temporary and will revert upon reboot. To make it permanent, you'll need to edit the `/etc/sysctl.conf` file and add `vm.max_map_count=262144`, then apply with `sudo sysctl -p`. +3. Download the certificate creation script and `config.yml` file: -3. Run the script to generate the necessary certificates for the Wazuh Stack. This ensures secure communication between the nodes: ```bash - docker compose -f generate-indexer-certs.yml run --rm generator + curl -sO https://packages.wazuh.com/5.0/wazuh-certs-tool.sh + curl -sO https://packages.wazuh.com/5.0/config.yml ``` -4. Start the Wazuh environment using `docker compose`: +4. Edit the config.yml file with the configuration of the Wazuh components to be deployed + + ```bash + nodes: + # Wazuh indexer server nodes + indexer: + - name: wazuh.indexer + ip: wazuh.indexer + + # Wazuh server nodes + # Use node_type only with more than one Wazuh manager + server: + - name: wazuh.manager + ip: wazuh.manager + + # Wazuh dashboard node + dashboard: + - name: wazuh.dashboard + ip: wazuh.dashboard + ``` + +5. Run the certificate creation script: + + ```bash + bash ./wazuh-certs-tool.sh -A + ``` + +5. Start the Wazuh environment using `docker compose`: * To run in the foreground (logs will be displayed in your current terminal; press `Ctrl+C` to stop): + ```bash docker compose up ``` + * To run in the background (detached mode, allowing the containers to run independently of your terminal): + ```bash docker compose up -d ``` Please allow some time for the environment to initialize, especially on the first run. It can take approximately a minute or two (depending on your host's resources) as the Wazuh Indexer starts up and generates the necessary indexes and index patterns. - diff --git a/indexer-certs-creator/README.md b/indexer-certs-creator/README.md deleted file mode 100644 index 8ddccdf5..00000000 --- a/indexer-certs-creator/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Certificate creation image build - -The dockerfile hosted in this directory is used to build the image used to boot Wazuh's single node and multi node stacks. - -To create the image, the following command must be executed: - -``` -$ docker build -t wazuh/wazuh-certs-generator:0.0.3 . -``` diff --git a/multi-node/README.md b/multi-node/README.md deleted file mode 100644 index 9a300fc7..00000000 --- a/multi-node/README.md +++ /dev/null @@ -1,62 +0,0 @@ -# Deploy Wazuh Docker in multi node configuration - -This deployment is defined in the `docker-compose.yml` file with two Wazuh manager containers, three Wazuh indexer containers, and one Wazuh dashboard container. It can be deployed by following these steps: - -1) Increase max_map_count on your host (Linux). This command must be run with root permissions: -``` -$ sysctl -w vm.max_map_count=262144 -``` - -2) Download the certificate creation script and config.yml file: -``` -$ curl -sO https://packages.wazuh.com/5.0/wazuh-certs-tool.sh -$ curl -sO https://packages.wazuh.com/5.0/config.yml -``` - -3) Edit the config.yml file with the configuration of the Wazuh components to be deployed -``` -nodes: - # Wazuh indexer server nodes - indexer: - - name: wazuh1.indexer - ip: wazuh1.indexer - - name: wazuh2.indexer - ip: wazuh2.indexer - - name: wazuh3.indexer - ip: wazuh3.indexer - - # Wazuh server nodes - # Use node_type only with more than one Wazuh manager - server: - - name: wazuh.master - ip: wazuh.master - node_type: master - - name: wazuh.worker - ip: wazuh.worker - node_type: worker - - # Wazuh dashboard node - dashboard: - - name: wazuh.dashboard - ip: wazuh.dashboard -``` - -4) Run the certificate creation script: -``` -bash ./wazuh-certs-tool.sh -A -``` - -5) Start the environment with docker compose: - -- In the foregroud: -``` -$ docker compose up -``` - -- In the background: -``` -$ docker compose up -d -``` - - -The environment takes about 1 minute to get up (depending on your Docker host) for the first time since Wazuh Indexer must be started for the first time and the indexes and index patterns must be generated. diff --git a/single-node/README.md b/single-node/README.md deleted file mode 100644 index fbded2be..00000000 --- a/single-node/README.md +++ /dev/null @@ -1,53 +0,0 @@ -# Deploy Wazuh Docker in single node configuration - -This deployment is defined in the `docker-compose.yml` file with one Wazuh manager containers, one Wazuh indexer containers, and one Wazuh dashboard container. It can be deployed by following these steps: - -1) Increase max_map_count on your host (Linux). This command must be run with root permissions: -``` -$ sysctl -w vm.max_map_count=262144 -``` - -2) Download the certificate creation script and config.yml file: -``` -$ curl -sO https://packages.wazuh.com/5.0/wazuh-certs-tool.sh -$ curl -sO https://packages.wazuh.com/5.0/config.yml -``` - -3) Edit the config.yml file with the configuration of the Wazuh components to be deployed -``` -nodes: - # Wazuh indexer server nodes - indexer: - - name: wazuh.indexer - ip: wazuh.indexer - - # Wazuh server nodes - # Use node_type only with more than one Wazuh manager - server: - - name: wazuh.manager - ip: wazuh.manager - - # Wazuh dashboard node - dashboard: - - name: wazuh.dashboard - ip: wazuh.dashboard -``` - -4) Run the certificate creation script: -``` -bash ./wazuh-certs-tool.sh -A -``` - -5) Start the environment with docker compose: - -- In the foregroud: -``` -$ docker compose up -``` - -- In the background: -``` -$ docker compose up -d -``` - -The environment takes about 1 minute to get up (depending on your Docker host) for the first time since Wazuh Indexer must be started for the first time and the indexes and index patterns must be generated.