Custom OpenSearch Dashboards Packaging Guide: Building from Source with Custom Plugins#

This comprehensive guide covers building OpenSearch Dashboards from source with custom plugins and creating custom Debian packages for deployment. Whether you need to integrate custom visualizations or modify the core functionality, this guide provides multiple approaches for packaging OpenSearch Dashboards.

Overview#

Why Custom Packaging?#

Custom packaging of OpenSearch Dashboards provides several advantages:

Custom Plugin Integration: Include proprietary or custom-developed plugins
Configuration Control: Pre-configure dashboards with specific settings
Security Hardening: Apply security patches or customizations
Resource Optimization: Remove unnecessary components or add optimizations
Enterprise Deployment: Create standardized packages for enterprise environments

Build Methods#

Standard Build: Using OpenSearch’s built-in build system
Manual Packaging: Creating Debian packages from scratch
Custom Plugin Build: Including additional plugins in the build

Prerequisites#

System Requirements#

1
# Minimum requirements for building OpenSearch Dashboards
2
# - CPU: 8+ cores (16+ recommended)
3
# - RAM: 16GB+ (32GB recommended)
4
# - Disk: 50GB+ free space
5
# - OS: Ubuntu 20.04+ or compatible Linux distribution
6

7
# Install essential build dependencies
8
sudo apt-get update
9
sudo apt-get install -y \
10
    git \
11
    curl \
12
    wget \
13
    build-essential \
14
    nodejs \
15
    npm \
16
    ruby \
17
    ruby-dev \
18
    rpm \
19
    python3 \
20
    python3-pip \
21
    dpkg-dev \
22
    debhelper

Node.js Version Management#

OpenSearch Dashboards requires specific Node.js versions:

1
# Install nvm (Node Version Manager)
2
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
3
source ~/.bashrc
4

5
# The .nvmrc file in the repository specifies the required Node.js version
6
# This will be used automatically when you run nvm use

Development Tools#

1
# Install Yarn package manager
2
npm install -g yarn
3

4
# Install additional build tools
5
npm install -g node-gyp

Standard Build Process#

1. Source Code Preparation#

1
# Clone OpenSearch Dashboards repository
2
git clone https://github.com/opensearch-project/OpenSearch-Dashboards.git
3
cd OpenSearch-Dashboards
4

5
# Checkout specific version (2.18.0 in this example)
6
git checkout 2.18.0
7

8
# Use the required Node.js version
9
nvm install $(cat .nvmrc)
10
nvm use $(cat .nvmrc)
11

12
# Verify Node.js version
13
node --version
14
npm --version

2. Dependency Installation#

1
# Install dependencies using Yarn
2
yarn install
3

4
# Alternative: Use npm if preferred
5
# npm install
6

7
# Bootstrap plugins (this process can take 30+ minutes)
8
yarn osd bootstrap

3. Custom Plugin Integration (Pre-Build)#

If you have custom plugins to include:

1
# Create plugins directory if it doesn't exist
2
mkdir -p plugins
3

