> ## 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.

# Building the Plugins

> Build Wazuh Dashboard Plugins from source for development or distribution

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](/development/setup))
* `jq` installed for reading plugin versions
* Compatible Git reference from [wazuh-indexer-plugins](https://github.com/wazuh/wazuh-indexer-plugins)

### Installing Dependencies

If dependencies are not already installed:

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

> [!WARNING]
>
> 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:

```bash theme={null}
yarn run generate:indexer-resources
```

### Building Individual Plugins

Each plugin must be built with the OpenSearch Dashboards version declared in its `package.json`.

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

```bash theme={null}
cd docker/osd-dev
./dev.sh up
```

Attach to the container:

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

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

```bash theme={null}
./dev.sh up -os 2.11.0 -osd 2.11.0
```

#### Development with Agents

Include Wazuh agents in the environment:

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

```bash theme={null}
./dev.sh up -saml
```

#### External Plugin Repositories

Mount external plugin repositories using the `-r` flag:

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

```bash theme={null}
docker ps
docker exec -it <CONTAINER_ID> bash
```

From inside the container:

```bash theme={null}
yarn start --no-base-path
```

The dashboard becomes available at:

* **URL**: [https://0.0.0.0:5601/](https://0.0.0.0:5601/)
* **Default credentials**: `admin:admin`
* **SAML credentials**: `wazuh:wazuh`

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

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

```bash theme={null}
yarn format            # Format code with Prettier
```

### Testing

```bash theme={null}
yarn test:jest         # Run Jest unit tests
yarn test:server       # Run server tests
yarn test:browser      # Run browser tests
```

See [Testing](/development/testing) for detailed testing information.

### Building

```bash theme={null}
yarn build             # Build plugin (requires OPENSEARCH_DASHBOARDS_VERSION)
```

### API Data Generation

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

```bash theme={null}
cd plugins/<plugin-name>
yarn install
```

### OpenSearch Dashboards Version Mismatch

Ensure the `OPENSEARCH_DASHBOARDS_VERSION` environment variable matches the version in `package.json`:

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

* [Run tests](/development/testing) on the built plugins
* [Contribute](/development/contributing) improvements
* Review [source repository documentation](https://github.com/wazuh/wazuh-dashboard-plugins/tree/main/docs/dev)


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