Building Docker images locally

You can modify and build Docker images for the Wazuh central components (manager, indexer, and dashboard) and the Wazuh agent. Build the images yourself only when you need to change them, for example, to add packages or configuration files. To deploy the published Wazuh images instead, skip this section and follow the Wazuh Docker deployment.

When you change an image, keep its credential steps. Each Dockerfile removes the passwords, CA, and certificates that installing the package creates on the build host. Each container then resolves its own credentials when it starts. Without that step, every container started from your image shares the build host's CA key and certificates.

Each image has its own directory, which holds its Dockerfile and a config directory:

wazuh-docker/build-docker-images/wazuh-manager/
wazuh-docker/build-docker-images/wazuh-indexer/
wazuh-docker/build-docker-images/wazuh-dashboard/
wazuh-docker/build-docker-images/wazuh-agent/

Requirements

Docker Engine with the Docker Buildx plugin. The build script runs docker buildx bake. Run docker buildx version to check that the plugin is installed.
Git, curl, and jq. Without jq, the script prints jq: command not found and then stops with curl: (22) The requested URL returned error: 403.
Internet access to GitHub, Docker Hub, the Amazon Linux 2023 package repositories, the Wazuh package repository, and packages.wazuh.com for the Wazuh signing key.
Free disk space: at least 20 GB. The build uses about 13 GB, and that space stays in use after the build: about 5 GB for the four images, and the rest for the build cache.

Building the images

Run the commands below as root, or as a user in the docker group.

Clone the Wazuh Docker repository to your system:

# git clone https://github.com/wazuh/wazuh-docker.git -b v5.0.0-rc2

Navigate to the wazuh-docker/build-docker-images directory:
```
# cd wazuh-docker/build-docker-images
```
Run the build script. Choose one of the following commands:
- To tag the images 5.0.0-rc2, as the docker-compose.yml files of Wazuh 5.0.0-rc2 expect, add the release stage with the -d option:
```
# ./build-images.sh -d rc2
```
- To tag the images 5.0.0:
```
# ./build-images.sh
```
Each command builds the wazuh/wazuh-manager, wazuh/wazuh-indexer, wazuh/wazuh-dashboard, and wazuh/wazuh-agent images. The script prints the image names and tags under Image tags: before it starts building. Run only one of them, because a second build adds about 9 GB more build cache.

The -v option sets the Wazuh version in X.Y.Z format only. To build another Wazuh version, clone the tag of that version in step 1 instead.

Each image installs its Wazuh package only if the package is signed with the Wazuh key. Use --skip-signature-check only together with --dev, to build images from unsigned development packages.

On every run, the script downloads the package list of the Wazuh version to wazuh-docker/build-docker-images/artifact_urls.yaml and replaces any earlier copy. To build from your own package list, pass it with the -a option.

To get all the available script options, use the -h or --help option:

# ./build-images.sh -h

The command output looks similar to this:

Usage: ./build-images.sh [OPTIONS]

    -a, --artifact-urls <file>   [Optional] Use this artifact URLs file instead of downloading the one for the requested version.
    -d, --dev-stage <ref>        [Optional] Set the pre-release stage suffix (e.g. beta1, rc2). Not used by default.
    --dev                        [Optional] Mark as a development build: appends the commit ref to the image tag. Controlled by inputs.dev in the workflow.
    --release                    [Optional] Final release build: use the production artifact URLs file without checking the GitHub release. Not valid with --dev, -d or -a.
    -refs, --references <refs>   [Optional] [Only with --dev] JSON array of commit refs for components (indexer, manager, dashboard, agent) in order. Defaults to 'latest'.
    -rg, --registry <reg>        [Optional] Set the Docker registry to push the images.
    -c, --component <comp>       [Optional] Build only this component: 'wazuh-indexer', 'wazuh-manager', 'wazuh-dashboard' or 'wazuh-agent'. By default, all four.
    -v, --version <ver>          [Optional] Set the Wazuh version should be builded. By default, 5.0.0.
    -m, --multiarch              [Optional] Enable multi-architecture builds.
    --skip-signature-check       [Optional] [Only with --dev] Install the Wazuh packages without checking that they are signed by Wazuh. Only for unsigned development packages.
    -h, --help                   Show this help.

The base images are downloaded before the build. Environment variables:
    BASE_IMAGE_PULL_RETRIES      Attempts per base image. By default, 5.
    BASE_IMAGE_PULL_DELAY        Seconds added to the wait after each failed attempt. By default, 15.

Next steps

To deploy the images you built, follow the Wazuh Docker deployment from the same clone. If this Docker host already runs a Wazuh Docker deployment, don't create a second one from this clone, because its single-node and multi-node directories use the same volume names. Either set the image tags of your existing deployment to the ones you built, or stop the other stack and first set another project name in the deployment directory, for example, with echo COMPOSE_PROJECT_NAME=wazuh-custom > .env. Both stacks publish the same ports, so they can't run at the same time. Images built with -d rc2 already carry the tags in the docker-compose.yml files, so the deployment uses them without a download. If you built them without -d rc2, first change the tag in every image: line to 5.0.0. These lines are in wazuh-docker/single-node/docker-compose.yml, wazuh-docker/multi-node/docker-compose.yml, and wazuh-docker/wazuh-agent/docker-compose.yml.