Skip to main content
This guide covers the minimum toolchain and editor setup required for developing the Wazuh Dashboard Plugins.

​
Prerequisites

Before beginning development, ensure the following dependencies are installed on your system:

​
Required Tools

  • Git - Version control system
  • Node.js - Use the version specified in .nvmrc (currently 22.22.0)
  • Yarn v1 (Yarn Classic) - Package manager
  • Docker Desktop (optional) - Required for Docker-based development environments

​
Additional Utilities

For building packages and working with the full development workflow:
  • jq - Command-line JSON processor (used to read plugin versions)
  • zip, unzip - Archive utilities
  • gzip - Compression utility
  • brotli - Compression utility
  • curl - Data transfer utility

​
Installing Node.js with nvm

The recommended approach is to use Node Version Manager (nvm) to install and manage Node.js versions.
  1. Install nvm following the official installation guide
  2. Navigate to the repository root and install the required Node.js version: 
nvm install $(cat .nvmrc)
nvm use $(cat .nvmrc)
This automatically installs and activates Node.js 22.22.0 as specified in the .nvmrc file.

​
Installing Dependencies

The repository contains multiple plugins that require dependency installation. Install dependencies for each internal plugin: 
for plugin in plugins/main plugins/wazuh-core plugins/wazuh-check-updates; do
  (cd "$plugin" && yarn)
done
The main plugin downloads indexer resources during installation. Ensure the referenced wazuh-indexer-plugins Git reference exists. See External Resources for details.

​
Docker Desktop Setup

Docker Desktop provides a consistent development environment across Windows, macOS, and Linux.

​
Installation

  1. Install Docker Desktop following the official instructions for your operating system
  2. Ensure Docker Compose version is 2.20.2 or higher
  3. Review the system requirements for your platform

​
Resource Allocation

Allocate sufficient resources to Docker Desktop:
  • Memory: 8 GB minimum (more is recommended)
  • CPU Cores: 4 cores minimum

​
Network Configuration

Create the required Docker networks: 
docker network create devel
docker network create mon

​
Logging Driver

Install the Loki Docker logging driver for container log collection: 
docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions

​
User Permissions (Linux)

On Linux systems, configure Docker Desktop user permissions to avoid read-only volume issues: 
sudo groupadd -g 100999 docker-desktop
sudo useradd -u 100999 -g 100999 -M docker-desktop
sudo chown -R $USER:docker-desktop /path/to/wazuh-dashboard-plugins
sudo usermod -aG docker-desktop $USER
Restart your session after making these changes.

​
Editor Setup

Visual Studio Code is the recommended editor with the following extensions:
  • ESLint - JavaScript/TypeScript linting
  • Prettier - Code formatting
Enable format on save in VS Code settings for automatic code formatting.

​
Debugging

For runtime debugging, use the OpenSearch Dashboards development server (see Running from Sources). This provides:
  • Hot module reloading
  • Browser debugging for UI code
  • Server-side debugging for plugin backend code

​
Repository Structure

The repository follows a hybrid model: Internal Plugins (in this repository):
  • plugins/main - Main Wazuh dashboard plugin
  • plugins/wazuh-core - Core utilities and shared components
  • plugins/wazuh-check-updates - Update checking functionality
External Plugins (separate repositories):
  • wazuh-dashboard-reporting - Reporting functionality
  • wazuh-security-dashboards-plugin - Security features
  • wazuh-dashboard-security-analytics - Security analytics features

​
Environment Variables

For convenience when working with multiple repositories, set environment variables: 
# Add to ~/.bashrc or ~/.zshrc
export WZ_HOME=~/path/to/wazuh-dashboard-plugins/plugins
export WZ_REPORTING=~/path/to/wazuh-dashboard-reporting
export WZ_SECURITY=~/path/to/wazuh-security-dashboards-plugin
Apply changes: 
source ~/.bashrc  # or source ~/.zshrc
Verify the variables: 
echo $WZ_HOME
echo $WZ_REPORTING
echo $WZ_SECURITY

​
Verification

Verify your development environment is correctly configured: 
# Check Node.js version
node --version  # Should output v22.22.0

# Check Yarn version
yarn --version  # Should output 1.x.x

# Check Docker
docker --version
docker compose version  # Should be 2.20.2 or higher

# Verify networks
docker network ls | grep -E "devel|mon"

​
Next Steps

With your development environment configured:
  1. Build the plugins from source
  2. Run the development server
  3. Execute tests
  4. Review the contributing guidelines