Operating System CentOS

How to Install CrateDB (Crate.IO) on AlmaLinux 9 or Rocky Linux 9

Add the official CrateDB RPM repository on AlmaLinux 9 or Rocky Linux 9, start a single node, create a database user and connect with the Admin UI and the crash shell.

CrateDB is a distributed SQL database built for large volumes of time-series, document and search data. It was originally published as Crate.IO, which is still the name of the company behind it. This guide installs a single CrateDB node on AlmaLinux 9 or Rocky Linux 9 from the vendor's RPM repository, checks it, creates a password-protected user and connects with the web Admin UI and the crash command-line shell. CentOS 7 reached end of life in June 2024; the commands below also apply to RHEL 9 and CentOS Stream 9.

Requirements

  • An x86-64 server running AlmaLinux 9, Rocky Linux 9 or RHEL 9.
  • At least 2 GB of RAM for testing; CrateDB is a Java application and benefits from much more in production. The RPM bundles its own Java runtime, so you do not install a JDK separately.
  • A user with sudo rights.

Update the system first:

sudo dnf upgrade -y

Add the CrateDB repository

Import the package signing key:

sudo rpm --import https://cdn.crate.io/downloads/yum/RPM-GPG-KEY-crate

Create the repository file. The path contains a 7 for historical reasons; it is the one repository CrateDB publishes for all Red Hat-compatible releases:

sudo tee /etc/yum.repos.d/cratedb.repo > /dev/null <<'EOF'
[cratedb-ce-stable]
name=CrateDB RPM package repository - $basearch - Stable
baseurl=https://cdn.crate.io/downloads/yum/7/$basearch
enabled=0
gpgcheck=1
gpgkey=https://cdn.crate.io/downloads/yum/RPM-GPG-KEY-crate
autorefresh=1
type=rpm-md
EOF

The repository is deliberately disabled (enabled=0), so a routine dnf upgrade never upgrades your database by surprise. You enable it explicitly each time you install or upgrade CrateDB.

Install and start CrateDB

sudo dnf install --enablerepo=cratedb-ce-stable crate

The service does not start by itself. Start it and enable it at boot:

sudo systemctl start crate
sudo systemctl enable crate

Check the state and the log if something goes wrong:

sudo systemctl status crate
sudo journalctl -u crate --no-pager -n 50

Verify the node

CrateDB listens on port 4200 for HTTP (REST API and Admin UI), 5432 for the PostgreSQL wire protocol and 4300 for node-to-node traffic. Out of the box it binds to the loopback interface only. Query the HTTP endpoint from the server itself:

curl -sS http://127.0.0.1:4200/

The JSON reply contains the node name, the cluster name crate and the installed version number.

Configuration files

  • /etc/crate/crate.yml – main configuration (network, cluster, authentication, paths).
  • /etc/default/crate – environment variables read by the service, for example the heap size.

The heap defaults to at most 1 GB. The comments in crate.yml suggest starting at about 25% of the machine's memory. On an 8 GB server, add this line to /etc/default/crate:

CRATE_HEAP_SIZE=2g

Restart after any configuration change:

sudo systemctl restart crate

Install crash and create a user

crash is CrateDB's interactive SQL shell. The quickest way to get it is the standalone executable, which only needs the system Python:

curl -o crash https://cdn.crate.io/downloads/releases/crash_standalone_latest
chmod +x crash
sudo mv crash /usr/local/bin/crash

Connect to the local node. The packaged configuration trusts the built-in superuser crate when the connection comes from the server itself:

crash --hosts http://127.0.0.1:4200

Create your own user with a password and grant it privileges. Every connection that does not come from localhost as crate must authenticate with a password, so this is the account you use remotely:

CREATE USER deploy WITH (password = 'choose-a-strong-password');
GRANT ALL PRIVILEGES TO deploy;

Try a first table while you are there:

CREATE TABLE readings (ts TIMESTAMP WITH TIME ZONE, sensor TEXT, value DOUBLE PRECISION);
INSERT INTO readings (ts, sensor, value) VALUES (now(), 'probe-1', 21.5);
REFRESH TABLE readings;
SELECT * FROM readings;

Leave the shell with \q.

Open the Admin UI

The Admin UI is served at http://localhost:4200/ on the node. Because CrateDB only listens on loopback by default, the safest way to reach it from your computer is an SSH tunnel:

ssh -L 4200:127.0.0.1:4200 deploy@203.0.113.10

Then open http://localhost:4200/ in your browser. Nothing is exposed to the internet and no firewall change is required.

Optional: listen on the network

If applications on other hosts must connect, bind CrateDB to a non-loopback address. As soon as you do, CrateDB runs its bootstrap checks at startup and refuses to start if the system is not prepared, so do the following in order.

Raise the kernel's memory-map limit:

echo 'vm.max_map_count = 262144' | sudo tee /etc/sysctl.d/90-cratedb.conf
sudo sysctl --system

Add these lines to /etc/crate/crate.yml for a one-node installation:

network.host: _site_
discovery.type: single-node

_site_ binds to the server's private (site-local) address; use 0.0.0.0 only if the server has no private network and you restrict access with the firewall. Restart the service, then allow only the client address through firewalld:

sudo systemctl restart crate
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="198.51.100.20" port port="4200" protocol="tcp" accept'
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="198.51.100.20" port port="5432" protocol="tcp" accept'
sudo firewall-cmd --reload

Remote clients now log in as the user you created, for example crash --hosts http://203.0.113.10:4200 -U deploy. Port 4200 is plain HTTP; for traffic over the public internet, configure TLS in CrateDB or keep using the SSH tunnel.

Upgrade CrateDB

Read the release notes for the target version, then upgrade with the repository enabled for that one transaction:

sudo dnf upgrade --enablerepo=cratedb-ce-stable crate
sudo systemctl restart crate

Frequently asked questions

Is Crate.IO the same thing as CrateDB?

Yes. The database is called CrateDB; Crate.io is the company that develops it. Packages, the service and the system user are still named crate.

Can I use PostgreSQL clients?

CrateDB speaks the PostgreSQL wire protocol on port 5432, so psql and most PostgreSQL drivers can connect. It is not a drop-in PostgreSQL replacement, though: its SQL dialect and feature set differ, so check the reference before porting an application.

Why does CrateDB fail to start after I changed network.host?

A non-loopback address activates the bootstrap checks. The usual causes are vm.max_map_count below 262144 or missing discovery settings. The reason is printed in journalctl -u crate.

How do I grow from one node to a cluster?

Install the same CrateDB version on each host, give all nodes the same cluster.name, and configure the seed hosts and initial master nodes as described in the vendor's multi-node guide. A node that already started as a single-node cluster needs its cluster state reset before it can join others, so plan the topology before loading data.

Share story:

Continue reading other guides on How VPS.