SSL encryption in a Neo4j Docker container

Neo4j on Docker supports Neo4j’s native SSL Framework for setting up secure Bolt and HTTPS communications. To configure these settings in Docker, you either set them in the neo4j.conf file, or pass them to Docker as Docker environment variables.

Set up your certificate folders

Verify that you have SSL public certificate(s) and private key(s).

The certificates must be issued by a trusted certificate authority (CA), such as https://www.openssl.org/ or https://letsencrypt.org/.

The default file names are private.key and public.crt.
Create a local folder to store your certificates.

For example, $HOME/neo4j/certificates. This folder will be later mounted to /ssl of your container.
In your local folder (e.g. $HOME/neo4j/certificates), create a folder for the SSL policy of each of your communication channels that you want to secure. There, you will store your certificates and private keys.

It is recommended to use different certificates for the different communication channels (bolt and https).

In the following examples, <scope> substitutes the name of the communication channel.
```
$ mkdir $HOME/neo4j/certificates/<scope>
```
In each of your <scope> folders, create a /trusted and a /revoked folder for the trusted and revoked certificates.
```
$ mkdir $HOME/neo4j/certificates/<scope>/trusted
$ mkdir $HOME/neo4j/certificates/<scope>/revoked
```

Finally, you add your certificates to the respective <scope> folder.

The <scope> folder(s) should now show the following listings:

$ ls $HOME/neo4j/certificates/<scope>
-r-------- ... private.key
-rw-r--r-- ... public.crt
drwxr-xr-x ... revoked
drwxr-xr-x ... trusted

Configure SSL via neo4j.conf

In the neo4j.conf file, configure the following settings for the policies that you want to use:

# Https SSL configuration
server.https.enabled=true
dbms.ssl.policy.https.enabled=true
dbms.ssl.policy.https.base_directory=certificates/https
dbms.ssl.policy.https.private_key=private.key
dbms.ssl.policy.https.public_certificate=public.crt


# Bolt SSL configuration
dbms.ssl.policy.bolt.enabled=true
dbms.ssl.policy.bolt.base_directory=certificates/bolt
dbms.ssl.policy.bolt.private_key=private.key
dbms.ssl.policy.bolt.public_certificate=public.crt

For more information on configuring SSL policies, see Configuration.

For more information on configuring connectors, see Configuration options.

Example 1. A docker run command that launches a container with SSL policy enabled via neo4j.conf.

docker run \
    --publish=7473:7473 \ (1)
    --publish=7687:7687 \
    --user="$(id -u):$(id -g)" \ (2)
    --volume=$HOME/neo4j/certificates:/ssl \ (3)
    --volume=$HOME/neo4j/conf:/conf \ (4)
    neo4j:5.19.0

1	The port to access the HTTPS endpoint.
2	Docker will be started as the current user (assuming the current user has read access to the certificates).
3	The volume that contains the SSL policies that you want to set up Neo4j to use.
4	The volume that contains the neo4j.conf file. In this example, the neo4j.conf is in the `$HOME/neo4j/conf` folder of the host.

Configure SSL via Docker environment variables

As an alternative to configuring SSL via the neo4j.conf file, you can set an SSL policy by passing its configuration values to the Neo4j Docker container as environment variables. For more information on how to convert the Neo4j settings to the form accepted by Docker, see Environment variables:

Example 2. A docker run command that launches a container with SSL policy enabled via Docker environment variables.

docker run \
    --publish=7473:7473 \ (1)
    --publish=7687:7687 \
    --user="$(id -u):$(id -g)" \ (2)
    --volume=$HOME/neo4j/certificates:/ssl \ (3)
    --env NEO4J_dbms_connector_https_enabled=true \ (4)
    --env NEO4J_dbms_ssl_policy_https_enabled=true \ (5)
    --env NEO4J_dbms_ssl_policy_https_base__directory=/ssl/https \ (6)
    neo4j:5.19.0

1	The port to access the HTTPS endpoint.
2	Docker will be started as the current user (assuming the current user has read access to the certificates).
3	The volume that contains the SSL policies that you want to set up Neo4j to use.
4	The HTTPS connector is disabled by default. Therefore, you must set `server.https.enabled` to `true`, for Neo4j to be able to listen for incoming connections on the HTTPS port. However, for the Bolt SSL policy, you do not have to pass this parameter as the Bolt connector is enabled by default.
5	The SSL policy that you want to set up for Neo4j.
6	The base directory under which SSL certificates and keys are searched for. Note that the value is the docker volume folder /ssl/https and not the /certificate/https folder of the host.