Quickstart Guide

Get up and running with Wazuh Dashboard Plugins in minutes

Introduction

This quickstart guide will help you set up a development environment for Wazuh Dashboard Plugins using Docker. You’ll have a fully functional Wazuh dashboard running in under 15 minutes.

This guide assumes you have basic familiarity with Docker and command-line interfaces.

Quick Setup with Docker

Step 1: Install Prerequisites

1. Install Docker Desktop

   Download and install Docker Desktop for your operating system.

   Verify installation:

   docker --version
   docker compose version
   

   Ensure Docker Compose version is 2.20.2 or higher

2. Install Node.js

   Install Node.js version 22.22.0 using nvm:

   # Install nvm if you haven't already
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   
   # Install and use Node.js 22.22.0
   nvm install 22.22.0
   nvm use 22.22.0
   
3. Install Yarn

   npm install -g yarn
   

Step 2: Clone the Repository

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

Step 3: Set Up Docker Environment

1. Create Docker Networks

   docker network create devel
   docker network create mon
   
2. Install Loki Logging Driver

   docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions
   
3. Configure Docker Resources

   Open Docker Desktop and allocate:

   • Memory: 8 GB minimum
   • CPUs: 4 cores minimum

   Navigate to: Settings → Resources → Advanced

Step 4: Linux-Specific Setup

Linux Users: Set Permissions

If you’re on Linux, configure user permissions to avoid permission issues:

# Create docker-desktop group
sudo groupadd -g 100999 docker-desktop
sudo useradd -u 100999 -g 100999 -M docker-desktop

# Set permissions on the repository
sudo chown -R $USER:docker-desktop $(pwd)
sudo usermod -aG docker-desktop $USER

# Log out and log back in for changes to take effect

Step 5: Start the Development Environment

cd docker/osd-dev

# Start the environment with OpenSearch 3.5.0 and OpenSearch Dashboards 3.5.0
./dev.sh -o 3.5.0 -d 3.5.0 up

The first startup will take several minutes as Docker downloads the required images.

Step 6: Install Plugin Dependencies

1. Access the Container

   Open a new terminal and attach to the running container:

   # List running containers
   docker ps
   
   # Attach to the OpenSearch Dashboards container
   docker exec -it <container-name> bash
   
2. Install Dependencies

   Inside the container:

   # Navigate to the Wazuh plugin
   cd /usr/share/opensearch-dashboards/plugins/wazuh
   
   # Install dependencies
   yarn install
   
3. Start OpenSearch Dashboards

   # Navigate to OpenSearch Dashboards root
   cd /usr/share/opensearch-dashboards
   
   # Start the server
   yarn start
   

   The first start may take 5-10 minutes as it optimizes bundles.

Step 7: Access the Dashboard

Once the server starts successfully:

1. Open your browser
2. Navigate to http://localhost:5601
3. You should see the OpenSearch Dashboards login screen
4. Look for the Wazuh plugin in the main menu

Alternative: Development Without Docker

For a native development setup without Docker:

1. Install OpenSearch Dashboards

   Download and install OpenSearch Dashboards 3.5.0 from the official website.

2. Clone and Build Plugins

   git clone https://github.com/wazuh/wazuh-dashboard-plugins.git
   cd wazuh-dashboard-plugins
   
   # Set the OpenSearch Dashboards version
   export OPENSEARCH_DASHBOARDS_VERSION=3.5.0
   
   # Build wazuh-core
   cd plugins/wazuh-core
   yarn install
   yarn build
   
   # Build wazuh-check-updates
   cd ../wazuh-check-updates
   yarn install
   yarn build
   
   # Build main plugin
   cd ../main
   yarn install
   yarn build
   
3. Install Plugins

   cd /path/to/opensearch-dashboards
   
   # Install in dependency order
   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
   bin/opensearch-dashboards-plugin install file:///path/to/wazuh-dashboard-plugins/plugins/main/build/wazuh-5.0.0.zip
   
4. Start OpenSearch Dashboards

   bin/opensearch-dashboards
   

Exploring the Dashboard

First-Time Setup

When you first access the Wazuh dashboard:

1. Configure API Connection

   The Wazuh dashboard needs to connect to a Wazuh manager API. Configure your API host:

   • Host: Your Wazuh manager IP or hostname
   • Port: Usually 55000
   • Username: API username
   • Password: API password
2. Health Check

   The plugin automatically runs health checks:

   • API connectivity validation
   • Index pattern creation
   • Default configuration setup
3. Explore Modules

   Navigate through different security modules:

   • Security Events
   • Integrity Monitoring
   • Vulnerability Detection
   • Compliance (PCI DSS, GDPR, HIPAA, etc.)

Key Features to Try

Security Events

View real-time security alerts and events from your infrastructure

Agent Management

Monitor and manage Wazuh agents deployed across your systems

Compliance Dashboard

Check compliance status against PCI DSS, GDPR, and other standards

Dev Tools

Interact with the Wazuh API directly through the built-in console

Development Workflow

Making Changes

1. Edit Source Code

   The plugin source is mounted into the container, so you can edit files on your host:

   # Example: Edit a React component
   vim plugins/main/public/components/overview/overview.tsx
   
2. Rebuild (if needed)

   For TypeScript changes, you may need to rebuild:

   # Inside the container
   cd /usr/share/opensearch-dashboards/plugins/wazuh
   yarn build
   
3. Restart Server

   Restart OpenSearch Dashboards to see your changes:

   # Stop with Ctrl+C
   # Then restart
   yarn start
   

Running Tests

Jest Tests

cd plugins/main
yarn test:jest

Common Tasks

Updating API Information

When the Wazuh server API changes:

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

Adding External Plugins

To develop with external plugins like reporting:

# Clone external plugin
git clone https://github.com/wazuh/wazuh-dashboard-reporting.git ~/wazuh-dashboard-reporting

# Start environment with external plugin
cd docker/osd-dev
./dev.sh -o 3.5.0 -d 3.5.0 -r wazuh-dashboard-reporting=~/wazuh-dashboard-reporting up

Cleaning Up

# Stop the environment
cd docker/osd-dev
./dev.sh stop

# Remove containers
./dev.sh down

# Remove volumes (warning: deletes data)
docker compose down -v

Troubleshooting

Container Won't Start

Check Docker logs:

docker logs <container-name>

Ensure you have enough resources allocated in Docker Desktop.

Permission Denied Errors

On Linux, verify group permissions:

ls -la plugins/
sudo chown -R $USER:docker-desktop plugins/

Plugin Not Appearing

1. Verify plugin is installed: bin/opensearch-dashboards-plugin list
2. Check OpenSearch Dashboards logs for errors
3. Ensure all dependencies are installed correctly

Slow Build Times

Use the NPM cache server:

cd docker/cache
docker compose up -d

Next Steps

Architecture

Learn about the plugin architecture

Contributing

Contribute to the project

Style Guide

Follow coding standards

Join Slack

Get help from the community

Resources

• Wazuh Documentation
• OpenSearch Dashboards Documentation
• GitHub Repository
• Community Forums