4
# Copy your custom plugins
5
cp -r /path/to/your/custom/plugins/* plugins/
6

7
# Example plugin structure:
8
# plugins/
9
# ├── my-custom-plugin/
10
# │   ├── package.json
11
# │   ├── public/
12
# │   ├── server/
13
# │   └── kibana.json
14

15
# Install plugin dependencies
16
cd plugins/my-custom-plugin
17
yarn install
18
cd ../..

4. Build Process#

1
# Build OpenSearch Dashboards (this can take 1+ hours)
2
yarn build --skip-os-packages
3

4
# Alternative: Build with OS packages
5
yarn build --deb
6

7
# The built files will be in:
8
# - build/opensearch-dashboards/ (application files)
9
# - build/opensearch-dashboards-*.deb (if building packages)

Manual Debian Package Creation#

1. Package Structure Setup#

1
# Create package directory structure
2
mkdir -p opensearch-dashboards-2.18.0/DEBIAN
3
mkdir -p opensearch-dashboards-2.18.0/usr/share/opensearch-dashboards
4
mkdir -p opensearch-dashboards-2.18.0/etc/opensearch-dashboards
5
mkdir -p opensearch-dashboards-2.18.0/var/log/opensearch-dashboards
6
mkdir -p opensearch-dashboards-2.18.0/var/lib/opensearch-dashboards
7
mkdir -p opensearch-dashboards-2.18.0/lib/systemd/system
8

9
# Set proper ownership for package building
10
sudo chown -R $USER:$USER opensearch-dashboards-2.18.0/

2. Copy Built Application#

1
# Copy built application files
2
cp -r build/opensearch-dashboards/* opensearch-dashboards-2.18.0/usr/share/opensearch-dashboards/
3

4
# Create directory structure in the package
5
mkdir -p opensearch-dashboards-2.18.0/usr/share/opensearch-dashboards/{bin,config,plugins,data}
6

7
# Ensure proper permissions for executables
8
chmod +x opensearch-dashboards-2.18.0/usr/share/opensearch-dashboards/bin/*

3. Create Package Control Files#

Control File#

1
cat > opensearch-dashboards-2.18.0/DEBIAN/control << 'EOF'
2
Package: opensearch-dashboards
3
Version: 2.18.0-custom1
4
Section: web
5
Priority: optional
6
Architecture: amd64
7
Depends: libnss3, libatk-bridge2.0-0, libgtk-3-0, libx11-xcb1, libxcomposite1, libxcursor1, libxdamage1, libxi6, libxtst6, libasound2
8
Maintainer: Your Organization <admin@yourorg.com>
9
Description: OpenSearch Dashboards with custom plugins
10
 Custom build of OpenSearch Dashboards including specific plugins
11
 and configurations for enterprise deployment.
12
 .
13
 OpenSearch Dashboards is a data visualization dashboard for OpenSearch.
14
Installed-Size: 1048576
15
EOF

Pre-installation Script#

1
cat > opensearch-dashboards-2.18.0/DEBIAN/preinst << 'EOF'
2
#!/bin/bash
3
set -e
4

5
# Create opensearch-dashboards group if it doesn't exist
6
if ! getent group opensearch-dashboards >/dev/null; then
7
    groupadd -r opensearch-dashboards
8
fi
9

10
# Create opensearch-dashboards user if it doesn't exist
11
if ! getent passwd opensearch-dashboards >/dev/null; then
12
    useradd -r -g opensearch-dashboards -d /usr/share/opensearch-dashboards \
13
            -s /sbin/nologin -c "OpenSearch Dashboards Service User" opensearch-dashboards
14
fi
15

16
# Create necessary directories
17
mkdir -p /var/log/opensearch-dashboards
18
mkdir -p /var/lib/opensearch-dashboards
19
mkdir -p /etc/opensearch-dashboards
20

21
exit 0
22
EOF

Post-installation Script#

1
cat > opensearch-dashboards-2.18.0/DEBIAN/postinst << 'EOF'
2
#!/bin/bash
3
set -e
4

5
# Set ownership and permissions
6
chown -R opensearch-dashboards:opensearch-dashboards /usr/share/opensearch-dashboards
7
chown -R opensearch-dashboards:opensearch-dashboards /var/log/opensearch-dashboards
8
chown -R opensearch-dashboards:opensearch-dashboards /var/lib/opensearch-dashboards
9
chown -R opensearch-dashboards:opensearch-dashboards /etc/opensearch-dashboards
10

11
# Set directory permissions
12
chmod 750 /usr/share/opensearch-dashboards
13
chmod 750 /var/log/opensearch-dashboards
14
chmod 750 /var/lib/opensearch-dashboards
15
chmod 750 /etc/opensearch-dashboards
16

17
# Set file permissions
18
chmod 755 /usr/share/opensearch-dashboards/bin/opensearch-dashboards
19
chmod 755 /usr/share/opensearch-dashboards/bin/opensearch-dashboards-plugin
20

21
# Configure systemd service
22
systemctl daemon-reload
23
systemctl enable opensearch-dashboards.service
24

25
# Create data directory symlink if it doesn't exist
26
if [ ! -L /usr/share/opensearch-dashboards/data ]; then
27
    ln -sf /var/lib/opensearch-dashboards /usr/share/opensearch-dashboards/data
28
fi
29

30
echo "OpenSearch Dashboards installed successfully."
31
echo "Configuration file: /etc/opensearch-dashboards/opensearch_dashboards.yml"
32
echo "Start service: sudo systemctl start opensearch-dashboards"
33

34
exit 0
35
EOF

Pre-removal Script#

1
cat > opensearch-dashboards-2.18.0/DEBIAN/prerm << 'EOF'
2
#!/bin/bash
3
set -e
4

5
# Stop service if running
6
if systemctl is-active --quiet opensearch-dashboards; then
7
    systemctl stop opensearch-dashboards
8
fi
9

10
# Disable service
11
if systemctl is-enabled --quiet opensearch-dashboards; then
12
    systemctl disable opensearch-dashboards
13
fi
14

15
exit 0
16
EOF

4. Create Configuration Files#

Default Configuration#

1
# Copy default configuration
2
cp config/opensearch_dashboards.yml opensearch-dashboards-2.18.0/etc/opensearch-dashboards/
3

4
# Add custom paths to configuration
5
cat >> opensearch-dashboards-2.18.0/etc/opensearch-dashboards/opensearch_dashboards.yml << 'EOF'
6

7
# Custom paths for packaged installation
8
path.data: /var/lib/opensearch-dashboards
9
logging.dest: /var/log/opensearch-dashboards/opensearch_dashboards.log
10

11
# Security settings
12
server.ssl.enabled: false
13
opensearch.ssl.verificationMode: none
14

15
# Custom branding (if applicable)
16
opensearchDashboards.branding.mark: "data:image/svg+xml;base64,..."
17
opensearchDashboards.branding.title: "Custom OpenSearch Dashboards"
18
EOF

Systemd Service File#

1
cat > opensearch-dashboards-2.18.0/lib/systemd/system/opensearch-dashboards.service << 'EOF'
2
[Unit]
3
Description=OpenSearch Dashboards
4
Documentation=https://opensearch.org/docs/dashboards
5
Wants=network-online.target
6
After=network-online.target
7
RequiresMountsFor=/var/lib/opensearch-dashboards
8

9
[Service]
10
Type=simple
11
User=opensearch-dashboards
12
Group=opensearch-dashboards
13
Environment=NODE_ENV=production
14
Environment=CONFIG_PATH=/etc/opensearch-dashboards/opensearch_dashboards.yml
15
Environment=NODE_OPTIONS="--max-old-space-size=4096"
16
ExecStart=/usr/share/opensearch-dashboards/bin/opensearch-dashboards
17
Restart=always
18
RestartSec=3
19
StartLimitBurst=3
20
StartLimitInterval=60
21
TimeoutStopSec=30
22
KillMode=mixed
23
KillSignal=SIGTERM
24

25
# Security settings
26
NoNewPrivileges=true
27
ProtectSystem=strict
28
ProtectHome=true
29
ReadWritePaths=/var/lib/opensearch-dashboards
30
ReadWritePaths=/var/log/opensearch-dashboards
31
PrivateTmp=true
32
ProtectKernelTunables=true
33
ProtectControlGroups=true
34
RestrictSUIDSGID=true
35

36
# Resource limits
37
LimitNOFILE=65536
38
LimitMEMLOCK=infinity
39

40
[Install]
41
WantedBy=multi-user.target
42
EOF

5. Make Scripts Executable#

1
# Make maintainer scripts executable
2
chmod 755 opensearch-dashboards-2.18.0/DEBIAN/preinst
3
chmod 755 opensearch-dashboards-2.18.0/DEBIAN/postinst
4
chmod 755 opensearch-dashboards-2.18.0/DEBIAN/prerm

6. Build the Package#

1
# Build the Debian package
2
dpkg-deb --build opensearch-dashboards-2.18.0
3

4
# Verify package
5
dpkg-deb --info opensearch-dashboards-2.18.0.deb
6
dpkg-deb --contents opensearch-dashboards-2.18.0.deb
7

8
# Check package with Lintian (optional)
9
lintian opensearch-dashboards-2.18.0.deb

Custom Plugin Integration#

Plugin Development Structure#

1
# Example custom plugin structure
2
mkdir -p plugins/my-security-plugin
3

4
cat > plugins/my-security-plugin/package.json << 'EOF'
5
{
6
  "name": "my-security-plugin",
7
  "version": "2.18.0",
8
  "description": "Custom security visualization plugin",
9
  "main": "index.js",
10
  "opensearchDashboardsVersion": "2.18.0",
11
  "dependencies": {
12
    "react": "^16.14.0",
13
    "react-dom": "^16.14.0"
14
  }
15
}
16
EOF
17

18
cat > plugins/my-security-plugin/opensearch_dashboards.json << 'EOF'
19
{
20
  "id": "mySecurityPlugin",
21
  "version": "2.18.0",
22
  "opensearchDashboardsVersion": "2.18.0",
23
  "server": true,
24
  "ui": true,
25
  "requiredPlugins": ["data", "navigation"],
26
  "optionalPlugins": []
27
}
28
EOF

Plugin Build Integration#

1
# Build plugins during the main build process
2
yarn osd bootstrap
3

4
# Verify plugin is included
5
ls -la build/opensearch-dashboards/plugins/

Build Optimization#

Performance Optimization#

1
# Set Node.js memory limits for large builds
2
export NODE_OPTIONS="--max-old-space-size=8192"
3

4
# Use parallel builds where possible
5
export JOBS=8
6

7
# Optimize build for production
8
yarn build --skip-os-packages --skip-archives --release

Size Optimization#

1
# Remove development dependencies from final package
2
cd opensearch-dashboards-2.18.0/usr/share/opensearch-dashboards
3
find . -name "node_modules" -type d -exec rm -rf {} + 2>/dev/null || true
4
find . -name "*.map" -delete
5
find . -name "*.ts" -delete
6
find . -name "*.spec.js" -delete
7
find . -name "*.test.js" -delete
8

9
# Compress assets
10
find . -name "*.js" -exec gzip -9 {} \; -exec mv {}.gz {} \;

Security Hardening#

1
# Remove potentially sensitive files
2
rm -rf opensearch-dashboards-2.18.0/usr/share/opensearch-dashboards/.git*
3
rm -rf opensearch-dashboards-2.18.0/usr/share/opensearch-dashboards/test/
4
rm -rf opensearch-dashboards-2.18.0/usr/share/opensearch-dashboards/docs/
5

6
# Set secure permissions
7
find opensearch-dashboards-2.18.0/usr/share/opensearch-dashboards -type f -exec chmod 644 {} \;
8
find opensearch-dashboards-2.18.0/usr/share/opensearch-dashboards -type d -exec chmod 755 {} \;
9
chmod 755 opensearch-dashboards-2.18.0/usr/share/opensearch-dashboards/bin/*

Deployment and Testing#

Installation Testing#

1
# Install the custom package
2
sudo dpkg -i opensearch-dashboards-2.18.0.deb
3

4
# Fix any dependency issues
5
sudo apt-get install -f
6

7
# Start the service
8
sudo systemctl start opensearch-dashboards
9

10
# Check service status
11
sudo systemctl status opensearch-dashboards
12

13
# Verify web interface (default port 5601)
14
curl -s http://localhost:5601/api/status | jq .

Validation Scripts#

1
#!/bin/bash
2
echo "=== OpenSearch Dashboards Installation Validation ==="
3

4
# Check service status
5
if systemctl is-active --quiet opensearch-dashboards; then
6
    echo "✓ Service is running"
7
else
8
    echo "✗ Service is not running"
9
    exit 1
10
fi
11

12
# Check port binding
13
if netstat -tlnp | grep -q :5601; then
14
    echo "✓ Port 5601 is bound"
15
else
16
    echo "✗ Port 5601 is not bound"
17
    exit 1
18
fi
19

20
# Check API response
21
if curl -s -f http://localhost:5601/api/status >/dev/null; then
22
    echo "✓ API is responding"
23
else
24
    echo "✗ API is not responding"
25
    exit 1
26
fi
27

28
# Check custom plugins
29
if curl -s http://localhost:5601/api/plugins | grep -q "mySecurityPlugin"; then
30
    echo "✓ Custom plugins loaded"
31
else
32
    echo "⚠ Custom plugins not detected"
33
fi
34

35
# Check log files
36
if [ -f /var/log/opensearch-dashboards/opensearch_dashboards.log ]; then
37
    echo "✓ Log file exists"
38
    if grep -q "Server running at" /var/log/opensearch-dashboards/opensearch_dashboards.log; then
39
        echo "✓ Successful startup logged"
40
    else
41
        echo "⚠ No startup confirmation in logs"
42
    fi
43
else
44
    echo "✗ Log file not found"
45
fi
46

47
echo "=== Validation Complete ==="

Automated Build Script#

1
#!/bin/bash
2
set -e
3

4
VERSION="2.18.0"
5
CUSTOM_VERSION="${VERSION}-custom$(date +%Y%m%d)"
6
BUILD_DIR="/tmp/opensearch-dashboards-build"
7
PLUGINS_DIR="/path/to/custom/plugins"
8

9
echo "Building OpenSearch Dashboards ${CUSTOM_VERSION}"
10

11
# Cleanup previous builds
12
rm -rf "$BUILD_DIR"
13
mkdir -p "$BUILD_DIR"
14
cd "$BUILD_DIR"
15

16
# Clone and checkout
17
git clone https://github.com/opensearch-project/OpenSearch-Dashboards.git
18
cd OpenSearch-Dashboards
19
git checkout "$VERSION"
20

21
# Setup Node.js
22
nvm use $(cat .nvmrc)
23

24
# Copy custom plugins
25
if [ -d "$PLUGINS_DIR" ]; then
26
    cp -r "$PLUGINS_DIR"/* plugins/
27
fi
28

29
# Install dependencies
30
yarn install
31
yarn osd bootstrap
32

33
# Build
34
yarn build --skip-os-packages --release
35

36
# Create package
37
cd ..
38
./create-debian-package.sh "$CUSTOM_VERSION"
39

40
echo "Build complete: opensearch-dashboards-${CUSTOM_VERSION}.deb"

Troubleshooting#

Common Build Issues#

Memory Issues:

1
# Increase Node.js heap size
2
export NODE_OPTIONS="--max-old-space-size=16384"
3

4
# Monitor memory usage during build
5
watch -n 1 'free -h && ps aux | grep node'

Permission Issues:

1
# Fix ownership
2
sudo chown -R $USER:$USER .
3

4
# Fix permissions
5
find . -type f -exec chmod 644 {} \;
6
find . -type d -exec chmod 755 {} \;

Plugin Conflicts:

1
# Clean plugin cache
2
rm -rf plugins/*/node_modules
3
yarn osd bootstrap --force
4

