Installation on Docker

Quick Start

For a quick installation of pre-integrated Axibase Collector and ATSD instances in a single Docker container, refer to the ATSD Sandbox guide.

Host Requirements

Image Information

Importing an Image in Restricted Environments

If the target Docker host has no direct connectivity to Docker Hub, execute the following steps to prepare and load the Collector image:

  • Log in to a Docker host which is connected to Docker Hub.
  • Pull the Collector image from Docker Hub and export into an archive file:
docker pull axibase/collector:latest
docker save -o docker-axibase-collector.tar axibase/collector:latest
gzip docker-axibase-collector.tar
  • Copy the docker-axibase-collector.tar.gz archive to the target Docker host.
  • Import the image from the archive:
docker load < docker-axibase-collector.tar.gz

Alternatively, download a pre-built image file from the axibase.com.

Start Container

Using Collector to monitor Docker? Launch container in privileged mode as described in the Docker Job Documentation.

docker run \
 --detach \
 --publish-all \
 --restart=always \
 --name=axibase-collector \
 axibase/collector:latest

To automatically configure a connection to the Axibase Time Series Database, add the -atsd-url parameter containing the ATSD hostname and https port (default 8443), as well as collector account credentials:

docker run \
 --detach \
 --publish-all \
 --restart=always \
 --name=axibase-collector \
 axibase/collector:latest \
  -atsd-url=https://collector-user:collector-password@atsd_host:atsd_https_port

If the user name or password contains a $, &, #, or ! character, escape the character with backslash \.

The password must contain at least six (6) characters and is subject to the following requirements.

For example, for user adm-dev with the password my$pwd sending data to ATSD at https://10.102.0.6:8443, specify:

docker run \
 --detach \
 --publish-all \
 --restart=always \
 --name=axibase-collector \
 axibase/collector:latest \
  -atsd-url=https://adm-dev:my\$pwd@10.102.0.6:8443

Start Container in Privileged Mode

The launch command is different if the Collector container is used to monitor statistics from the local Docker Engine.

Launch Parameters

Name Required Description
--detach Yes Run container in background and print container id.
--publish-all No Publish exposed https port (9443) to a random port.
--restart No Auto-restart policy. Not supported in all Docker Engine versions.
--name No Assign a host-unique name to the container.

To bind the Collector to a particular port instead of a random one, replace --publish-all with --publish 10443:9443, where the first number indicates an available port on the Docker host.

Environment Variables

Name Required Description
ATSD_SERVICE_HOST No Host where Axibase Time Series Database is installed.
ATSD_SERVICE_PORT_HTTPS No Https port.
ATSD_SERVICE_PORT_TCP No Tcp port for network commands.
ATSD_URL No URL (protocol://host:port) for the Axibase Time Series Database connection.
COLLECTOR_USER_NAME No User name for the data collector account.
COLLECTOR_USER_PASSWORD No Password for the data Collector account.
DOCKER_HOSTNAME No Hostname of the Docker host where Axibase Collector container is running.
JAVA_OPTS No Java VM options.
By default the Collector starts with option -Xmx256m

For example, for user adm-dev with the password my$pwd sending data to ATSD at https://10.102.0.6:8443, specify:

docker run \
 --detach \
 --publish-all \
 --restart=always \
 --name=axibase-collector \
 --env COLLECTOR_USER_NAME=adm-dev \
 --env COLLECTOR_USER_PASSWORD=my\$pwd \
 --env ATSD_URL=https://10.102.0.6:8443 \
 axibase/collector:latest

For example, to set the maximum Java heap size, specify:

docker run \
 --detach \
 --publish-all \
 --restart=always \
 --name=axibase-collector \
 --env JAVA_OPTS=-Xmx512m \
 axibase/collector:latest

Check Installation

Initializing the application may take up to five minutes.

docker exec -it axibase-collector tail -f /opt/axibase-collector/logs/axibase-collector.log

Wait until the following message appears:

FrameworkServlet 'dispatcher': initialization completed.

This message indicates that the initial configuration is complete.

Validation

docker ps | grep axibase-collector
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                     NAMES
ee15099d9f88        axibase/collector   "/bin/bash /opt/axiba"   33 seconds ago      Up 32 seconds       0.0.0.0:32769->9443/tcp   axibase-collector

Take note of the public https port assigned to axibase-collector container, for example 32769 in the example above.

Login

Open https://docker_hostname:32769 in your browser and create an administrator account.

docker_hostname is the hostname or IP address of the Docker host and 32769 is the external port number assigned to the Collector container in the previous step.

Setup ATSD Connection

Configure the ATSD Server connection to send data into an Axibase Time Series Database instance.

Troubleshooting

Review the following log files for any errors:

docker exec -it axibase-collector tail -n 100 /opt/axibase-collector/logs/axibase-collector.log
docker exec -it axibase-collector tail -n 100 /opt/axibase-collector/logs/err-collector.log