Development Environment Setup

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.

Install nvm following the official installation guide
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

Install Docker Desktop following the official instructions for your operating system
Ensure Docker Compose version is 2.20.2 or higher
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

Recommended Configuration

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:

Get Started

Core Concepts

Security Modules

Compliance

Cloud Integrations

Agent Management

Configuration

Development

Prerequisites

Required Tools

Additional Utilities

Installing Node.js with nvm

Installing Dependencies

Docker Desktop Setup

Installation

Resource Allocation

Network Configuration

Logging Driver

User Permissions (Linux)

Editor Setup

Recommended Configuration

Debugging

Repository Structure

Environment Variables

Verification

Next Steps

​Prerequisites

​Required Tools

​Additional Utilities

​Installing Node.js with nvm

​Installing Dependencies

​Docker Desktop Setup

​Installation

​Resource Allocation

​Network Configuration

​Logging Driver

​User Permissions (Linux)

​Editor Setup

​Recommended Configuration

​Debugging

​Repository Structure

​Environment Variables

​Verification

​Next Steps

Prerequisites

Required Tools

Additional Utilities

Installing Node.js with nvm

Installing Dependencies

Docker Desktop Setup

Installation

Resource Allocation

Network Configuration

Logging Driver

User Permissions (Linux)

Editor Setup

Recommended Configuration

Debugging

Repository Structure

Environment Variables

Verification

Next Steps