> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wazuh/wazuh-dashboard-plugins/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`)

```bash theme={null}
# Using nvm (recommended)
nvm install 22.22.0
nvm use 22.22.0
```

**2. Yarn Package Manager**

Install Yarn for dependency management

```bash theme={null}
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**

```bash theme={null}
git clone https://github.com/wazuh/wazuh-dashboard-plugins.git
cd wazuh-dashboard-plugins
```

**2. Install Dependencies**

Install dependencies for each plugin:

```bash theme={null}
# 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:

```bash theme={null}
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**

```bash theme={null}
export OPENSEARCH_DASHBOARDS_VERSION=3.5.0
```

**2. Build the Main Plugin**

```bash theme={null}
cd plugins/main
yarn build
```

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

**3. Build Core Plugins**

```bash theme={null}
# Wazuh Core
cd plugins/wazuh-core
yarn build

# Wazuh Check Updates
cd ../wazuh-check-updates
yarn build
```

**4. Install to OpenSearch Dashboards**

```bash theme={null}
# 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
```

> [!WARNING]
>
> 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](https://docs.docker.com/get-docker/) with Docker Compose v2.20.2 or higher

**2. Create Docker Networks**

```bash theme={null}
docker network create devel
docker network create mon
```

**3. Install Loki Driver**

```bash theme={null}
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)**

```bash theme={null}
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

```bash Basic Usage theme={null}
cd docker/osd-dev
./dev.sh -o 3.5.0 -d 3.5.0 up
```

```bash With External Plugins theme={null}
# Set environment variables for external plugins
export WZ_REPORTING=~/path/to/wazuh-dashboard-reporting
export WZ_SECURITY=~/path/to/wazuh-security-dashboards-plugin

# Start with external plugins
./dev.sh -o 3.5.0 -d 3.5.0 \
  -r wazuh-dashboard-reporting=$WZ_REPORTING \
  -r wazuh-security-dashboards-plugin=$WZ_SECURITY up
```

```bash Auto-detection Mode theme={null}
# Run from inside the repository (detects internal plugins automatically)
./dev.sh -o 3.5.0 -d 3.5.0 up
```

### Working Inside the Container

**1. Attach to Container**

```bash theme={null}
docker exec -it <container-name> bash
```

**2. Install Dependencies**

```bash theme={null}
cd /usr/share/opensearch-dashboards/plugins/wazuh
yarn install
```

**3. Start OpenSearch Dashboards**

```bash theme={null}
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:

```json theme={null}
{
  "name": "wazuh",
  "version": "5.0.0",
  "revision": "00",
  "pluginPlatform": {
    "version": "3.5.0"
  },
  "description": "Wazuh dashboard"
}
```

### Key Scripts

```bash Linting theme={null}
# Lint all code
yarn lint

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

# Auto-fix issues
yarn lint:fix
```

```bash Testing theme={null}
# Run Jest tests
yarn test:jest

# Run server tests
yarn test:server

# Run browser tests
yarn test:browser
```

```bash Building theme={null}
# Build the plugin
yarn build

# Build with specific OpenSearch Dashboards version
OPENSEARCH_DASHBOARDS_VERSION=3.5.0 yarn build
```

```bash Development theme={null}
# Start development server
yarn start

# Format code
yarn format
```

## Post-Installation

### Verify Installation

**1. Check Plugin List**

```bash theme={null}
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**

```bash theme={null}
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

> [!TIP]
>
> 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:
>
> ```bash theme={null}
> node --version  # Should output v22.22.0
> nvm use 22.22.0
> ```

> **Build Failures**
>
> Clear the build cache and reinstall:
>
> ```bash theme={null}
> rm -rf node_modules build
> yarn cache clean
> yarn install
> yarn build
> ```

> **Docker Permission Errors**
>
> On Linux, ensure proper group permissions:
>
> ```bash theme={null}
> 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](https://mintlify.com/wazuh/wazuh-dashboard-plugins/quickstart.md)**
>
> Set up your first Wazuh environment

> **[Compatibility Matrix](https://mintlify.com/wazuh/wazuh-dashboard-plugins/compatibility.md)**
>
> Check version compatibility

> **[Contributing](https://github.com/wazuh/wazuh-dashboard-plugins/blob/master/CONTRIBUTING.md)**
>
> Learn how to contribute

> **[Development Guide](https://github.com/wazuh/wazuh-dashboard-plugins/blob/master/STYLEGUIDE.md)**
>
> Review coding standards


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.