Creating Custom Debian Packages for OpenSearch Dashboards#

Oh, you’re deploying OpenSearch Dashboards in enterprise environments? How delightfully original. Of course you need customizations—because heaven forbid you use anything “as is.” Well, since you insist on making your life complicated with specific plugins, custom themes, and specialized configurations, I suppose creating a custom Debian package is the least painful way to standardize your special snowflake modifications across your infrastructure.

This guide begrudgingly walks you through building a custom Debian package for OpenSearch Dashboards 2.18.0 with your inevitably over-engineered plugins and configurations.

Why Package Custom OpenSearch Dashboards?#

Before diving into the technical steps, let me enlighten you on why packaging is supposedly “better” than manual installation—as if you hadn’t already convinced yourself of this brilliant idea:

Standardized deployments across multiple environments (because consistency is apparently too much to ask for otherwise)
Simplified upgrades through package management (shocking that a package manager would manage packages)
Dependency management handled by the package manager (revolutionary concept, truly)
Configuration consistency across your infrastructure (imagine that!)
Easier integration with CI/CD pipelines and configuration management tools (because making simple things complicated is the enterprise way)

Prerequisites#

Before starting this adventure in overcomplication, ensure your build system has:

A Debian-based Linux distribution (Ubuntu 20.04+ recommended—because apparently we’re picky about our suffering)
Sufficient RAM (at least 8GB) and disk space (20GB free)—yes, that’s right, this simple dashboard needs more resources than some entire operating systems
Internet connection to download dependencies (shocking requirement, I know)
Root or sudo access (because we’re about to break things systemically)

Step 1: Setting Up the Build Environment#

First, install the necessary dependencies for building OpenSearch Dashboards:

1
# Install system dependencies
2
sudo apt-get update
3
sudo apt-get install -y nodejs npm ruby ruby-dev build-essential rpm git curl
4

5
# Install Node Version Manager (nvm)
6
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
7
source ~/.bashrc
8

9
# Install Yarn
10
npm install -g yarn

Step 2: Clone and Prepare the Source Code#

Clone the OpenSearch Dashboards repository and check out the specific version you want to package:

1
git clone https://github.com/opensearch-project/OpenSearch-Dashboards.git
2
cd OpenSearch-Dashboards
3
git checkout 2.18.0
4

5
# Set up the correct Node.js version
6
nvm install $(cat .nvmrc)
7
nvm use $(cat .nvmrc)

Step 3: Add Custom Plugins#

Now add your custom plugins to the build:

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
# Alternatively, you can clone plugin repositories directly
8
# git clone https://github.com/example/your-plugin.git plugins/your-plugin

Step 4: Build OpenSearch Dashboards#

Build the package with your custom plugins included:

1
# Bootstrap the project
2
yarn osd bootstrap
3

4
# Build OpenSearch Dashboards
5
yarn build --skip-os-packages

This process might take some time depending on your system resources—or more accurately, it will take forever because JavaScript build processes are apparently designed by people who have never heard of efficiency.

Step 5: Create the Debian Package Structure#

Create the directory structure for your Debian package:

1
# Create base package directory
2
mkdir -p opensearch-dashboards-2.18.0/DEBIAN
3

4
# Create installation directories
5
mkdir -p opensearch-dashboards-2.18.0/usr/share/opensearch-dashboards
6
mkdir -p opensearch-dashboards-2.18.0/etc/opensearch-dashboards
7
mkdir -p opensearch-dashboards-2.18.0/var/log/opensearch-dashboards
8
mkdir -p opensearch-dashboards-2.18.0/var/lib/opensearch-dashboards
9
mkdir -p opensearch-dashboards-2.18.0/lib/systemd/system

Step 6: Copy Build Artifacts#

Copy the built files to the appropriate locations in the package structure:

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

Step 7: Create Debian Control Files#

Control File#

Create the main package control file:

1
cat > opensearch-dashboards-2.18.0/DEBIAN/control << EOL
2
Package: opensearch-dashboards
3
Version: 2.18.0
4
Section: web
5
Priority: optional
6
Architecture: amd64
7
Depends: libnss3
8
Maintainer: Your Name <your.email@domain.com>
9
Description: OpenSearch Dashboards with custom plugins
10
 Custom build of OpenSearch Dashboards including specific plugins
11
EOL

Pre-installation Script#

Create the pre-installation script to set up the user and group:

1
cat > opensearch-dashboards-2.18.0/DEBIAN/preinst << EOL
2
#!/bin/bash
3
if ! getent group opensearch-dashboards >/dev/null; then
4
    groupadd -r opensearch-dashboards
5
fi
6
if ! getent passwd opensearch-dashboards >/dev/null; then
7
    useradd -r -g opensearch-dashboards -d /usr/share/opensearch-dashboards -s /sbin/nologin opensearch-dashboards
8
fi
9
EOL
10

11
chmod 755 opensearch-dashboards-2.18.0/DEBIAN/preinst

Post-installation Script#

Create the post-installation script to set permissions:

1
cat > opensearch-dashboards-2.18.0/DEBIAN/postinst << EOL
2
#!/bin/bash
3
chown -R opensearch-dashboards:opensearch-dashboards /usr/share/opensearch-dashboards
4
chown -R opensearch-dashboards:opensearch-dashboards /var/log/opensearch-dashboards
5
chown -R opensearch-dashboards:opensearch-dashboards /var/lib/opensearch-dashboards
6
chmod 750 /usr/share/opensearch-dashboards
7
chmod 750 /var/log/opensearch-dashboards
8
chmod 750 /var/lib/opensearch-dashboards
9

10
# Enable and start the service
11
systemctl daemon-reload
12
systemctl enable opensearch-dashboards.service
13
EOL
14

15
chmod 755 opensearch-dashboards-2.18.0/DEBIAN/postinst

Step 8: Create Configuration Files#

Configuration File#

Copy and modify the default configuration file:

1
cp config/opensearch_dashboards.yml opensearch-dashboards-2.18.0/etc/opensearch-dashboards/
2

3
# Add custom paths
4
cat >> opensearch-dashboards-2.18.0/etc/opensearch-dashboards/opensearch_dashboards.yml << EOL
5

6
# Custom paths
7
path.data: /var/lib/opensearch-dashboards
8
path.logs: /var/log/opensearch-dashboards
9

10
# Custom settings
11
server.host: "0.0.0.0"
12
server.port: 5601
13
opensearch.hosts: ["https://localhost:9200"]
14
opensearch.ssl.verificationMode: none
15
EOL

Systemd Service File#

Create a systemd service file for automatic startup:

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

8
[Service]
9
Type=simple
10
User=opensearch-dashboards
11
Group=opensearch-dashboards
12
Environment=NODE_ENV=production
13
Environment=CONFIG_PATH=/etc/opensearch-dashboards/opensearch_dashboards.yml
14
ExecStart=/usr/share/opensearch-dashboards/bin/opensearch-dashboards
15
Restart=always
16
WorkingDirectory=/usr/share/opensearch-dashboards
17

18
[Install]
19
WantedBy=multi-user.target
20
EOL

Step 9: Build the Debian Package#

Now build the Debian package:

1
dpkg-deb --build opensearch-dashboards-2.18.0

This will create a file named opensearch-dashboards-2.18.0.deb in your current directory.

Step 10: Installing the Package#

To install your custom package on a Debian/Ubuntu system:

1
sudo dpkg -i opensearch-dashboards-2.18.0.deb
2

3
# If there are dependency issues
4
sudo apt-get install -f