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

• Application variables

• JVM variables

---

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.