---
title: Install the Core+ C++ client
sidebar_label: Installation
---

The Deephaven Core+ C++ client allows you to create and connect to [Persistent Queries](../crash-course/develop-query/deephaven-ide.md#develop-a-persistent-query) using the Community Core engine in the Deephaven Enterprise system. This page provides an overview of how to install the C++ client.

## Obtain the C++ client sources

Contact your Deephaven representative to obtain the C++ client source bundle.

The source bundle includes a Dockerized build script that can be used in any [supported](#supported-operating-systems) Linux machine with Docker and Docker's `buildx` installed (`buildx` is the Docker CLI plugin for extended build capabilities with `BuildKit`). The script produces a binary package for supported platforms.

The source bundle is named `dhe-cpp-src-<version>.tgz`, where `<version>` is the Deephaven Enterprise version. Ensure that the version matches the version of the Deephaven Enterprise server you are connecting to.

## Supported operating systems

You can build the C++ client sources on Ubuntu 22.04 or 24.04. The build process produces a source bundle that can be used on any of the following operating systems:

- Ubuntu 22.04 or 24.04
- RHEL 9

## Prerequisites

The Dockerized build uses a script to build the client. It requires `docker` and `docker buildx`, which can be installed by following the steps in [Install Docker on Ubuntu](https://docs.docker.com/engine/install/ubuntu/). Additionally, if you need to run Docker as a non-root user, follow the instructions in [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/). If you don't follow those steps, be sure to run the Dockerized build script with `sudo`.

The build script installs all other prerequisites to use the client API.

## Unpack the client sources

Unpack the source bundle in a directory of your choice:

```bash
ROOT_DIR=/path/to/source/bundle
VERSION=<version>  # e.g. 1.20240517.499
cd $ROOT_DIR
tar -xvf dhe-cpp-src-$VERSION.tgz
```

## Installation steps

The Dockerized build creates a series of 4 Docker images, each depending on the previous one:

- `dhe-cpp-base`: The dependent C++ libraries, which include arrow, gRPC, and their respective dependencies.
- `dhe-cpp-dhc`: The Community Core C++ client API.
- `dhe-cpp-dhe`: The Enterprise Core+ C++ client API.
- `dhe-cpp-bundle`: An image that contains a `.tgz` bundle with the final result that can be extracted from a Docker container and installed for use on any [compatible machine](#supported-operating-systems).

The `docker-build.sh` script has a few parameters:

- `--base-distro`: The Linux distribution to use. Defaults to `ubuntu:24.04`. Other valid options include:
  - `ubuntu:22.04` for Ubuntu 22.04.
  - `registry.access.redhat.com/ubi9/ubi-minimal:9.6` for RHEL 9.
- `--prefix`: The installation directory. Defaults to `/opt/deephaven`.
- `--clear-images`: Automatically remove the images after the build. This behavior is disabled by default.

The Dockerized build script, `docker-build.sh`, can be found in the `$ROOT_DIR/coreplus/cpp-client/` directory.

`cd` into the `cpp-client` directory to run the build script:

```bash
cd coreplus/cpp-client
```

Here are three examples of running the Dockerized build script:

```bash
# Build for Ubuntu 24.04 with the root directory set to /opt/deephaven
PREFIX=/opt/deephaven
DISTRO=ubuntu:24.04

./docker-build.sh --base-distro $DISTRO --prefix $PREFIX
```

```bash
# Build for RHEL 9 with the root directory set to /opt/deephaven
PREFIX=/opt/deephaven
DISTRO=registry.access.redhat.com/ubi9/ubi-minimal:9.6

./docker-build.sh --base-distro $DISTRO --prefix $PREFIX
```

```bash
# Build for RHEL 9 with the root directory set to /usr/local/deephaven and clear Docker images after the build
PREFIX=/usr/local/deephaven
DISTRO=registry.access.redhat.com/ubi9/ubi-minimal:9.6

./docker-build.sh --base-distro $DISTRO --prefix $PREFIX --clear-images

# If you want the Deephaven test and example binaries included in the installation, add the flag:
# --install-tests-and-examples to your ./docker-build.sh command
```

> [!NOTE]
> The Docker images are not needed once the build is complete. The `--clear-images` option removes them after the build. If you plan to [Install the R client](./install-r-client.md), you will need the Docker images produced during the build.

The build script creates a `.tgz` bundle in the `build/` directory. For example, if you built against RHEL 9:

```
build/dhe-cpp-latest-ubi-9.6.tgz
```

## Unpack the build bundle

The `build/` tar bundle contains files relative to the `$PREFIX` you specified. For example, if you specified `PREFIX=/usr/local/deephaven`, the organization of the tar file is `/usr/local/deephaven/...`.

Because of this organization, it is easiest to unpack the tar bundle in the root of the filesystem. You may need root access to unpack the bundle at `/`.

The `$PREFIX` is hardcoded into the installation. You cannot change your choice of installation directory without redoing the build.

```bash
cd build
tar -xvf <tar_bundle> --directory=/
```

## Source the environment

At the root of the `--prefix` directory is an `env.sh` script that sets the environment variables needed to run the C++ client. This script should be sourced before running any C++ client program:

```bash
source $PREFIX/env.sh
```

Once this is done, you're ready to use the C++ client. The [usage guide](./coreplus-cpp-client.md) provides examples of how to use the client.

## Related documentation

- [Use the Core+ C++ client](./coreplus-cpp-client.md)
- [Core+ Clients](../sys-admin/architecture/communications.md#core-clients)
- [Install the R client](./install-r-client.md)