forked from wazuh/wazuh-docker
Merge pull request #2215 from wazuh/enh/2197-Missing_documentation_in_the_wazuh-docker_repository
Add missing documentation sections in the repository
This commit is contained in:
Gonzalo Acuña
@@ -11,6 +11,7 @@ All notable changes to this project will be documented in this file.
|
||||
|
||||
- Remove revision input ([#2217](https://github.com/wazuh/wazuh-docker/pull/2217))
|
||||
- Improve build script and workflow component revisions handling ([#2212](https://github.com/wazuh/wazuh-docker/pull/2212))
|
||||
- Add missing documentation sections in the repository ([#2215](https://github.com/wazuh/wazuh-docker/pull/2215))
|
||||
- Add Wazuh version and revision into wazuh-certs-tool and config file ([#2195](https://github.com/wazuh/wazuh-docker/pull/2195))
|
||||
- Improve S3 artifact URLs handling ([#2183](https://github.com/wazuh/wazuh-docker/pull/2183))
|
||||
- Allow building separate targets ([#2177](https://github.com/wazuh/wazuh-docker/pull/2177))
|
||||
|
||||
+1
-1
@@ -89,7 +89,7 @@ The folder `wazuh-agent` contains a README explaining how to run a container wit
|
||||
│ │ │ ├── README.md
|
||||
│ │ │ └── requirements.md
|
||||
│ │ ├── glossary.md
|
||||
│ │ ├── Introduction
|
||||
│ │ ├── introduction
|
||||
│ │ │ ├── compatibility.md
|
||||
│ │ │ ├── description.md
|
||||
│ │ │ └── README.md
|
||||
|
||||
+8
-3
@@ -12,8 +12,9 @@
|
||||
|
||||
# Reference Manual
|
||||
|
||||
- [Introduction](ref/Introduction/introduction.md)
|
||||
- [Description](ref/Introduction/description.md)
|
||||
- [Introduction](ref/introduction/introduction.md)
|
||||
- [Description](ref/introduction/description.md)
|
||||
- [Compatibility](ref/introduction/compatibility.md)
|
||||
- [Getting Started](ref/getting-started/getting-started.md)
|
||||
- [Requirements](ref/getting-started/requirements.md)
|
||||
- [Deployment](ref/getting-started/deployment/deployment.md)
|
||||
@@ -24,4 +25,8 @@
|
||||
- [Environment Variabless](ref/configuration/environment-variables.md)
|
||||
- [Configuration files](ref/configuration/configuration-files.md)
|
||||
- [Upgrade](ref/upgrade.md)
|
||||
- [Glossary](ref/glossary.md)
|
||||
- [Uninstall](ref/uninstall.md)
|
||||
- [Backup and restore](ref/backup-and-restore.md)
|
||||
- [Security](ref/security.md)
|
||||
- [Performance](ref/performance.md)
|
||||
- [Glossary](ref/glossary.md)
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
# Backup and restore
|
||||
|
||||
For backup and restore, refer to the documentation for each component:
|
||||
|
||||
- [Wazuh manager](https://github.com/wazuh/wazuh/blob/v5.0.0/docs/ref/backup-restore.md)
|
||||
- [Wazuh agent](https://github.com/wazuh/wazuh-agent/blob/v5.0.0/docs/ref/backup-restore.md)
|
||||
@@ -28,5 +28,20 @@
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
|
||||
Consult the official Wazuh documentation for version 5.0.0 for detailed information on all possible configuration parameters for each component.
|
||||
|
||||
## Persistence configuration
|
||||
|
||||
When customizing your Wazuh Docker deployment, certain files and directories must be persisted to retain your changes across container restarts and recreations. This is critical for maintaining custom configurations, user credentials, and security settings.
|
||||
|
||||
### Volumes and Bind Mounts
|
||||
|
||||
Docker volumes allow you to persist data outside of container lifecycles. When a container is removed or recreated, data stored in volumes remains intact. This is essential for maintaining configuration files, user data, and other persistent state. While, bind mounts allow you to mount a file or directory from the host into the container.
|
||||
|
||||
To persist files or directories in your Wazuh deployment, you can mount them as volumes or bind mounts in your `docker-compose.yml` file.
|
||||
|
||||
> **Important**: Ensure that files exist on the host before starting the containers. If the file doesn't exist, Docker will create a directory instead, which may cause startup failures.
|
||||
|
||||
For more information on Docker volumes and bind mounts, refer to the official Docker documentation:
|
||||
- [Use volumes](https://docs.docker.com/storage/volumes/)
|
||||
- [Bind mounts](https://docs.docker.com/storage/bind-mounts/)
|
||||
|
||||
@@ -18,7 +18,7 @@ Getting started with Wazuh-Docker involves the following general steps:
|
||||
|
||||
Before diving into the deployment, please ensure you have reviewed:
|
||||
|
||||
- The [Description](ref/Introduction/description.md) of Wazuh-docker to understand the components and architecture.
|
||||
- The [Description](ref/introduction/description.md) of Wazuh-docker to understand the components and architecture.
|
||||
- The [Requirements](ref/getting-started/requirements.md) to confirm your environment is suitable.
|
||||
|
||||
## Steps to Get Started
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
# Compatibility
|
||||
|
||||
This section provides information about the compatibility of the Wazuh Docker stack with different platforms.
|
||||
|
||||
## Supported platforms
|
||||
|
||||
### Host operating system and architecture
|
||||
|
||||
- Linux hosts are recommended for running the stack.
|
||||
- Windows and macOS are supported when using Docker Desktop. On Windows, the WSL 2 backend is recommended.
|
||||
- When building images, the build process supports `linux/amd64` and `linux/arm64`.
|
||||
|
||||
### Privileged ports and rootless Docker
|
||||
|
||||
The default Compose deployments publish some privileged ports on the host (for example, the Dashboard on `443/tcp` and syslog on `514/udp`).
|
||||
|
||||
- If you run Docker in rootless mode or under restrictive policies, publishing ports below `1024` may fail.
|
||||
- In such environments, map the services to non-privileged host ports in the corresponding `docker-compose.yml` file.
|
||||
|
||||
### Resource constraints
|
||||
|
||||
For detailed information on resource requirements and recommendations, please refer to the [Requirements](../getting-started/requirements.md) section.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Performance
|
||||
|
||||
This section provides practical recommendations to improve performance for Wazuh Docker deployments (single-node and multi-node). Apply the controls that match your workload and environment.
|
||||
|
||||
## Performance drivers
|
||||
|
||||
- **Wazuh Indexer** is typically the main bottleneck (JVM heap, disk I/O, and CPU).
|
||||
- **Wazuh Manager** load grows with the number of connected agents and event throughput.
|
||||
- **Wazuh Dashboard** mainly affects interactive usage and depends on Indexer responsiveness.
|
||||
|
||||
For baseline host sizing and prerequisites, see [Requirements](getting-started/requirements.md).
|
||||
|
||||
## Storage and host
|
||||
|
||||
- Use low-latency storage for the Indexer data volume (see [Requirements](getting-started/requirements.md)).
|
||||
- Avoid slow or inconsistent storage for the Indexer (for example, network filesystems) unless you have validated latency and durability for your use case.
|
||||
- Monitor disk space growth. Index data and persistent volumes can grow quickly in high-ingest environments.
|
||||
|
||||
## Wazuh Indexer (OpenSearch)
|
||||
|
||||
- Set the JVM heap explicitly using `OPENSEARCH_JAVA_OPTS` (documented in [Environment variables](configuration/environment-variables.md)).
|
||||
- Keep heap sizing conservative relative to available memory so the OS can cache filesystem data; oversized heap commonly degrades disk-heavy workloads.
|
||||
- Ensure the Linux host meets the required `vm.max_map_count` prerequisite (documented in [Requirements](getting-started/requirements.md)).
|
||||
- Prioritize heap sizing and GC stability.
|
||||
- Prioritize disk throughput/latency for the Indexer data volume.
|
||||
- Prioritize CPU availability during ingest peaks.
|
||||
|
||||
## Wazuh Manager
|
||||
|
||||
- If you observe ingestion backpressure or delayed processing, validate that the Manager has sufficient CPU and memory and that persistent volumes are not constrained by slow storage.
|
||||
- For multi-node deployments, distribute agent load appropriately (for example, by separating responsibilities between master/worker nodes) to avoid overloading.
|
||||
|
||||
## Dashboard
|
||||
|
||||
- Dashboard responsiveness depends on Indexer health. Address Indexer resource constraints first when troubleshooting slow UI queries.
|
||||
- Avoid exposing the Dashboard to excessive concurrent users on small hosts; scale the host or deployment model if needed.
|
||||
|
||||
## Observability and troubleshooting
|
||||
|
||||
- Start with container-level signals: `docker stats`, container logs, and host disk utilization.
|
||||
- For Indexer issues, validate basic cluster health and look for sustained CPU saturation, JVM memory pressure, and disk I/O contention.
|
||||
- For Manager issues, review Manager logs for queue growth and repeated connection retries.
|
||||
@@ -0,0 +1,26 @@
|
||||
# Security
|
||||
|
||||
This section summarizes security recommendations for Wazuh Docker deployments (single-node and multi-node). Apply the controls that match your environment and risk profile.
|
||||
|
||||
## Credentials and secrets
|
||||
|
||||
- Do not use default credentials. The Compose examples include placeholder values for the Wazuh API, Dashboard, and Indexer access.
|
||||
- Prefer injecting secrets at runtime (for example, via your CI/CD secret store or an external secrets manager) instead of hardcoding them in `docker-compose.yml`.
|
||||
- Rotate credentials regularly and after any suspected exposure.
|
||||
|
||||
## Certificates and TLS
|
||||
|
||||
- Protect the generated `wazuh-certificates/` directory. Limit filesystem permissions and do not publish it.
|
||||
- Regenerate certificates if private keys are leaked or if nodes are re-provisioned.
|
||||
- Use certificates and TLS settings appropriate for production (trusted CA, correct DNS names, and key protection).
|
||||
|
||||
## Network exposure
|
||||
|
||||
- Restrict access to exposed service ports at the host firewall and security group level.
|
||||
- Do not expose internal-only endpoints to untrusted networks. In particular, limit access to the Indexer API port (`9200`) and the Wazuh API port (`55000`) to administrative networks.
|
||||
|
||||
## Host and runtime hardening
|
||||
|
||||
- Run Docker on a hardened host (patched OS, minimal installed packages, restricted SSH access).
|
||||
- Limit access to the Docker daemon. Docker socket access grants administrative control over the host.
|
||||
- Ensure persistent volumes and bind-mounted configuration files are backed by secure storage and appropriate permissions.
|
||||
@@ -0,0 +1,55 @@
|
||||
# Uninstall
|
||||
|
||||
This section describes how to uninstall a Wazuh Docker deployment by stopping and removing the resources created.
|
||||
|
||||
## Uninstalling single-node and multi-node deployments
|
||||
|
||||
1. Navigate to the deployment directory (`single-node` or `multi-node`):
|
||||
|
||||
```bash
|
||||
cd <deployment-directory>
|
||||
```
|
||||
|
||||
2. Stop and remove the containers:
|
||||
|
||||
```bash
|
||||
docker compose down --remove-orphans
|
||||
```
|
||||
|
||||
3. Remove persistent volumes and all stored data:
|
||||
|
||||
```bash
|
||||
docker compose down --volumes --remove-orphans
|
||||
```
|
||||
|
||||
4. Remove generated or downloaded files:
|
||||
|
||||
```bash
|
||||
rm -rf wazuh-certificates/ config.yml wazuh-certs-tool.sh
|
||||
```
|
||||
|
||||
5. Verify that the deployment is removed:
|
||||
|
||||
```bash
|
||||
docker ps
|
||||
```
|
||||
|
||||
## Wazuh agent deployment
|
||||
|
||||
1. Navigate to the agent deployment directory:
|
||||
|
||||
```bash
|
||||
cd wazuh-agent
|
||||
```
|
||||
|
||||
2. Stop and remove the container:
|
||||
|
||||
```bash
|
||||
docker compose down --remove-orphans
|
||||
```
|
||||
|
||||
3. Verify that the deployment is removed:
|
||||
|
||||
```bash
|
||||
docker ps
|
||||
```
|
||||
+74
-5
@@ -1,10 +1,79 @@
|
||||
# Upgrading Wazuh in Docker
|
||||
|
||||
To upgrade your Wazuh deployment when using Docker, we recommend following the official Wazuh documentation. It contains the most accurate and up-to-date information for upgrading from previous versions to the current one.
|
||||
To upgrade your Wazuh deployment when using Docker, the process primarily involves updating the image tags in your `docker-compose.yml` file to the desired version.
|
||||
|
||||
> 📘 Please refer to the official guide:
|
||||
> [Upgrading Wazuh Docker](https://documentation.wazuh.com/current/deployment-options/docker/upgrading-wazuh-docker.html)
|
||||
Below is a step-by-step example of how to perform this update:
|
||||
|
||||
This external guide provides detailed upgrade instructions that cover multiple scenarios and configurations.
|
||||
1. **Stop the current deployment**:
|
||||
Stop and remove the existing containers.
|
||||
```bash
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
Following the official documentation ensures a smoother and safer upgrade process, with fewer risks of data loss or configuration issues.
|
||||
2. **Update the image tags**:
|
||||
Edit your `docker-compose.yml` file and update the `image` field for all Wazuh services to the desired version.
|
||||
|
||||
### Single-node configuration
|
||||
Update the image tag for the following services in `single-node/docker-compose.yml`:
|
||||
- `wazuh.manager`
|
||||
- `wazuh.indexer`
|
||||
- `wazuh.dashboard`
|
||||
|
||||
Example (update to 5.0.0):
|
||||
|
||||
```yaml
|
||||
services:
|
||||
wazuh.manager:
|
||||
image: wazuh/wazuh-manager:5.0.0
|
||||
...
|
||||
|
||||
wazuh.indexer:
|
||||
image: wazuh/wazuh-indexer:5.0.0
|
||||
...
|
||||
|
||||
wazuh.dashboard:
|
||||
image: wazuh/wazuh-dashboard:5.0.0
|
||||
...
|
||||
```
|
||||
|
||||
### Multi-node configuration
|
||||
Update the image tag for the following services in `multi-node/docker-compose.yml`:
|
||||
- `wazuh.master`
|
||||
- `wazuh.worker`
|
||||
- `wazuh1.indexer`, `wazuh2.indexer`, and `wazuh3.indexer`
|
||||
- `wazuh.dashboard`
|
||||
|
||||
Example (update to 5.0.0):
|
||||
|
||||
```yaml
|
||||
services:
|
||||
wazuh.master:
|
||||
image: wazuh/wazuh-manager:5.0.0
|
||||
...
|
||||
|
||||
wazuh.worker:
|
||||
image: wazuh/wazuh-manager:5.0.0
|
||||
...
|
||||
|
||||
wazuh1.indexer:
|
||||
image: wazuh/wazuh-indexer:5.0.0
|
||||
...
|
||||
|
||||
wazuh2.indexer:
|
||||
image: wazuh/wazuh-indexer:5.0.0
|
||||
...
|
||||
|
||||
wazuh3.indexer:
|
||||
image: wazuh/wazuh-indexer:5.0.0
|
||||
...
|
||||
|
||||
wazuh.dashboard:
|
||||
image: wazuh/wazuh-dashboard:5.0.0
|
||||
...
|
||||
```
|
||||
|
||||
3. **Start the updated deployment**:
|
||||
Start the containers again. Docker will automatically pull the new images.
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user