Installing Instana backend on Docker

To install Instana in a container-based environment, follow the steps:

Note: Virus scanners might interfere with the installation. If you meet any permission-related errors such as Operation not permitted, deactivate your virus scanner and try again.

Supported OS

The following Linux® distributions on x86/64bit processors are supported:

  • Ubuntu 18.04
  • Ubuntu 20.04
  • Debian 10.x
  • Debian 11.x
  • CentOS / Oracle Linux / Red Hat Enterprise Linux 7.9
  • CentOS / Oracle Linux / Red Hat Enterprise Linux 8.x with Docker CE
  • CentOS 7.9
  • Amazon Linux 2.x
  • SUSE Linux Enterprise Server 12 SP5
  • SUSE Linux Enterprise Server 15

Supported Docker versions

The following Docker versions are supported:

  • 20.10+
  • 19.03+
  • 18.03+
  • 1.13

Minimum requirements

The machine where you want to install the Instana backend must have at minimum 12 CPUs and 48 GiB available memory. This is the lowest limit and only recommended for small installations. Production environments must have a minimum size of 16 CPUs and 64 GiB memory.

Network security notes

Note: Don't expose Instana without taking proper precautions.

Make sure to set the firewall properly for the installation. The only ports that you need to expose for a self-hosted installation are as follows:

  • Port 80: Used to detect broken links and promote them to SSL.

  • Port 443: Primary application port for UI and API.

  • Port 86 and 446: EUM ports. For more information, see Exposing the monitoring endpoint to end users.

  • Port 1444: Acceptor port for agents to connect to.


  • To authenticate against the Docker repository, make sure that the host machine that you want to install the Instana backend can connect to
  • All installation and migration commands must be run as root user.
  • You must ensure that Docker is installed, and at least 25 GB of free spaces are available for Docker images. For more information about how to install Docker, see the Docker CE or Docker EE documentation.
  • Set up mount points and external volumes:
    • Data stores

      Defaults to /mnt/data.

    • Cassandra

      It can't use the same volume for production installs. Defaults to /mnt/metrics.

    • ClickHouse

      It can't use the same volume for productions installs. Defaults to /mnt/traces.

    • Logs

      Defaults to /var/log/instana. If required, you can create a different directory.

Fresh installation: Single host

1. Installing the Instana package

To install the Instana package on your machine, use the following installation steps:


As root, run the following command to add the repo, replacing <download_key> with your download key:

export DOWNLOAD_KEY=<download_key>

echo 'deb [signed-by=/usr/share/keyrings/instana-archive-keyring.gpg] generic main' > /etc/apt/sources.list.d/instana-product.list

cat << EOF > /etc/apt/auth.conf
  login _
  password $DOWNLOAD_KEY

wget -O- --user=_ --password="$DOWNLOAD_KEY" | gpg --dearmor > /usr/share/keyrings/instana-archive-keyring.gpg

Installing instana-console:

apt update -y
apt install -y instana-console

To avoid getting major updates during automated upgrades, run the following commands:

cat > /etc/apt/preferences.d/instana-console <<EOF
Package: instana-console
Pin: version <version to pin>
Pin-Priority: 1000

Red Hat/CentOS

As root, run the following command to add the repo, replacing <download_key> with your download key:

export DOWNLOAD_KEY=<download_key>

cat << EOF > /etc/yum.repos.d/Instana-Product.repo

Installing instana-console:

yum clean expire-cache -y
yum update -y
yum install -y instana-console

To avoid getting major updates during automated updates, run the following command:

yum versionlock add instana-console

2. Installing Instana

Note: The Instana command requires the root user for running because it's needed to adjust some values in the kernel and ensure that access rights are set correctly on the different mount points.

Instana containers are implemented to be rootless. So even though the root user is required for the installer, the application itself runs in the provided instana-user.

  1. To install Instana backend on your machine, run the following command:

    instana init

    Note: A settings.hcl file is generated in the same directory as where you run the instana init command.

  2. Select single (single host installation).

  3. Enter the following information:

    • Your tenant name and unit name.

    • Your agent key and sales key.

    • DNS name.

    • Path to your certificate files. If no path is defined, Instana generates an HTTPS TLS certificate for the UI (tls.crt) and key (tls.key) in the cert folder. If you want to generate your own self-signed certificates, enter your hostname in the following command:

      openssl req -x509 -newkey rsa:2048 -keyout tls.key -out tls.crt -days 365 -nodes -subj "/CN=<hostname>"
  4. You can now sign in to Instana by using the credentials that are displayed.

  5. After Instana is deployed, activate your license.

Air-gapped installation on a target host

Prerequisite: Make sure that Docker is installed on the target host that has no internet connectivity.

  1. On a host with internet connectivity, install instana-console as described in the 1. Install the Instana package.

  2. Download the required binary files.

    Two files are required for an air-gapped installation:

    • The instana-console binary

      For Ubuntu/Debian, run the command apt-get download instana-console.

      For Red Hat/CentOS, run the command yum install --downloadonly instana-console.

      Or you can mirror the Instana repository.

    • The archive with Instana Docker containers

      Run the command instana images export to create an export-{version}.tar within the execution directory.

  3. Copy the files to the target host that has no internet connectivity.

  4. Install instana-console from the package that you previously downloaded and transferred.

  5. Ensure that Docker is installed.

  6. To import the containers, run the command instana images import -f <path/to/export-{version}.tar>.

  7. Start the installation as described in the installation section.

