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
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
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
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
Create Docker Networks
docker network create devel docker network create mon
Install Loki Logging Driver
docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions
Configure Docker Resources
Open Docker Desktop and allocate:
Memory : 8 GB minimumCPUs : 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
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-nam e > bash
Install Dependencies
Inside the container: # Navigate to the Wazuh plugin cd /usr/share/opensearch-dashboards/plugins/wazuh # Install dependencies yarn install
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:
Open your browser
Navigate to http://localhost:5601
You should see the OpenSearch Dashboards login screen
Look for the Wazuh plugin in the main menu
Alternative: Development Without Docker For a native development setup without Docker:
Install OpenSearch Dashboards
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
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
Start OpenSearch Dashboards
bin/opensearch-dashboards
Exploring the Dashboard First-Time Setup When you first access the Wazuh dashboard:
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
Health Check
The plugin automatically runs health checks:
API connectivity validation
Index pattern creation
Default configuration setup
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
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
Rebuild (if needed)
For TypeScript changes, you may need to rebuild: # Inside the container cd /usr/share/opensearch-dashboards/plugins/wazuh yarn build
Restart Server
Restart OpenSearch Dashboards to see your changes: # Stop with Ctrl+C # Then restart yarn start
Running Tests Jest Tests
Linting
Type Checking
cd plugins/main yarn test:jest
Common Tasks 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
Check Docker logs: docker logs < container-nam e >
Ensure you have enough resources allocated in Docker Desktop.
On Linux, verify group permissions: ls -la plugins/ sudo chown -R $USER :docker-desktop plugins/
Verify plugin is installed: bin/opensearch-dashboards-plugin list
Check OpenSearch Dashboards logs for errors
Ensure all dependencies are installed correctly
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 