Skip to main content
This guide explains how to build the Wazuh Dashboard Plugins from source code into distributable packages.

​
Build Types

There are two primary build workflows:
  1. Plugin-only builds - Build individual plugins as ZIP files for development
  2. System packages - Build complete DEB/RPM packages including the full dashboard distribution

​
Building Plugins from Source

This workflow builds only the plugins in this repository into distributable ZIP packages.

​
Prerequisites

  • Development environment configured (see Setup)
  • jq installed for reading plugin versions
  • Compatible Git reference from wazuh-indexer-plugins

​
Installing Dependencies

If dependencies are not already installed: 
# Set GIT_REF to a compatible wazuh-indexer-plugins branch/tag
export GIT_REF=main

# Install dependencies for main plugin (downloads indexer resources)
cd plugins/main
GIT_REF=$GIT_REF yarn
cd ../..

# Install dependencies for other plugins
for plugin in plugins/wazuh-core plugins/wazuh-check-updates; do
  (cd "$plugin" && yarn)
done
The main plugin requires the GIT_REF environment variable during installation to download resources from the wazuh-indexer-plugins repository. Ensure the referenced branch or tag exists and is compatible with your plugin version.

​
External Resources

The main plugin downloads external resources during the yarn installation:
  • Indexer resources from wazuh-indexer-plugins repository
  • API specification files for endpoint generation
The postinstall script automatically executes: 
yarn run generate:indexer-resources

​
Building Individual Plugins

Each plugin must be built with the OpenSearch Dashboards version declared in its package.json. 
# Read the OpenSearch Dashboards version from package.json
OPENSEARCH_DASHBOARDS_VERSION=$(jq -r .pluginPlatform.version plugins/main/package.json)

# Build main plugin
cd plugins/main
OPENSEARCH_DASHBOARDS_VERSION=$OPENSEARCH_DASHBOARDS_VERSION yarn build
cd ../..

# Build wazuh-core plugin
cd plugins/wazuh-core
OPENSEARCH_DASHBOARDS_VERSION=$OPENSEARCH_DASHBOARDS_VERSION yarn build
cd ../..

# Build wazuh-check-updates plugin
cd plugins/wazuh-check-updates
OPENSEARCH_DASHBOARDS_VERSION=$OPENSEARCH_DASHBOARDS_VERSION yarn build
cd ../..

​
Build Artifacts

Build artifacts are written to each plugin’s build/ directory:
  • plugins/main/build/wazuh-<version>.zip
  • plugins/wazuh-core/build/wazuhCore-<version>.zip
  • plugins/wazuh-check-updates/build/wazuhCheckUpdates-<version>.zip

​
Building Inside Docker

The recommended workflow is to build inside the Docker development environment. This ensures:
  • Required OpenSearch Dashboards build helpers are available
  • Build matches the target platform
  • Consistent build environment across different machines
Start the development environment and execute build commands from within the container: 
cd docker/osd-dev
./dev.sh up
Attach to the container: 
docker ps
docker exec -it <CONTAINER_ID> bash
From inside the container, run the build commands as described above.

​
Running from Sources

The recommended method for running plugins during development is using the Docker-based development environments.

​
Starting the Development Environment

Navigate to the OpenSearch Dashboards development environment: 
cd docker/osd-dev
./dev.sh up
The script automatically detects versions from plugins/wazuh-core/package.json and internal plugins from plugins/.

​
Specify Versions

To use specific OpenSearch and OpenSearch Dashboards versions: 
./dev.sh up -os 2.11.0 -osd 2.11.0

​
Development with Agents

Include Wazuh agents in the environment: 
# DEB-based agent
./dev.sh up --server-local my-tag -a deb

# RPM-based agent
./dev.sh up --server-local my-tag -a rpm

# Without agents
./dev.sh up --server-local my-tag -a without

​
SAML Environment

Enable SAML authentication: 
./dev.sh up -saml

​
External Plugin Repositories

Mount external plugin repositories using the -r flag: 
./dev.sh up -os 2.11.0 -osd 2.11.0 \
  -r wazuh-dashboard-reporting=$WZ_REPORTING \
  -r wazuh-security-dashboards-plugin=$WZ_SECURITY

​
Environment Components

The Docker environment includes:
  • OpenSearch single-node cluster - Indexer for Wazuh data
  • Wazuh manager - Real or local build depending on flags
  • OpenSearch Dashboards dev environment - Bootstrapped with pre-compiled node modules
  • Wazuh agents (optional) - Deployed based on -a flag
  • Imposter - Mock server for testing
  • Elasticsearch-exporter - Metrics adapter for Prometheus

​
Starting the Development Server

Attach a shell to the development container: 
docker ps
docker exec -it <CONTAINER_ID> bash
From inside the container: 
yarn start --no-base-path
The dashboard becomes available at:

​
Hot Reloading

The development server supports hot module reloading. Changes to plugin code are automatically detected and reloaded without restarting the server.

​
Package Scripts

The main plugin package.json includes several useful scripts:

​
Linting

yarn lint              # Lint all code
yarn lint:public       # Lint public (client) code
yarn lint:server       # Lint server code
yarn lint:common       # Lint common code
yarn lint:fix          # Auto-fix linting issues

​
Formatting

yarn format            # Format code with Prettier

​
Testing

yarn test:jest         # Run Jest unit tests
yarn test:server       # Run server tests
yarn test:browser      # Run browser tests
See Testing for detailed testing information.

​
Building

yarn build             # Build plugin (requires OPENSEARCH_DASHBOARDS_VERSION)

​
API Data Generation

yarn generate:api-data # Generate API endpoint data from spec
This script downloads the Wazuh API specification and generates:
  • common/api-info/endpoints.json - API endpoint definitions
  • common/api-info/security-actions.json - Security action definitions

​
Building System Packages

To build complete DEB or RPM system packages, see the detailed guide in the source repository at docs/dev/build-packages.md. This process:
  1. Builds the base Wazuh Dashboard
  2. Builds all plugin dependencies
  3. Packages everything into distributable system packages
Key steps:
  1. Clone and build wazuh-dashboard
  2. Clone and build wazuh-security-dashboards-plugin
  3. Clone and build wazuh-dashboard-plugins
  4. Clone and build wazuh-dashboard-reporting
  5. Clone and build wazuh-dashboard-security-analytics
  6. Create ZIP packages
  7. Run build-packages.sh script
Refer to ~/workspace/source/docs/dev/build-packages.md for the complete workflow.

​
Troubleshooting

​
Missing Dependencies

If build fails with missing dependencies: 
cd plugins/<plugin-name>
yarn install

​
OpenSearch Dashboards Version Mismatch

Ensure the OPENSEARCH_DASHBOARDS_VERSION environment variable matches the version in package.json: 
jq -r .pluginPlatform.version plugins/main/package.json

​
Indexer Resources Download Failure

If the main plugin fails to download indexer resources, verify:
  1. GIT_REF environment variable is set
  2. The referenced branch/tag exists in wazuh-indexer-plugins
  3. Network connectivity to GitHub

​
Docker Build Issues

If building inside Docker fails:
  1. Ensure sufficient resources allocated to Docker Desktop
  2. Check Docker daemon is running
  3. Verify networks exist: docker network ls

​
Next Steps