Installation

Introduction

This part of the documentation covers the installation of CrateDB on Linux, macOS and Windows systems. The first step to using any software package is getting it properly installed. Please read this section carefully.

By installing CrateDB the way as outlined in this document, you will be able to quickly setup and run a single-node cluster. The document describes different installation methods. While we recommend to use the package-based methods for Debian or Ubuntu and Red Hat or CentOS by subscribing to the respective release channels, you can also download release archives and run CrateDB manually using the Ad-hoc (Unix, macOS, Windows) method.

When the installation is finished, the CrateDB service should be up and running. Then, you can access the Admin UI from your local machine by navigating to:

http://localhost:4200/

After successfully installing CrateDB, please also consider reading the Post-install notes.

Note

CrateDB requires a Java virtual machine to run.

  • Starting with CrateDB 4.2, Java is bundled with CrateDB and no extra installation is necessary.

  • CrateDB versions before 4.2 required a separate Java installation. For CrateDB 3.0 to 4.1, Java 11 is the minimum requirement. CrateDB versions before 3.0 require Java 8. We recommend using OpenJDK on Linux Systems and Oracle Java on Microsoft Windows and macOS.

Try CrateDB without installing

If you want to try out CrateDB on Linux or macOS but would prefer to avoid the hassle of manual installation or extracting release archives, you can get a fresh CrateDB node up and running in your current working directory with a single command:

sh$ bash -c "$(curl -L https://try.crate.io/)"

Note

This is a quick way to try out CrateDB. It is not the recommended method to install CrateDB in a durable way. The following sections will outline that method.

Linux

Debian or Ubuntu

This section of the documentation outlines how to install CrateDB deb packages using the apt package manager.

Configure package repository

You will need to configure your system to register with and trust packages from the CrateDB package repository:

# Install prerequisites.
apt-get install sudo
sudo apt-get install curl gnupg software-properties-common apt-transport-https apt-utils

# Import the public GPG key for verifying the package signatures.
curl -sS https://cdn.crate.io/downloads/deb/DEB-GPG-KEY-crate | sudo apt-key add -

# Register with the CrateDB package repository.
[[ $(lsb_release --id --short) = "Debian" ]] && repository="apt"
[[ $(lsb_release --id --short) = "Ubuntu" ]] && repository="deb"
distribution=$(lsb_release --codename --short)
sudo add-apt-repository "deb https://cdn.crate.io/downloads/${repository}/stable/ ${distribution} main"

Note

CrateDB provides both stable release and testing release channels. To use the testing channel, replace stable with testing in the command line above. You can read more about the release workflow.

Now update the package sources:

sudo apt update

You should see a success message. This indicates that the CrateDB package repository is correctly registered.

Install CrateDB

With everything set up, you can install CrateDB:

sudo apt install crate

Control CrateDB

You can control the crate service with the systemctl utility program:

sudo systemctl COMMAND crate

Replace COMMAND with start, stop, restart, status and so on.

Red Hat or CentOS

This section of the documentation outlines how to install CrateDB RPM packages using the YUM package manager.

Configure package repository

You will need to configure your system to register with and trust packages from the CrateDB package repository:

# Install prerequisites.
yum install sudo

# Import the public GPG key for verifying the package signatures.
sudo rpm --import https://cdn.crate.io/downloads/yum/RPM-GPG-KEY-crate

# Register with the CrateDB package repository.
sudo rpm -Uvh https://cdn.crate.io/downloads/yum/7/x86_64/crate-release-7.0-1.x86_64.rpm

The command above will install the /etc/yum.repos.d/crate.repo package repository configuration file.

Note

CrateDB provides both stable release and testing release channels. You can read more about the release workflow.

By default, yum (Red Hat’s package manager) will use the stable repository. This is because the testing repository is disabled. If you would like to enable the testing repository, edit the crate.repo file and set enabled=1 within the [crate-testing] section.

Install CrateDB

With everything set up, you can install CrateDB:

sudo yum install crate

After the installation is finished, the crate service should be installed, but not running. Use the following command to start CrateDB:

sudo systemctl start crate

In order to make the service reboot-safe, invoke:

sudo systemctl enable crate

Control CrateDB

You can control the crate service with the systemctl utility program:

