forked from wazuh/wazuh-docker
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 (```) ---
This commit is contained in:
Jesus Garcia
@@ -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
|
||||
|
||||
|
||||
+23
-14
@@ -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 <ref> [Optional] Set the development stage you want to build, example rc2 or beta1, not used by default.
|
||||
-r, --revision <rev> [Optional] Package revision. By default 1
|
||||
-ref, --reference <ref> [Optional] Set the Wazuh reference to build development images. By default, the latest stable release.
|
||||
-rg, --registry <reg> [Optional] Set the Docker registry to push the images.
|
||||
-v, --version <ver> [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.
|
||||
|
||||
```
|
||||
```
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user