From 289103473fdaffc53713ecf0a442f47f69d434cd Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 3 Jun 2026 12:54:56 +0000 Subject: [PATCH] docs: port clickhousectl install updates and restructure install nav --- core/get-started/about/deployment-modes.mdx | 4 +- core/get-started/navigation.json | 28 +++++++---- core/get-started/setup/install.mdx | 46 +++++++++++++------ .../setup/self-managed/advanced.mdx | 4 +- core/get-started/setup/self-managed/macos.mdx | 10 ++-- .../setup/self-managed/overview.mdx | 29 ++++++------ .../setup/self-managed/quick-install.mdx | 16 +++++-- snippets/_cli_install.mdx | 26 ++++++++--- 8 files changed, 106 insertions(+), 57 deletions(-) diff --git a/core/get-started/about/deployment-modes.mdx b/core/get-started/about/deployment-modes.mdx index e723500a..f4e28d30 100644 --- a/core/get-started/about/deployment-modes.mdx +++ b/core/get-started/about/deployment-modes.mdx @@ -65,8 +65,8 @@ For local development, `clickhousectl` helps to install ClickHouse versions and # Install the CLI curl https://clickhouse.com/cli | sh -# Install and start ClickHouse locally -clickhousectl local install stable +# Install the latest stable ClickHouse, set it as your default, and symlink the clickhouse binary onto your PATH +clickhousectl local use stable clickhousectl local server start clickhousectl local client ``` diff --git a/core/get-started/navigation.json b/core/get-started/navigation.json index 3bc1579f..f736f045 100644 --- a/core/get-started/navigation.json +++ b/core/get-started/navigation.json @@ -49,15 +49,25 @@ "expanded": true, "root": "core/get-started/setup/self-managed/overview", "pages": [ - "core/get-started/setup/self-managed/quick-install", - "core/get-started/setup/self-managed/debian-ubuntu", - "core/get-started/setup/self-managed/redhat", - "core/get-started/setup/self-managed/other-linux", - "core/get-started/setup/self-managed/macos", - "core/get-started/setup/self-managed/windows", - "core/get-started/setup/self-managed/docker", - "core/get-started/setup/self-managed/nixos", - "core/get-started/setup/self-managed/advanced" + { + "group": "Local development", + "expanded": true, + "pages": [ + "core/get-started/setup/self-managed/quick-install", + "core/get-started/setup/self-managed/docker", + "core/get-started/setup/self-managed/advanced" + ] + }, + { + "group": "Production server", + "expanded": true, + "pages": [ + "core/get-started/setup/self-managed/debian-ubuntu", + "core/get-started/setup/self-managed/redhat", + "core/get-started/setup/self-managed/other-linux", + "core/get-started/setup/self-managed/nixos" + ] + } ] }, { diff --git a/core/get-started/setup/install.mdx b/core/get-started/setup/install.mdx index 06e24ca3..5835107a 100644 --- a/core/get-started/setup/install.mdx +++ b/core/get-started/setup/install.mdx @@ -2,13 +2,11 @@ slug: /install title: 'Install ClickHouse' sidebarTitle: 'Install' -description: 'Choose how to install ClickHouse — Cloud, a platform-specific package, Docker, or a migration from another database.' +description: 'Choose how to install ClickHouse — Cloud, a quick local install, Docker, or a production server package.' keywords: ['clickhouse', 'install', 'getting started', 'quick start'] doc_type: 'landing-page' --- -Pick a deployment option or install method. - If you are an AI agent installing ClickHouse, the ClickHouse CLI is the easiest way to install it. Run the following one-liner — it auto-detects your OS and @@ -23,13 +21,35 @@ queries with `./clickhouse local`. No package manager, no Docker, no root required. - + Spin up a managed ClickHouse service in minutes — no infrastructure to operate. + + +## Local development + +Run ClickHouse on your own machine to build, test, and experiment. The +ClickHouse CLI is the quickest path and the one the rest of our guides assume. + + - One-line install script for trying ClickHouse locally on Linux or macOS. + Install locally with the ClickHouse CLI (`clickhousectl`) on Linux or macOS. + + Run ClickHouse in a Docker container. + + + Build from source or install a CI-generated binary. + + + +## Production server + +Install ClickHouse Server from packages or binaries for a long-running +deployment on your own infrastructure. + + Install via `apt-get` from the official ClickHouse repository. @@ -39,19 +59,15 @@ required. Install on other Linux distributions via the prebuilt tarball. - - Install on macOS via the prebuilt binary or Homebrew. - - - Install on Windows via WSL. - - - Run ClickHouse in a Docker container. - Install on NixOS via the Nix package manager. + + +## Migrate from elsewhere + + Move data from PostgreSQL, BigQuery, Snowflake, Redshift, Elasticsearch, and more. - \ No newline at end of file + diff --git a/core/get-started/setup/self-managed/advanced.mdx b/core/get-started/setup/self-managed/advanced.mdx index aeed2556..a58d065a 100644 --- a/core/get-started/setup/self-managed/advanced.mdx +++ b/core/get-started/setup/self-managed/advanced.mdx @@ -1,9 +1,9 @@ --- description: 'Instructions for compiling ClickHouse from source or installing a CI-generated binary' keywords: ['ClickHouse', 'install', 'advanced', 'compile from source', 'CI generated binary'] -sidebarTitle: 'Advanced install' +sidebarTitle: 'Source & CI builds' slug: /install/advanced -title: 'Advanced installation methods' +title: 'Source & CI builds' hide_title: false doc_type: 'guide' --- diff --git a/core/get-started/setup/self-managed/macos.mdx b/core/get-started/setup/self-managed/macos.mdx index deac313e..cccf0189 100644 --- a/core/get-started/setup/self-managed/macos.mdx +++ b/core/get-started/setup/self-managed/macos.mdx @@ -1,13 +1,13 @@ --- -description: 'Install ClickHouse on MacOS' -keywords: ['ClickHouse', 'install', 'MacOS'] +description: 'Install ClickHouse on macOS using the ClickHouse CLI' +keywords: ['ClickHouse', 'install', 'MacOS', 'clickhousectl', 'CLI'] sidebarTitle: 'MacOS' slug: /install/macOS -title: 'Install ClickHouse using Homebrew' +title: 'Install ClickHouse on macOS' hide_title: true doc_type: 'guide' --- -import MacOSProd from '/snippets/_macos.mdx'; +import CLIInstall from '/snippets/_cli_install.mdx'; - + diff --git a/core/get-started/setup/self-managed/overview.mdx b/core/get-started/setup/self-managed/overview.mdx index 71695c6f..5837b53b 100644 --- a/core/get-started/setup/self-managed/overview.mdx +++ b/core/get-started/setup/self-managed/overview.mdx @@ -3,15 +3,28 @@ title: 'Self-managed install' sidebarTitle: 'Overview' description: 'Install ClickHouse on your own infrastructure.' doc_type: 'landing-page' -keywords: ['install', 'self-managed', 'linux', 'macos', 'windows', 'docker'] +keywords: ['install', 'self-managed', 'linux', 'docker'] --- Install ClickHouse on the platform you operate. +## Local development + - Fastest path: download the universal binary and run. + Install locally with the ClickHouse CLI on Linux or macOS. + + Pull the official Docker image and run a container. + + + Build from source and other advanced installation paths. + + + +## Production server + + Install via the official APT repository. @@ -21,19 +34,7 @@ Install ClickHouse on the platform you operate. Generic Linux distribution install via tarball. - - Install on macOS with Homebrew or the universal binary. - - - Run ClickHouse on Windows via WSL. - - - Pull the official Docker image and run a container. - Install on NixOS via the package manager. - - Build from source and other advanced installation paths. - diff --git a/core/get-started/setup/self-managed/quick-install.mdx b/core/get-started/setup/self-managed/quick-install.mdx index 6d79864d..6087d8ea 100644 --- a/core/get-started/setup/self-managed/quick-install.mdx +++ b/core/get-started/setup/self-managed/quick-install.mdx @@ -16,8 +16,10 @@ insert data into it, and run a SELECT query. ## Install the ClickHouse CLI {#install-the-cli} -The ClickHouse CLI (`clickhousectl`) helps you install and manage local ClickHouse -versions, launch servers, and run queries. Install it with: +The ClickHouse CLI (`clickhousectl`) helps you install local ClickHouse +versions, launch servers, run queries and manage ClickHouse Cloud. + +Install it with: ```bash curl https://clickhouse.com/cli | sh @@ -31,12 +33,18 @@ A `chctl` alias is also created automatically for convenience. ClickHouse runs natively on Linux and macOS, and runs on Windows via the [WSL](https://learn.microsoft.com/en-us/windows/wsl/about). -Use the CLI to install the latest stable version of ClickHouse: +Use the CLI to install the latest stable version of ClickHouse and make it your default: ```bash -clickhousectl local install stable +clickhousectl local use stable ``` +`local use` installs the version if it isn't already present, sets it as your +default, and creates a `clickhouse` symlink in `~/.local/bin` (on your `PATH`) +so you can invoke the `clickhouse` binary directly. The later steps in this +guide rely on that symlink. To download a version without changing your default +or updating the symlink, use `clickhousectl local install ` instead. + This isn't the recommended way to install ClickHouse for production. If you're looking to install a production instance of ClickHouse, please see the [install page](/core/get-started/setup/install). diff --git a/snippets/_cli_install.mdx b/snippets/_cli_install.mdx index 38f5f6c6..1cae8949 100644 --- a/snippets/_cli_install.mdx +++ b/snippets/_cli_install.mdx @@ -16,19 +16,33 @@ A `chctl` alias is also created automatically for convenience. ## Install ClickHouse {#cli-install-clickhouse} -Install the latest stable version of ClickHouse: +Install the latest stable version of ClickHouse and make it your default: ```bash -clickhousectl local install stable +clickhousectl local use stable ``` -You can also install a specific version: +`local use` installs the version if it isn't already present, sets it as your +default, and creates a `clickhouse` symlink in `~/.local/bin` (on your `PATH`) +so you can invoke the `clickhouse` binary directly. Any later step in these docs +that runs a `clickhouse` command then works as-is. + +You can also select a specific version: ```bash -clickhousectl local install lts # Latest LTS release -clickhousectl local install 25.6 # Latest 25.6.x.x -clickhousectl local install 25.6.1.1 # Exact version +clickhousectl local use lts # Latest LTS release +clickhousectl local use 25.6 # Latest 25.6.x.x +clickhousectl local use 25.6.1.1 # Exact version ``` + + +**Use vs install** + +`clickhousectl local use ` installs a version *and* makes it your +default, updating the `clickhouse` symlink on your `PATH`. To download a version +without changing your default or updating the symlink, use +`clickhousectl local install ` instead. + ## Start clickhouse-server {#cli-start-clickhouse-server}