Run Stardog over SSL in Docker

This page explains how to enable HTTPS connections to Stardog when the server runs in a Docker container.

Overview

The official Stardog container invokes stardog-admin server start as its entrypoint. Enabling SSL therefore follows the same sequence as a non-container deployment: prepare certificates, point Stardog to a keystore (and optionally a truststore), then start the server with --enable-ssl or --require-ssl. The Docker-specific consideration is file placement: Stardog manages everything in STARDOG_HOME, so keystore and truststore files should live in a separate mounted directory the container can read.

This page shows how to stage those files and launch the container. For background on creating certificates, keystores, and truststores, see Encryption in Transit.

Before you begin

Create or acquire the certificate and keystore artifacts described in Step 1 and Step 2.
Ensure you have a Stardog home directory prepared on the host and mounted into the container (see Persisting Data with Docker Volumes).
Create a separate host directory or Docker volume to hold TLS material outside STARDOG_HOME.
Have your Stardog license key in the mounted home directory.

1. Stage TLS assets outside `STARDOG_HOME`

Pick a container path for the TLS material, such as /stardog-security. This directory should be provided by either a bind mount or a dedicated Docker volume so that it remains separate from /var/opt/stardog.

If you use a named volume, populate it with the keystore and optional truststore before starting Stardog:

 docker volume create stardog-security
 docker run -d --name temp-vol-helper -v stardog-security:/volume_tls alpine sleep infinity
 docker cp ./my-keystore.jks temp-vol-helper:/volume_tls/my-keystore.jks
 docker cp ./my-truststore.jks temp-vol-helper:/volume_tls/my-truststore.jks
 docker exec temp-vol-helper chown -R 1000:1000 /volume_tls
 docker stop temp-vol-helper && docker rm temp-vol-helper

For bind mounts, copy the files into a host directory (for example, ~/stardog-security) and ensure they are readable by UID/GID 1000, which is the user the container runs as by default.

Update the stardog.properties file inside STARDOG_HOME so Stardog knows where to find the keystore (and optionally the truststore). The example below assumes the TLS directory is mounted at /stardog-security:
```
 javax.net.ssl.keyStore=/stardog-security/my-keystore.jks
 javax.net.ssl.keyStorePassword=changeit
 # Optional when the server must trust certificates presented by other systems
 javax.net.ssl.trustStore=/stardog-security/my-truststore.jks
 javax.net.ssl.trustStorePassword=changeit
```
If you prefer, the same values can be supplied at runtime through the STARDOG_SERVER_JAVA_ARGS environment variable.

2. Start the container with SSL enabled

Expose the HTTPS port(s) you intend to use, then append the desired server flag to the docker run command.

Allow both HTTP and HTTPS
```
  docker run -it --name my-stardog \
    -v stardog-home:/var/opt/stardog \
    -v stardog-security:/stardog-security \
    -p 5820:5820 \
    -p 5821:5821 \
    stardog/stardog --enable-ssl
```
In this mode, Stardog keeps HTTP on port 5820 and creates an HTTPS listener on port 5821. Map both ports if clients will use HTTPS. Replace stardog-security:/stardog-security with a bind mount path (for example, /path/to/security:/stardog-security) if you are not using a named volume for the TLS assets.
Require HTTPS only
```
  docker run -it --name my-stardog \
    -v stardog-home:/var/opt/stardog \
    -v stardog-security:/stardog-security \
    -p 5820:5820 \
    stardog/stardog --require-ssl
```
When --require-ssl is used the server accepts HTTPS exclusively, bound to port 5820 by default. Override the port with --port <number> if you need a different listener.

If you did not embed the keystore settings into stardog.properties, set them with STARDOG_SERVER_JAVA_ARGS:

docker run -it --name my-stardog \
  -v stardog-home:/var/opt/stardog \
  -v stardog-security:/stardog-security \
  -p 5820:5820 -p 5821:5821 \
  -e STARDOG_SERVER_JAVA_ARGS="-Djavax.net.ssl.keyStore=/stardog-security/my-keystore.jks -Djavax.net.ssl.keyStorePassword=changeit" \
  stardog/stardog --enable-ssl

3. Connect with HTTPS clients

Use the https:// scheme and the exposed HTTPS port when invoking Stardog tools:

docker exec -it my-stardog /opt/stardog/bin/stardog-admin --server https://localhost:5821 server status

If you are using a self-signed certificate or a private Certificate Authority, configure the client-side truststore as described in Step 3 of Encryption in Transit. If you don’t do this, the client will not trust the server certificate, and you’ll see an error like this:

PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

4. Example Docker Compose service

The same configuration works with Docker Compose. The snippet below exposes both HTTP and HTTPS, mounts a named volume, injects JVM arguments for the keystore, and turns on SSL:

services:
  stardog:
    image: stardog/stardog
    container_name: stardog-ssl
    ports:
      - "5820:5820"
      - "5821:5821"
    volumes:
      - stardog-home:/var/opt/stardog
      - stardog-security:/stardog-security
    environment:
      STARDOG_SERVER_JAVA_ARGS: "-Djavax.net.ssl.keyStore=/stardog-security/my-keystore.jks -Djavax.net.ssl.keyStorePassword=changeit"
      STARDOG_JAVA_ARGS: "-Djavax.net.ssl.trustStore=/stardog-security/my-truststore.jks -Djavax.net.ssl.trustStorePassword=changeit"
    command: ["--enable-ssl"]

volumes:
  stardog-home:
    external: true
  stardog-security:
    external: true

Make sure the stardog-home volume contains the license and stardog.properties, and that the stardog-security volume (or bind mount) contains the keystore and optional truststore before running docker compose up.

Next steps

Confirm the server is listening on HTTPS in the container logs (docker logs my-stardog).
Configure any remote clients or integrations to trust the certificate chain you installed on the server.

Overview
Before you begin
1. Stage TLS assets outside STARDOG_HOME
2. Start the container with SSL enabled
3. Connect with HTTPS clients
4. Example Docker Compose service
Next steps