Environment Variables

CrateDB can be configured using environment variables that control both CrateDB-specific settings and Java Virtual Machine (JVM) options.

There are two main categories:

  1. Application variables – Affect CrateDB directly.

  2. JVM variables – Affect the Java Virtual Machine that runs CrateDB.

We use “application” here to distinguish between:

  • CrateDB (the Java application)

  • The JVM (the process that executes CrateDB)

Quick reference table

Variable
Type / Unit
Default
Description

CRATE_HOME

Path

—

Root directory of CrateDB installation. Used for config, data, and logs.

CRATE_JAVA_OPTS

String

—

Extra JVM options (e.g. GC tuning, stack size).

CRATE_HEAP_SIZE

Size (m / g)

—

Maximum JVM heap size.

CRATE_HEAP_DUMP_PATH

Path (file or directory)

Varies

Location for heap dumps on JVM crash.

Table of contents

Setting environment variables

The way you set environment variables depends on your deployment method (manual installation, Linux package, Docker, etc.).

Example – Manual installation:

export CRATE_HOME=/tmp/crate
./bin/crate

In this example:

  • CRATE_HOME is set to /tmp/crate

  • export makes it available to sub-processes

  • CrateDB is started from ./bin/crate

Application variables

CRATE_HOME — Directory path

The home directory of the CrateDB installation.

  • Used as the root for the configuration directory, data directory, log directory, etc.

  • For package installations, this is usually set automatically.

  • For manual installations, set this to the root directory where you run bin/crate.

JVM variables

CRATE_JAVA_OPTS — Java options

Custom JVM options for running CrateDB.

Example: Change stack size

CRATE_JAVA_OPTS=-Xss500k

📚 See also: Refer to your JVM documentation for Unix-like systems or Windows for available Java options.

CRATE_HEAP_SIZE — Heap size

The amount of memory allocated to the JVM heap.

Example: Set heap size to 4 GB

CRATE_HEAP_SIZE=4g

  • Use g for gigabytes or m for megabytes.

  • Proper heap sizing is critical for performance — too small may cause frequent GC pauses, too large may increase GC times.

CRATE_HEAP_DUMP_PATH — File or directory path (default: varies)

Path to store heap dumps in case of a JVM crash.

  • Directory path: A new dump file is created in that directory after each crash.

  • File path: The specified file is overwritten on each crash.

Defaults:

  • Basic installation: Process working directory

  • Linux package: /var/lib/crate

  • Docker: /data/data

Ensure sufficient disk space is available for heap dumps. Large heaps can produce equally large dump files.

PreviousLoggingNextCluster sizing

Last updated