Link Search Menu Expand Document
Start for Free

Persisting Data with Docker Volumes

This page describes how to persist data with Docker volumes.

Overview

When running Stardog within a Docker container, the data generated by Stardog (databases, stardog.properties, the license file, logs) reside within the container’s filesystem. By default, this data is ephemeral: if the container is removed, all the data is lost.

To ensure your Stardog data survives container restarts and removals, you must use Docker volumes. Volumes mount a directory from the host machine or a Docker-managed storage area into the container, effectively storing the data outside the container’s lifecycle.

Why Persistence is Crucial

Data persistence offers the following benefits:

  • Data Safety: Prevents loss of your data when containers are stopped, removed, or recreated (e.g., during upgrades).
  • Configuration Management: Allows you to manage Stardog configuration files (stardog.properties, log4j2.xml) outside the container.
  • Upgrades: Simplifies the Stardog upgrade process. You can stop the old container, pull a new Stardog image, and start a new container pointing to the same volume, retaining all your data.

The Stardog Home Directory (STARDOG_HOME)

Stardog stores all its critical data within its home directory, STARDOG_HOME. By default, this directory is set to /var/opt/stardog. The home directory is where you need to mount a Docker volume into. If you configure a different STARDOG_HOME using environment variables, ensure your volume mapping points to that custom location instead.

Methods for Persisting Data

There are two primary ways to use Docker volumes for persistence:

  • Named Volumes (Recommended): Docker manages the volume’s storage location on the host machine. This is generally simpler and more portable across operating systems. Docker handles permissions more transparently than do bind mounts.
  • Bind Mounts: You specify an exact path on your host machine to be mounted into the container. This gives you direct access to the files on the host but requires careful management of the host directory and potential file permissions.

Named Volumes

This is the recommended approach for most users.

Create a named volume

You can create a named volume named stardog-home with the following command:

docker volume create stardog-home

Migrating License Key and Existing Data/Configuration

When you first create or use a named volume like stardog-home, it contains no files. Stardog requires at least a license key to function correctly. You must place your Stardog license key (e.g., stardog-license-key.bin) into the named volume before first starting the main Stardog container that uses this volume. Without it, Stardog will fail to start.

If you are moving from a non-Docker Stardog setup or another configuration, you also need to copy any existing data directories, stardog.properties files, log configurations, etc., from your old STARDOG_HOME into this volume.

How to Copy Files into the Named Volume

Because named volumes are managed by Docker and do not map to a user-facing directory by default, accessing them requires using docker cp with a temporary utility container:

First, run a lightweight container mounting the volume:

# Mounts 'stardog-home' to '/volume_data' inside a temporary alpine container
docker run -d --name temp-vol-helper -v stardog-home:/volume_data alpine sleep infinity

If you are migrating an existing home directory, copy it to the temporary container and change the permissions to user and group 1000:

# Copy your home directory to temp-vol-helper (note trailing '/.')
docker cp /path/to/stardog/home/. temp-vol-helper:/volume_data/

# Set permissions to 1000:1000 inside the /volume_data in the alpine container
docker exec -it temp-vol-helper chown -R 1000:1000 /volume_data

If you’re just adding a license key (i.e., you don’t have an existing installation), you can mereley copy that to /volume_data:

docker cp /path/on/host/stardog-license-key.bin temp-vol-helper:/volume_data/stardog-license-key.bin

Once you’ve done that, stop and remove the temporary container:

docker stop temp-vol-helper && docker rm temp-vol-helper

Start Stardog

Run Stardog with the volume. Use the -v or --volume flag with the format volume-name:/path/in/container:

docker run -it -p 5820:5820 \ 
  -v stardog-home:/var/opt/stardog \ 
  --name my-stardog \ 
  stardog/stardog
  • -p 5820:5820: Exposes the default Stardog port.
  • -v stardog-home:/var/opt/stardog: Maps the named volume stardog-home to the Stardog home directory inside the container. If stardog-home doesn’t exist, Docker creates it.
  • --name my-stardog: Assigns a convenient name to the container.

Now, if you stop (docker stop my-stardog) and remove (docker rm my-stardog) this container, the stardog-home volume remains. You can start a new Stardog container using the same -v stardog-home:/var/opt/stardog mapping, and it will pick up all the existing data.

Bind Mounts

With bind mounts, you map a specific directory from your host system. Use the -v or --volume flag with the format /path/on/host:/path/in/container.

docker run -it -p 5820:5820 \ 
  -v ~/Documents/stardog-home/:/var/opt/stardog \ 
  --name my-stardog \ 
  stardog/stardog
  • -p 5820:5820: Exposes the default Stardog port.
  • -v ~/Documents/stardog-home/:/var/opt/stardog: Maps the directory ~/Documents/stardog-home/ (or your chosen path) on the host to /var/opt/stardog inside the container.
  • --name my-stardog: Assigns a convenient name to the container.

Bind mounts can sometimes lead to permission errors if the user ID (UID) and group ID (GID) running the Stardog process inside the container don’t have write access to the mounted host directory. We discussed avoiding this issue with named volumes above. If you encounter permission issues with bind mounts, you may need to chown the host directory to match the UID/GID used by the Stardog container process. By default, these are both set to 1000, so the command would be sudo chown -R 1000:1000 /path/on/host/stardog-home.

Important Considerations

  • Backups: Docker volumes provide persistence, not backups. You can see how to back up databases here and back up your server here.
  • Location of Named Volumes: Docker manages the location of named volumes. You can inspect a volume’s location using docker volume inspect <volume-name>, but you generally shouldn’t manipulate files there directly. Use bind mounts if you need direct, predictable host path access.

By using Docker volumes, you ensure that your Stardog deployment is robust and your data is safely persisted outside the lifecycle of individual containers. Choose the volume type (named volume or bind mount) that best suits your operational needs.