Link Search Menu Expand Document
Start for Free

Docker Server Configuration

This page covers server configuration for Stardog running in Docker, including memory settings, scratch space, and OS-level tuning.

Page Contents
  1. Production Configuration
  2. Passing Environment Variables
  3. Passing Server Startup Options
  4. Memory Configuration
  5. Disk Storage
  6. Scratch Space
  7. Open Files Setting
  8. vm.swappiness Setting
  9. CAP_SYS_NICE Setting
  10. TCP KeepAlive
  11. Loading External JARs

Production Configuration

A production deployment combines multiple settings. The following example shows the structure of a production docker run command:

$ docker run -d --name stardog \
  --ulimit nofile=100000:100000 \
  --memory-swappiness=0 \
  --cap-add SYS_NICE \
  --sysctl net.ipv4.tcp_keepalive_time=120 \
  -e STARDOG_SERVER_JAVA_ARGS="-Xmx8g -Xms8g -XX:MaxDirectMemorySize=20g -Djava.io.tmpdir=/var/opt/stardog/tmp" \
  -v ~/stardog-home:/var/opt/stardog \
  -p 5820:5820 \
  stardog/stardog

The values shown above are examples. Adjust them based on your environment—particularly memory settings, which depend on your data volume. See the sections below for guidance on each setting.

Passing Environment Variables

Use Docker’s -e flag to pass environment variables to the container. For example, to configure JVM memory settings:

$ docker run -v ~/stardog-home:/var/opt/stardog -p 5820:5820 \
  -e STARDOG_SERVER_JAVA_ARGS="-Xmx8g -Xms8g -XX:MaxDirectMemorySize=20g" \
  stardog/stardog

Common environment variables:

  • STARDOG_SERVER_JAVA_ARGS - JVM options (heap size, direct memory, GC settings, temp directory)
  • STARDOG_EXT - Path to external JARs inside the container

Passing Server Startup Options

The Docker image runs stardog-admin server start as its entrypoint. Append startup options to the end of the docker run command:

$ docker run -v ~/stardog-home:/var/opt/stardog -p 5820:5820 \
  stardog/stardog --enable-ssl

Multiple options can be combined:

$ docker run -v ~/stardog-home:/var/opt/stardog -p 5820:5820 \
  stardog/stardog --enable-ssl --bind 192.168.1.100

For available startup options, see the server start man page. For SSL configuration, see Setting up SSL.

Memory Configuration

Memory configuration is critical for production performance. The default settings (2GB heap + 1GB direct) are for testing only and will produce a warning on startup. Always configure memory for production use.

Configure memory using the STARDOG_SERVER_JAVA_ARGS environment variable:

$ docker run \
  -e STARDOG_SERVER_JAVA_ARGS="-Xmx8g -Xms8g -XX:MaxDirectMemorySize=20g" \
  -v ~/stardog-home:/var/opt/stardog -p 5820:5820 stardog/stardog

See Capacity Planning for memory sizing based on your data volume. Key points:

  • Minimum 32GB system memory for production
  • Set -Xms and -Xmx to the same value
  • Direct memory should be higher than heap memory

Disk Storage

Stardog runs best on local / block storage devices. Network based disk storage is not recommended, including NFS, SMB, and EFS based storage systems.

If you must use network based disk, please set the following property within stardog.properties file in your $STARDOG_HOME directory:

storage.envoptions.use_mmap_writes = false

Scratch Space

Stardog writes temporary files to three locations:

  1. Temp directory (java.io.tmpdir) - Used for sorting pages during a bulk load, and for buffering the incoming stream when a cluster node performs a full sync. Defaults to /tmp in the container.
  2. Spilling directory (spilling.dir) - Used when queries exceed available memory. Defaults to $STARDOG_HOME/.spilling.
  3. Checkpoint staging ($STARDOG_HOME/data/checkpoints) - Used for SST files during a bulk load, for staging a backup before it is uploaded to cloud storage, and for extracting a backup or a peer’s checkpoint during a restore or cluster sync. Not configurable: these files are hard-linked into the database rather than copied, which only works within one filesystem.

Ensure all three locations have sufficient disk space. For better I/O performance, consider placing the first two on separate fast disks.