To check a list of mandatory containers, run the command instana images version. This command lists all the Docker containers and their corresponding version.

Image commands

The installer comes with a set of commands for managing the Instana docker images.

Exporting images to tar

All required images of an instana-console version can be exported to a tar file by running the following command:

instana images export -k ${agent_key}

Importing images from tar

Import an export image tar into the local Docker cache by running the following command:

instana images import -f /path/to/export.tar

Prepulling images

Prefetch all necessary images into the local docker cache by running the following command:

instana images pull -k ${agent_key}

Pushing images to custom registry

Allow to push containers from the local Docker cache to a custom hosted registry by running the following command:

instana images push -u ${registry_user} -p ${registry_pass} -r ${registry_url}

Afterward, the registry can be configured in the settings.hcl file and the installer uses it for installations and updates.

Listing images and versions

Return a list of the currently required images for this version by running the following command:

instana images version

Pruning local image cache

Remove all containers from the local cache that are no longer required for the current version by running the following command:

instana images prune

Installation: Dual-host

For the dual-host installation, ClickHouse is moved to a separate host with a distinct ZooKeeper installation.

1. Optional: Copying data from existing machine

If you want to migrate from a current installation, you need to take the time to move existing data to the new machine.

To do so, it is best to copy the existing data and log directories from your original installation. You can check the original settings.hcl file to find where these directories are mounted.

After Instana is shut down, you can copy from these directories:

  • All directories that are named clickhouse, such as /mnt/traces/clickhouse and /mnt/log/instana/clickhouse.
  • All directories that are named zookeeper, such as /mnt/data/zookeeper and /mnt/log/instana/zookeeper.

Move the directories to the same directories on the new machine, and configure your new settings.hcl file.

Note: You are not required to delete the old directories, but you are suggested doing so after the new setup is up and running.

2. Installing the instana-console

Install instana-console from the repositories as previously described.

3. Exposing Docker Daemon port

The installer of the compute instance tries to connect to the port :2376 of this host to check prerequisites. For more information, see Enabling and accessing docker engine api on a remote docker host

If it's not set properly, you can see the following error message:

remote docker daemon is not reachable on host <clickhouse-host>:2376 : Cannot connect to the Docker daemon at tcp://<clickhouse-host>:2376. Is the docker daemon running?

4. Installing ClickHouse and Zookeeper on the first host


Run the command instana init, and select dual-clickhouse as type.


In the settings.hcl file, adjust type:

  type = "dual-clickhouse"

Install Instana by running the following command:

  instana init -y

Secure ClickHouse server by using IPtables

To secure your ClickHouse server in a multihost environment, see the example as follows. This example ensures that only IO that originates from the Instana backend host has access to the ClickHouse host.

You need to ssh from the Instana backend server to the ClickHouse host afterward. Or you need to provide an extra IP from the box that you want to ssh from.

iptables -A INPUT -s $(instana backend host IP) -j ACCEPT
iptables -A OUTPUT -d $(instana backend host IP) -j ACCEPT
iptables -A INPUT -d $(ssh host IP) -j ACCEPT #optional
iptables -A OUTPUT -d $(ssh host IP) -j ACCEPT #optional
iptables -A INPUT -j REJECT
iptables -A OUTPUT -j REJECT

5. Installing the rest of Instana on the second host


Run the command instana init, select dual-instana as type, and follow the interactive dialog.


Adjust type, and add ClickHouse IP additionally to the settings.hcl file.

  type                    = "dual-instana"
  clickhouse_bind_address = <IP of ClickHouse box>

Install Instana by running the following command:

  instana init -y

Self-hosted postinstallation - important

You are recommended to monitor the health of your self-hosted Instana backend with the use of an Instana agent that is running in Infrastructure-only mode.

It allows a number of health checks and metrics to be collected for your Instana backend.

Note: Infrastructure mode is essential. APM mode can put unnecessary load on your self-hosted services. For more information, see Host agent modes.

For configuration of one-liner installation, see Additional parameters.

Upgrading with a private docker registry

To use an internal Docker registry, you can specify the Docker registry for your migration process by changing the containerize command:

  • Single host:

    instana containerize --type single -y --registryUrl {url} --registryUser {user} --registryPass {pass}
  • Dual host:

    instana containerize --type dual-clickhouse -y --registryUrl {url} --registryUser {user} --registryPass {pass}
    instana containerize --type dual-instana -y --registryUrl {url} --registryUser {user} --registryPass {pass}

Optional Features

BeeInstana Metric Pipeline (beta)

This feature includes a new data pipeline with additional Instana backend components and a datastore (BeeInstana) to the store of the infrastructure metrics. Based on this data, further features can be activated in the product.

  • Custom Infrastructure Dashboards
  • Infrastructure Explore

Note: Ensure that enough free space is available in the storage location for the metric data, and the entire system is not currently being operated at its capacity limits. This is because the additional components might endanger the stability.

An estimated disk size of 1 million metrics can be derived from this table:

Period in seconds Retention Disk size in GBs
10 1 72.72
60 30 418.88
300 90 289.35
3600 395 191.49

To enable the pipeline and Custom Infrastructure Dashboards, enable the following feature flag in the settings.hcl file, and apply this change by using an instana update command to the system.

feature "beeinstana" {

Furthermore, you can activate Infrastructure Explore by using the following feature flag:

feature "infraEntityExplore" {