Getting started¶
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.
sudo apt update
sudo apt install --yes apt-transport-https apt-utils curl gnupg lsb-release
# Import the public GPG key for verifying the package signatures.
curl -sS https://cdn.crate.io/downloads/deb/DEB-GPG-KEY-crate | sudo tee /etc/apt/trusted.gpg.d/cratedb.asc
# Compute CrateDB package repository location.
[[ $(lsb_release --id --short) = "Debian" ]] && repository="apt"
[[ $(lsb_release --id --short) = "Ubuntu" ]] && repository="deb"
distribution=$(lsb_release --codename --short)
# Register with the CrateDB package repository.
echo "deb [signed-by=/etc/apt/trusted.gpg.d/cratedb.asc arch=amd64] https://cdn.crate.io/downloads/${repository}/stable/ ${distribution} main" \
| sudo tee /etc/apt/sources.list.d/cratedb.list
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.
The walkthrough is based on the sudo program. If it is not installed on
your machine, run apt update; apt install --yes sudo as a root user.
Now, update the package sources:
sudo apt update
You should see a success message. This indicates that the CrateDB package repository is correctly registered.
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 --pull=always 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.
Download the latest CrateDB release archive. Please make sure to select the right release archive matching your system.
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
On the terminal, change into the extracted
cratedirectory:cd crate-*
Run a CrateDB single-node instance on the local network interface:
./bin/crate
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:
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 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.