This is the multi-page printable view of this section.
Click here to print.
Return to the regular view of this page.
Altinity Stable Builds Install Guide
How to install the Altinity Stable Builds for ClickHouse
Installing ClickHouse from the Altinity Stable Builds, available from https://builds.altinity.cloud, takes just a few minutes.
Notice
Organizations that have used the legacy Altinity Stable Release repository at packagecloud.io can upgrade to the Altinity Stable Build without any conflicts. For more information on using the legacy repository, see the
Legacy ClickHouse Altinity Stable Releases Install Guide.
General Installation Instructions
When installing or upgrading from a previous version of ClickHouse from the Altinity Stable Builds, review the Release Notes for the ClickHouse 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 recommends you specify the version to install. The Release Notes lists the version numbers available for installation.
There are three main methods for installing Altinity Stable Builds:
- Deb Packages
- RPM Packages
- Docker images
The package sources come from two sources:
-
Altinity Stable Builds: These are built from a secure, internal build pipeline and available from https://builds.altinity.cloud. Altinity Stable Builds are distinguishable from community builds when displaying version information:
select version()
┌─version()─────────────────┐
│ 21.8.11.1.altinitystable │
└───────────────────────────┘
-
Community Builds: These are made by ClickHouse community members, and are available at repo.clickhouse.tech.
1 - Altinity Stable Builds Deb Install Guide
How to install the Altinity Stable Builds for ClickHouse on Debian based systems.
Installation Instructions: Deb packages
ClickHouse can be installed from the Altinity Stable builds, located at https://builds.altinity.cloud, or from the ClickHouse community repository.
IMPORTANT NOTE
We highly encourage organizations use a specific version to maximize compatibility, rather than relying on the most recent version. Instructions for how to specify the specific version of ClickHouse are included below.
Deb Prerequisites
The following prerequisites must be installed before installing an Altinity Stable build of ClickHouse:
- curl
- gnupg2
- apt-transport-https
- ca-certificates
These can be installed prior to installing ClickHouse with the following command:
sudo apt-get install curl gnupg2 apt-transport-https ca-certificates
Deb Packages for Altinity Stable Build
To install ClickHouse Altinity Stable build via Deb based packages from the Altinity Stable build repository:
-
Update the apt-get
local repository:
-
Install the Altinity package signing keys:
sudo sh -c 'mkdir -p /usr/share/keyrings && curl -s https://builds.altinity.cloud/apt-repo/pubkey.gpg | gpg --dearmor > /usr/share/keyrings/altinity-archive-keyring.gpg'
-
Update the apt-get
repository to include the Altinity Stable build repository with the following commands:
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/altinity-archive-keyring.gpg] https://builds.altinity.cloud/apt-repo stable main" > /etc/apt/sources.list.d/altinity-dev.list'
-
Install either a specific version of ClickHouse, or the most current version.
- To install a specific version, include the version in the
apt-get install
command. The example below specifies the version 21.8.10.1.altinitystable
:
version=21.8.10.1.altinitystable
sudo apt-get install clickhouse-common-static=$version clickhouse-client=$version clickhouse-server=$version
- To install the most current version of the ClickHouse Altinity Stable build without specifying a specific version, leave out the
version=
command.
sudo apt-get install clickhouse-client clickhouse-server
-
When prompted, provide the password for the default clickhouse
user.
-
Restart server.
Installed packages are not applied to an already running server. It makes it convenient to install the packages first and restart later when convenient.
sudo systemctl restart clickhouse-server
For users upgrading to Altinity Stable builds from the community ClickHouse builds, we recommend removing the community builds from the local repository. See the instructions for your distribution of Linux for instructions on modifying your local package repository.
For instructions on how to install ClickHouse community, see the ClickHouse Documentation site.
2 - Altinity Stable Builds RPM Install Guide
How to install the Altinity Stable Builds for ClickHouse on RPM based systems.
Installation Instructions: RPM packages
ClickHouse can be installed from the Altinity Stable builds, located at https://builds.altinity.cloud, or from the ClickHouse commuinity repository.
Depending on your Linux distribution, either dnf
or yum
will be used. See your particular distribution of Linux for specifics.
The instructions below uses the command $(type -p dnf || type -p yum)
to provide the correct command based on the distribution to be used.
IMPORTANT NOTE
We highly encourage organizations use a specific version to maximize compatibility, rather than relying on the most recent version. Instructions for how to specify the specific version of ClickHouse are included below.
RPM Prerequisites
The following prerequisites must be installed before installing an Altinity Stable build:
These can be installed prior to installing ClickHouse with the following:
sudo $(type -p dnf || type -p yum) install curl gnupg2
RPM Packages for Altinity Stable Build
To install ClickHouse from an Altinity Stable build via RPM based packages from the Altinity Stable build repository:
-
Update the local RPM repository to include the Altinity Stable build repository with the following command:
sudo curl https://builds.altinity.cloud/yum-repo/altinity.repo -o /etc/yum.repos.d/altinity.repo
-
Install ClickHouse server and client with either yum
or dnf
. It is recommended to specify a version to maximize compatibly with other applications and clients.
- To specify the version of ClickHouse to install, create a variable for the version and pass it to the installation instructions. The example below specifies the version
21.8.10.1.altinitystable
:
version=21.8.10.1.altinitystable
sudo $(type -p dnf || type -p yum) install clickhouse-common-static-$version clickhouse-server-$version clickhouse-client-$version
- To install the most recent version of ClickHouse, leave off the
version-
command and variable:
sudo $(type -p dnf || type -p yum) install clickhouse-common-static clickhouse-server clickhouse-client
For users upgrading to Altinity Stable builds from the community ClickHouse builds, we recommend removing the community builds from the local repository. See the instructions for your distribution of Linux for instructions on modifying your local package repository.
RPM Downgrading Altinity ClickHouse Stable 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.
For more information, see the Altinity Knowledge Base article Altinity packaging compatibility greater than 21.x and earlier.
For instructions on how to install ClickHouse community, see the ClickHouse Documentation site.
3 - Altinity Stable Builds Docker Install Guide
How to install the Altinity Stable Builds for ClickHouse with Docker.
Installation Instructions: Docker
These included instructions detail how to install a single Altinity Stable build of ClickHouse container through Docker. For details on setting up a cluster of Docker containers, see ClickHouse on Kubernetes.
Docker Images are available for Altinity Stable builds and Community builds. The instructions below focus on using the Altinity Stable builds for ClickHouse.
IMPORTANT NOTE
The Altinity Stable builds for ClickHouse do not use the
latest
tag. We highly encourage organizations to install a specific version of Altinity Stable builds to maximize compatibility. For information on the latest Altinity Stable Docker images, see the
Altinity Stable for ClickHouse Docker page.
The Docker repositories are located at:
To install a ClickHouse Altinity Stable build through Docker:
-
Create the directory for the docker-compose.yml file and the database storage and ClickHouse server storage.
mkdir clickhouse
cd clickhouse
mkdir clickhouse_database
-
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.8.10.1.altinitystable
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
-
Launch the ClickHouse Server with docker-compose
or docker compose
depending on your version of Docker:
-
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 clickhouse-client
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 :)
4 - Altinity Stable Builds macOS Install Guide
How to install the Altinity Stable Builds for ClickHouse with macOS.
Altinity Stable for ClickHouse is available to macOS users through the Homebrew package manager. Users and developers who use macOS as their preferred environment can quickly install a production ready version of ClickHouse within minutes.
The following instructions are targeted for users of Altinity Stable for ClickHouse. For more information on running community or other versions of ClickHouse on macOS, see either the Homebrew Tap for ClickHouse project or the blog post Altinity Introduces macOS Homebrew Tap for ClickHouse.
Note
As of this time, the only versions of macOS with prepared binary bottles are the following:
- macOS Monterey (version 12) on Intel
- macOS Monterey (version 12) on Apple silicon
Other versions of macOS will compile from the source code rather than downloading pre-compiled binaries. This process can take anywhere from 30 minutes to several hours depending on your environment and internet connection.
macOS Prerequisites
Brew Install for Altinity Stable Instructions
By default, installing ClickHouse through brew
will install the latest version of the community version of ClickHouse. Extra steps are required to install the Altinity Stable version of ClickHouse. Altinity Stable is installed as a keg-only version, which requires manually setting paths and other commands to run the Altinity Stable for ClickHouse through brew
.
To install Altinity Stable for ClickHouse in macOS through Brew:
-
Add the ClickHouse formula via brew tap
:
brew tap altinity/clickhouse
-
Install Altinity Stable for ClickHouse by specifying clickhouse@altinity-stable
for the most recent Altinity Stable version, or specify the version with clickhouse@{Altinity Stable Version}
. For example, as of this writing the most current version of Altinity Stable is 21.8, therefore the command to install that version of altinity stable is clickhouse@21.8-altinity-stable
. To install the most recent version, use the brew install
command as follows:
brew install clickhouse@altinity-stable
-
Because Altinity Stable for ClickHouse is available as a keg only release, the path must be set manually. These instructions will be displayed as part of the installation procedure. Based on your version, executable directory will be different based on the pattern:
$(brew --prefix)/{clickhouse version}/bin
For our example, clickhouse@altinity-stable
gives us the following path setting:
export PATH="/opt/homebrew/opt/clickhouse@21.8-altinity-stable/bin:$PATH"
Using the which
command after updating the path reveals the location of the clickhouse-server
executable:
which clickhouse-server
/opt/homebrew/opt/clickhouse@21.8-altinity-stable/bin/clickhouse-server
-
To start the Altinity Stable for ClickHouse server use the brew services start
command. For example:
brew services start clickhouse@altinity-stable
-
Connect to the new server with clickhouse-client
:
> clickhouse-client
ClickHouse client version 21.8.13.1.
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 21.11.6 revision 54450.
ClickHouse client version is older than ClickHouse server. It may lack support for new features.
penny.home :) select version()
SELECT version()
Query id: 128a2cae-d0e2-4170-a771-83fb79429260
┌─version()─┐
│ 21.11.6.1 │
└───────────┘
1 rows in set. Elapsed: 0.004 sec.
penny.home :) exit
Bye.
-
To end the ClickHouse server, use brew services stop
command:
brew services stop clickhouse@altinity-stable
5 - Altinity Stable Build Guide for ClickHouse
How to build ClickHouse from Altinity Stable manually.
Organizations that prefer to build ClickHouse manually can use the Altinity Stable versions of ClickHouse directly from the source code.
Clone the Repo
Before using either the Docker or Direct build process, the Altinity Stable for ClickHouse must be downloaded from the Altinity Stable of ClickHouse repository, located at https://github.com/Altinity/clickhouse. The following procedure is used to update the source code to the most current version. For more information on downloading a specific version of the source code, see the GitHub documentation.
Hardware Recommendations
ClickHouse can run on the most minimum hardware to full clusters. The following hardware requirements are recommended for building and running ClickHouse:
- 16GB of RAM (32 GB recommende)
- Multiple cores (4+)
- 20-50 GB disk storage
Downloading Altinity Stable for ClickHouse
Before building ClickHouse, specify the verified version to download and build by specifying the Altinity Stable for ClickHouse tags. The `–recursive`` command will download all submodules part of the Altinity Stable project.
As of this writing, the most recent verified version is v21.8.10.19-altinitystable
, so the download command to download that version of Altinity Stable into the folder AltinityStableClickHouse
is:
git clone --recursive -b v21.8.10.19-altinitystable --single-branch https://github.com/Altinity/clickhouse.git AltinityStableClickHouse
.
Direct Build Instructions for Deb Based Linux
To build Altinity Stable for ClickHouse from the source code for Deb based Linux platforms:
-
Install the prerequisites:
sudo apt-get install git cmake python ninja-build
-
Install clang-12
.
sudo apt install clang-12
-
Create and enter the build
directory within your AltinityStable directory.
-
Set the compile variables to clang-12
and initiate the ninja
build.
CC=clang-12 CXX=clang++-12 cmake .. -GNinja
-
Provide the ninja
command to build your own Altinity Stable for ClickHouse:
-
Once complete, Altinity Stable for ClickHouse will be in the project’s programs
folder, and can be run with the following commands:
- ClickHouse Server:
clickhouse server
- ClickHouse Client:
clickhouse client
6 - Legacy ClickHouse Altinity Stable Releases Install Guide
How to install the ClickHouse Altinity Stable Releases from packagecloud.io.
ClickHouse Altinity Stable Releases are specially vetted community builds of ClickHouse that Altinity certifies for production use. We track critical changes and verify against a series of tests to make sure they’re ready for your production environment. We take the steps to verify how to upgrade from previous versions, and what issues you might run into when transitioning your ClickHouse clusters to the next Stable Altinity ClickHouse release.
As of October 12, 2021, Altinity replaced the ClickHouse Altinity Stable Releases with the Altinity Stable Builds, providing longer support and validation. For more information, see Altinity Stable Builds.
Legacy versions of the ClickHouse Altinity Stable Releases are available from the Altinity ClickHouse Stable Release packagecloud.io repository, located at https://packagecloud.io/Altinity/altinity-stable.
The available Altinity ClickHouse Stable Releases from packagecloud.io for ClickHouse server, ClickHouse client and ClickHouse common versions are:
- Altinity ClickHouse Stable Release 21.1.10.3
- Altinity ClickHouse Stable Release 21.3.13.9
- Altinity ClickHouse Stable Release 21.3.15.2
- Altinity ClickHouse Stable Release 21.3.15.4
General Installation Instructions
When installing or upgrading from a previous version of legacy 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 recommends you specify the version to install. The Release Notes lists the version numbers available for installation.
There are three main methods for installing the legacy ClickHouse Altinity Stable Releases:
Altinity ClickHouse Stable Releases are distinguishable from community builds when displaying version information. The suffix altinitystable
will be displayed after the version number:
select version()
┌─version()─────────────────┐
│ 21.3.15.2.altinitystable │
└───────────────────────────┘
Prerequisites
This guide assumes that the reader is familiar with Linux commands, permissions, and how to install software for their particular Linux distribution. The reader will have to verify they have the correct permissions to install the software in their target systems.
Installation Instructions
Legacy Altinity ClickHouse Stable Release DEB Builds
To install legacy ClickHouse Altinity Stable Release version DEB packages from packagecloud.io:
-
Update the apt-get
repository with the following command:
curl -s https://packagecloud.io/install/repositories/Altinity/altinity-stable/script.deb.sh | sudo bash
-
ClickHouse can be installed either by specifying a specific version, or automatically going to the most current version. It is recommended to specify a version for maximum compatibility with existing clients.
- To install a specific version, create a variable specifying the version to install and including it with the install command:
version=21.8.8.1.altinitystable
sudo apt-get install clickhouse-client=$version clickhouse-server=$version clickhouse-common-static=$version
- To install the most current version of the legacy 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
-
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 systemctl restart clickhouse-server
Legacy Altinity ClickHouse Stable Release RPM Builds
To install legacy ClickHouse Altinity Stable Release version RPM packages from packagecloud.io:
-
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
-
ClickHouse can be installed either by specifying a specific version, or automatically going to the most current version. It is recommended to specify a version for maximum compatibility with existing clients.
- To install a specific version, create a variable specifying the version to install and including it with the install command:
version=version=21.8.8.1.altinitystable
sudo yum install clickhouse-client-${version} clickhouse-server-${version} clickhouse-server-common-${version}
- To install the most current version of the legacy ClickHouse Altinity Stable release without specifying a specific version, leave out the
version=
command.
sudo yum install clickhouse-client clickhouse-server clickhouse-server-common
-
Restart the ClickHouse server.
sudo systemctl restart clickhouse-server