5
# Debug plugin loading
6
node --trace-warnings scripts/opensearch_dashboards --verbose

Package Installation Issues#

Service Won’t Start:

1
# Check service logs
2
journalctl -u opensearch-dashboards -f
3

4
# Verify configuration
5
opensearch-dashboards --config /etc/opensearch-dashboards/opensearch_dashboards.yml --help
6

7
# Check permissions
8
ls -la /var/lib/opensearch-dashboards
9
ls -la /var/log/opensearch-dashboards

Port Conflicts:

1
# Check what's using port 5601
2
sudo netstat -tlnp | grep 5601
3
sudo lsof -i :5601
4

5
# Change port in configuration
6
echo "server.port: 5602" >> /etc/opensearch-dashboards/opensearch_dashboards.yml

Best Practices#

Security Considerations#

Regular Updates: Keep base OpenSearch Dashboards updated
Plugin Vetting: Audit all custom plugins for security vulnerabilities
Access Control: Implement proper authentication and authorization
Network Security: Use HTTPS and proper firewall rules
Monitoring: Implement logging and monitoring for security events

Performance Optimization#

Resource Allocation: Allocate sufficient CPU and memory
Caching: Configure appropriate caching strategies
Index Management: Optimize OpenSearch indices
Load Balancing: Use load balancers for high availability
Monitoring: Monitor performance metrics and optimize accordingly

Maintenance Procedures#

Backup Strategy: Regular backups of configurations and customizations
Update Process: Establish procedures for updating custom packages
Testing: Comprehensive testing before production deployment
Documentation: Maintain detailed documentation of customizations
Rollback Plan: Prepare rollback procedures for failed deployments

Conclusion#

Custom packaging of OpenSearch Dashboards enables organizations to deploy tailored solutions that meet specific requirements while maintaining control over the build and deployment process. Whether you need custom plugins, specific configurations, or enterprise-grade packaging, the approaches outlined in this guide provide a solid foundation for creating and deploying custom OpenSearch Dashboards packages.

Key takeaways:

Plan your customizations carefully before building
Test thoroughly in development environments
Implement proper security measures throughout the process
Maintain detailed documentation of customizations
Establish reliable build and deployment pipelines

With proper implementation, custom OpenSearch Dashboards packages can provide significant value for organizations requiring specialized functionality or deployment requirements.