Getting started

Security and upgrade notes

Warning

CrateDB versions prior to 4.6.6 are suspicable to the Log4Shell issue published on December 12, 2021. Please consider upgrading to the most recent version and follow up reading CrateDB Log4Shell mitigations.

Introduction

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

By installing CrateDB the way outlined in this document, you will be able to quickly set up and run a single-node cluster. The document describes different installation methods. While we recommend using 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) 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.

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 [arch=amd64] 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 to 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)

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 Unix-like systems.

  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
    
  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.

See also

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

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) setup or the Microsoft 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) setup or the Microsoft 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 by taking the guided tour.

Also, you might enjoy being guided through further information:

Note

As noted within the introductory section, this kind of installation flavor will let you quickly set up 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?