A full sync is the heaviest case and needs space on both volumes: the joining node buffers the incoming stream in java.io.tmpdir and stages the checkpoint under $STARDOG_HOME, each roughly the size of the database being transferred, on top of the space for the database itself. A restore from a cloud backup needs the same under $STARDOG_HOME. Size both volumes accordingly on nodes that may need to re-sync.

Entries under $STARDOG_HOME/data/checkpoints whose names begin with .tmp- are transient. They are removed when the operation finishes, and any left behind by a server that was killed are swept at the next startup. Do not delete them while the server is running — they may belong to a load or sync in progress.

To configure the temp directory, add -Djava.io.tmpdir to STARDOG_SERVER_JAVA_ARGS:

$ docker run \
  -e STARDOG_SERVER_JAVA_ARGS="-Xmx8g -Xms8g -XX:MaxDirectMemorySize=20g -Djava.io.tmpdir=/var/opt/stardog/tmp" \
  -v ~/stardog-home:/var/opt/stardog -p 5820:5820 stardog/stardog

To configure the spilling directory, add to stardog.properties:

spilling.dir=/path/to/spilling

If using a path outside $STARDOG_HOME, mount it as an additional volume.

Running out of disk space in either location can cause query failures or data loss.

Open Files Setting

Stardog requires at least 100,000 open files. This limit impacts both the number of active files and network connections.

When running Docker, set this with the --ulimit option:

$ docker run --ulimit nofile=100000:100000 \
  -v ~/stardog-home:/var/opt/stardog -p 5820:5820 stardog/stardog

The Docker host must also allow this limit. On the host, configure /etc/security/limits.conf or create /etc/security/limits.d/90-stardog.conf with:

*    soft    nofile    100000
*    hard    nofile    100000

vm.swappiness Setting

Linux platforms may have a swap partition. The vm.swappiness parameter controls how the kernel utilizes swap memory. The default value (60) is tuned for desktops, not production servers. Stardog performs better with this set to zero.

Set this with the --memory-swappiness option:

$ docker run --memory-swappiness=0 \
  -v ~/stardog-home:/var/opt/stardog -p 5820:5820 stardog/stardog

On the Docker host, you can also set this system-wide by adding vm.swappiness=0 to /etc/sysctl.conf and rebooting.

CAP_SYS_NICE Setting

Stardog prioritizes user queries over background database grooming jobs. The SYS_NICE capability allows Stardog to adjust thread priorities for optimal performance.

Add the --cap-add option to enable this:

$ docker run --cap-add SYS_NICE \
  -v ~/stardog-home:/var/opt/stardog -p 5820:5820 stardog/stardog

TCP KeepAlive

Long-running queries may be disconnected by network infrastructure that terminates idle connections (e.g., Azure has a 4-minute limit). TCP keepalive signals prevent this by indicating the connection is still active.

Stardog enables keepalive since version 10.2, but the Linux default timeout (2 hours) is too long. Set it to 120 seconds using --sysctl:

$ docker run --sysctl net.ipv4.tcp_keepalive_time=120 \
  -v ~/stardog-home:/var/opt/stardog -p 5820:5820 stardog/stardog

For full control over keepalive behavior:

$ docker run \
  --sysctl net.ipv4.tcp_keepalive_time=120 \
  --sysctl net.ipv4.tcp_keepalive_intvl=60 \
  --sysctl net.ipv4.tcp_keepalive_probes=20 \
  -v ~/stardog-home:/var/opt/stardog -p 5820:5820 stardog/stardog

For more information, see the TCP Keepalive HOWTO.

Loading External JARs

If you need to load external JARs (e.g., JDBC drivers for virtual graphs or custom functions), you must set the STARDOG_EXT environment variable and mount a volume containing the JARs:

docker run -v ~/stardog-home/:/var/opt/stardog \
 -v ~/stardog-ext:/var/opt/stardog-ext \
 -e STARDOG_EXT=/var/opt/stardog-ext \
 -p 5820:5820 stardog/stardog

In this example, ~/stardog-ext is a directory on your host machine containing your JAR files (such as JDBC drivers). The container will load any JARs found in the directory specified by STARDOG_EXT at startup.