Installation Guide

Complete guide to installing and configuring Wazuh Dashboard Plugins for development and production environments

Prerequisites

Before installing Wazuh Dashboard Plugins, ensure you have the following:

1. Node.js

   Install Node.js version 22.22.0 (as specified in .nvmrc)

   # Using nvm (recommended)
   nvm install 22.22.0
   nvm use 22.22.0
   
2. Yarn Package Manager

   Install Yarn for dependency management

   npm install -g yarn
   
3. OpenSearch Dashboards

   Have a compatible OpenSearch Dashboards instance (version 3.5.0 for Wazuh 5.0.0)

Installation Methods

Method 1: Development Installation

For development purposes, you’ll work with the source code directly.

1. Clone the Repository

   git clone https://github.com/wazuh/wazuh-dashboard-plugins.git
   cd wazuh-dashboard-plugins
   
2. Install Dependencies

   Install dependencies for each plugin:

   # Main plugin
   cd plugins/main
   yarn install
   
   # Wazuh Core plugin
   cd ../wazuh-core
   yarn install
   
   # Wazuh Check Updates plugin
   cd ../wazuh-check-updates
   yarn install
   
3. Generate API Data

   Update API information from the Wazuh server specification:

   cd plugins/main
   yarn generate:api-data --spec https://raw.githubusercontent.com/wazuh/wazuh/v5.0.0/api/api/spec/spec.yaml
   

Method 2: Building from Source

Build distributable plugin packages for installation.

1. Set Environment Variables

   export OPENSEARCH_DASHBOARDS_VERSION=3.5.0
   
2. Build the Main Plugin

   cd plugins/main
   yarn build
   

   The build artifact will be created in plugins/main/build/

3. Build Core Plugins

   # Wazuh Core
   cd plugins/wazuh-core
   yarn build
   
   # Wazuh Check Updates
   cd ../wazuh-check-updates
   yarn build
   
4. Install to OpenSearch Dashboards

   # Navigate to your OpenSearch Dashboards installation
   cd /path/to/opensearch-dashboards
   
   # Install the plugins
   bin/opensearch-dashboards-plugin install file:///path/to/wazuh-dashboard-plugins/plugins/main/build/wazuh-5.0.0.zip
   bin/opensearch-dashboards-plugin install file:///path/to/wazuh-dashboard-plugins/plugins/wazuh-core/build/wazuhCore-5.0.0.zip
   bin/opensearch-dashboards-plugin install file:///path/to/wazuh-dashboard-plugins/plugins/wazuh-check-updates/build/wazuhCheckUpdates-5.0.0.zip
   

Plugins must be installed in the correct order due to dependencies:

1. wazuh-core
2. wazuh-check-updates
3. main (wazuh)

Docker Development Environment

Wazuh provides Docker-based development environments for easier setup.

Prerequisites

1. Install Docker Desktop

   Install Docker Desktop with Docker Compose v2.20.2 or higher

2. Create Docker Networks

   docker network create devel
   docker network create mon
   
3. Install Loki Driver

   docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions
   
4. Allocate Resources

   Configure Docker Desktop with:

   • Minimum 8 GB RAM
   • 4 CPU cores
5. Set Up Permissions (Linux)

   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
   

Starting the Development Environment

Basic Usage

cd docker/osd-dev
./dev.sh -o 3.5.0 -d 3.5.0 up

Working Inside the Container

1. Attach to Container

   docker exec -it <container-name> bash
   
2. Install Dependencies

   cd /usr/share/opensearch-dashboards/plugins/wazuh
   yarn install
   
3. Start OpenSearch Dashboards

   cd /usr/share/opensearch-dashboards
   yarn start
   

Configuration

Plugin Dependencies

The main Wazuh plugin requires these OpenSearch Dashboards plugins:

Required Plugins

• navigation
• data
• dashboard
• embeddable
• discover
• inspector
• visualizations
• uiActions
• charts
• savedObjects
• opensearchDashboardsReact
• opensearchDashboardsUtils
• opensearchDashboardsLegacy
• wazuhCheckUpdates
• wazuhCore

Optional Plugins

• security
• securityDashboards
• searchguard
• telemetry
• notificationsDashboards
• alertingDashboards
• reportsDashboards

Package.json Overview

The main plugin’s package.json defines:

{
  "name": "wazuh",
  "version": "5.0.0",
  "revision": "00",
  "pluginPlatform": {
    "version": "3.5.0"
  },
  "description": "Wazuh dashboard"
}

Key Scripts

Linting

# Lint all code
yarn lint

# Lint specific areas
yarn lint:public
yarn lint:server
yarn lint:common

# Auto-fix issues
yarn lint:fix

Post-Installation

Verify Installation

1. Check Plugin List

   bin/opensearch-dashboards-plugin list
   

   You should see:

   • wazuh@5.0.0-00
   • wazuhCore@5.0.0-00
   • wazuhCheckUpdates@5.0.0-00
2. Start OpenSearch Dashboards

   bin/opensearch-dashboards
   
3. Access the Dashboard

   Navigate to http://localhost:5601 and verify the Wazuh plugin appears in the menu

Health Check

The Wazuh plugin includes automatic health checks that run on startup:

• Index pattern validation
• API connectivity tests
• Server compatibility checks
• Default configuration setup

Check the OpenSearch Dashboards logs at logs/opensearch_dashboards.log if you encounter issues during startup.

Troubleshooting

Common Issues

Node Version Mismatch

Ensure you’re using Node.js 22.22.0:

node --version  # Should output v22.22.0
nvm use 22.22.0

Build Failures

Clear the build cache and reinstall:

rm -rf node_modules build
yarn cache clean
yarn install
yarn build

Docker Permission Errors

On Linux, ensure proper group permissions:

sudo chown -R $USER:docker-desktop /path/to/plugins

Plugin Not Loading

Check plugin dependencies are installed in correct order and that opensearch_dashboards.json specifies the right platform version.

Next Steps

Quickstart Guide

Set up your first Wazuh environment

Compatibility Matrix

Check version compatibility

Contributing

Learn how to contribute

Development Guide

Review coding standards