sudo systemctl COMMAND crate

Replace COMMAND with start, stop, restart, status and so on.

Docker

CrateDB and Docker are great matches thanks to CrateDB’s shared-nothing, horizontally scalable architecture that lends itself well to containerization.

In order to spin up a container using the most recent stable version of the official CrateDB Docker image, use:

docker run --publish=4200:4200 --publish=5432:5432 crate

Tip

If this command aborts with an error, please consult the Docker troubleshooting guide. You are also welcome learn more about Resource constraints with respect to running CrateDB within containers.

Caution

This type of invoking CrateDB will get you up and running quickly.

Please note, by default, the CreateDB Docker container is ephemeral, so data will not be stored in a persistent manner. When stopping the container, all data will be lost.

When you are ready to start using CrateDB for data you care about, please consult the full guide to CrateDB and Docker in order to configure the Docker setup appropriately by using persistent disk volumes.

Ad-hoc (Unix, macOS, Windows)

This section of the documentation outlines how to use the release archives to install CrateDB. The walkthrough is suitable to install and run CrateDB on both Unix-like systems as well as on Microsoft Windows.

  1. Download the latest CrateDB release archive. Please make sure to select the right release archive matching your system.

  2. Once downloaded, extract the archive either using your favorite terminal or command line shell or by using a GUI tool like 7-Zip:

    # Extract tarball on Unix-like systems
    tar -xzf crate-*.tar.gz
    
    # Extract Zip archive on Windows systems
    unzip -o crate-*.zip
    
  3. On the terminal, change into the extracted crate directory:

    cd crate-*
    
  4. Run a CrateDB single-node instance on the local network interface:

    ./bin/crate
    
  5. In order to stop CrateDB again, use ctrl-c.

Caution

We do not yet officially support CrateDB on Windows for production use. If you would like to deploy CrateDB on Windows, please feel free to contact us so we can work with you on a solution.

See also

Consult the CLI tools documentation for further information about the ./bin/crate command.

Notes about Microsoft Windows

If you are installing CrateDB on a recent Windows Server edition, setting up the latest Microsoft Visual C++ 2019 Redistributable package is required. You can download it at msvcrt x86-64, msvcrt x86-32 or msvcrt ARM64.

Within the terminal, as a Windows user, the prompt after starting PowerShell will look like this.

PS> ./bin/crate

Basic configuration

In order to configure CrateDB, please take note of the configuration file locations and the available environment variables.

Configuration files

When using the package-based setup flavor for Debian or Ubuntu or Red Hat or CentOS, the main CrateDB configuration files are located within the /etc/crate directory. When using the Ad-hoc (Unix, macOS, Windows) setup, the configuration files are located within the config/ directory.

Environment variables

When using the package-based setup flavor for Debian or Ubuntu or Red Hat or CentOS, the CrateDB startup script uses Environment variables from the /etc/default/crate file. When using the Ad-hoc (Unix, macOS, Windows) setup, the environment variables will be set by bin/crate{.sh,.bat}.

Here is an example:

# Configure heap size (defaults to 256m min, 1g max).
CRATE_HEAP_SIZE=2g

# Maximum number of open files, defaults to 65535.
# MAX_OPEN_FILES=65535

# Maximum locked memory size. Set to "unlimited" if you use the
# bootstrap.mlockall option in crate.yml. You must also set
# CRATE_HEAP_SIZE.
MAX_LOCKED_MEMORY=unlimited

# Provide additional Java OPTS.
# CRATE_JAVA_OPTS=

# Force the JVM to use IPv4 only.
CRATE_USE_IPV4=true

Post-install notes

After successfully installing the software, you might want to follow up with taking the guided tour.

Also, you might enjoy to be guided into further information about how to quickly adjust the configuration settings, read more details about the Configuration of CrateDB, the background about Bootstrap checks, multi-node configuration within the section about Clustering and Going into production. When operating a CrateDB cluster in production, performance tuning will also be of interest.

Note

As noted within the introductory section, this kind of installation flavor will let you quickly setup and run a single-node cluster.

To add additional CrateDB nodes to this kind of cluster in order to make it form a multi-node cluster, you will need to remove the cluster state after changing the configuration.

Feedback

How helpful was this page?