Install Guide

Share this on Social Media: Twitter  Facebook   LinkIn
How to install the ClickHouse Altinity Stable Release

Installing the ClickHouse Altinity Stable Release takes just a few minutes.

General Installation Instructions

When installing or upgrading from a previous version of ClickHouse Altinity Stable Release, review the Release Notes for the version to install and upgrade to before starting. This will inform you of additional steps or requirements of moving from one version to the next.

Part of the installation procedures has you specify the version to install. The Release Notes lists the version numbers available for installation.

There are three main methods for installing ClickHouse Altinity Stable Releases:

The package sources come from two sources:

  • Community Builds: These are made by ClickHouse community members, and are available at repo.clickhouse.tech.
  • Altinity Builds: These are built from a secure, internal build pipeline and available at packagecloud.io/Altinity/altinity-stable. Altinity Builds are distinguishable from community builds when displaying version information:
select version()

┌─version()─────────────────┐
 21.3.15.2.altinity+stable 
└───────────────────────────┘

Installation Instructions: DEB packages

Altinity DEB Builds

DEB Releases 21.1 and After

To install ClickHouse Altinity Stable Release via DEB based packages:

  1. Update the apt-get repository with the following command:

    curl -s https://packagecloud.io/install/repositories/Altinity/altinity-stable/script.deb.sh | sudo bash
    
  2. To install a specific version, remove previous packages before installing the version to be installed:

    sudo apt-get remove clickhouse-client clickhouse-server clickhouse-server-common clickhouse-common-static
    version=21.3.15.2.altinity+stable
    sudo apt-get install clickhouse-client=$version clickhouse-server=$version clickhouse-common-static=$version
    
    1. To install the most current version of the ClickHouse Altinity Stable release without specifying a specific version, leave out the version= command.
    sudo apt-get install clickhouse-client clickhouse-server clickhouse-server-common
    
  3. Restart server.

    Installed packages are not applied to the already running server. It makes it convenient to install packages first and restart later when convenient.

    sudo service clickhouse-server restart
    

Community DEB Builds

  1. Configure the apt-get package repository with the following commands:

    sudo apt-get install dirmngr
    sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv E0C56BD4
    
    echo "deb http://repo.clickhouse.tech/deb/stable/ main/" | sudo tee \
        /etc/apt/sources.list.d/clickhouse.list
    sudo apt-get update
    
  2. Install packages.

    We recommend you install the specific ClickHouse versions by specifying it in the install commands. The version numbers are listed in the Release Notes.

    version=20.8.12.2
    sudo apt-get install -y clickhouse-server=$version \
    clickhouse-client=$version \
    clickhouse-common-static=$version
    
  3. Restart server. Installed packages are not applied to the already running server. It makes it convenient to install packages first and restart later when convenient.

    sudo service clickhouse-server restart
    clickhouse-client
    

Installation Instructions: RPM packages

Altinity RPM Builds

RPM Releases 21.1 and After

To install ClickHouse Altinity Stable Release versions 21.1 and greater via RPM packages:

  1. Update the yum package repository configuration with the following command:

    curl -s https://packagecloud.io/install/repositories/Altinity/altinity-stable/script.rpm.sh | sudo bash
    
  2. To install a specific version, remove previous packages before installing the version to be installed:

    sudo yum erase clickhouse-client clickhouse-server clickhouse-server-common clickhouse-common-static
    version=21.3.15.2.altinity+stable
    sudo yum install clickhouse-client-${version} clickhouse-server-${version} clickhouse-server-common-${version}
    
    1. To install the most current version of the ClickHouse Altinity Stable release without specifying a specific version, leave out the version= command.
    sudo yum install clickhouse-client clickhouse-server clickhouse-server-common
    
  3. Restart the ClickHouse server.

    sudo systemctl restart clickhouse-server
    

RPM Releases Prior to 21.1

  1. Configure the repository:

    curl -s https://packagecloud.io/install/repositories/Altinity/clickhouse-altinity-stable/script.rpm.sh | sudo bash
    
  2. Specify the version and install the packages. Note that for versions prior to 21.1 the option --setopt=obsoletes=0 must be set. For example: to install version 20.8.12.2-1.el7, use the following:

    version=20.8.12.2-1.el7 
    yum install --setopt=obsoletes=0 clickhouse-client-${version} clickhouse-server-${version}
    
  3. Restart the ClickHouse server.

    sudo systemctl restart clickhouse-server
    

RPM Downgrading to a Previous Release

To downgrade to a previous release, the current version must be installed, and the previous version installed with the --setup=obsoletes=0 option. Review the Release Notes before downgrading for any considerations or issues that may occur when downgrading between versions of ClickHouse.

To downgrade to a previous release:

  1. Remove the currently installed released packages:

    yum erase clickhouse-client clickhouse-server clickhouse-server-common clickhouse-common-static
    
  2. Set the repository and version:

    1. If using ClickHouse Altinity Stable releases 21.1 and later, follow the instructions from RPM Releases 21.1 and After
    2. If using ClickHouse Altinity Stable releases prior to 21.1, follow the instructions from RPM Releases Prior to 21.1

Community RPM Builds

To install ClickHouse Community Stable release:

  1. Configure the yum repository:

    sudo yum install yum-utils
    sudo rpm --import https://repo.clickhouse.tech/CLICKHOUSE-KEY.GPG
    sudo yum-config-manager --add-repo https://repo.clickhouse.tech/rpm/stable/x86_64
    
  2. Install the packages:

    sudo yum install clickhouse-server clickhouse-client
    

Installation Instructions: Docker

These included instructions detail how to install a single ClickHouse Altinity Stable Release container through Docker. For details on setting up a cluster of Docker containers, see ClickHouse on Kubernetes.

Docker Images are available for Altinity Builds and Community Builds. The instructions below focus on using the Altinity Builds for ClickHouse Altinity Stable Releases.

The Docker repositories are located at:

To install a ClickHouse Altinity Stable Release through Docker:

  1. Create the directory for the docker-compose.yml file and the database storage and ClickHouse server storage.

    mkdir clickhouse
    cd clickhouse
    mkdir clickhouse_database
    
  2. Create the file docker-compose.yml and populate it with the following, updating the clickhouse-server to the current altinity/clickhouse-server version:

    version: '3'
    
    services:
        clickhouse_server:
            image: altinity/clickhouse-server:21.3.15.2.altinity_stable
            ports:
            - "8123:8123"
            volumes:
            - ./clickhouse_database:/var/lib/clickhouse
            networks:
                - clickhouse_network
    
    networks:
    clickhouse_network:
        driver: bridge
        ipam:
            config:
                - subnet: 10.222.1.0/24
    
  3. Launch the ClickHouse Server with docker-compose or docker compose depending on your version of Docker:

    docker compose up -d
    
  4. Verify the installation by logging into the database from the Docker image directly, and make any other necessary updates with:

    docker compose exec clickhouse_server bash
    root@67c732d8dc6a:/# clickhouse-client
    ClickHouse client version 21.3.15.2.altinity+stable (altinity build).
    Connecting to localhost:9000 as user default.
    Connected to ClickHouse server version 21.1.10 revision 54443.
    
    67c732d8dc6a :)
    

Last modified 2021.08.17: Updated release instructions.