Skip to content

Permanent Storage

The sedex Client Docker container must be able to store data permanently. For this purpose, two external storage folders (or volumes) must be mounted (attached) to the container. On this page you find information about the content of the two external storage folders, as well as how permanent storage can be mounted using Docker.

Overview of the sedex Client as a Docker Container

Docker Containers are disposable - External Storage has to be mounted

Docker containers are considered disposable. This means that any data stored inside a container is deleted when the container is deleted. However, sedex needs data that survive the (possibly short) life cycle of a container and must be persisted permanently. For this purpose, two external permanent data storage folders must be connected to the sedex Client container using the --mount option.

Permanent storage "sedex-interface"

The first permanent storage folder that has to be mounted into the container from the outside is named "sedex-interface". This external permanent storage folder provides the file system-based interface for sending and receiving sedex messages. Accordingly, the business applications that need to receive or send sedex messages must also have access to this storage.

In the "sedex-interface" permanent storage contains the following sub-folders:

  • inbox/
    Messages that have been received for your participant are found in this folder. That is, your business application receives a sedex message by reading the envelope and the payload files from this folder.
  • outbox/
    Messages ready to be sent have to be placed in this folder. That is, your business application sends a sedex message by writing the payload and the envelope files into this folder.
  • processed/
    The sedex Client moves all outgoing messages that have been processed into this folder. This mainly includes sent messages, but also messages which could not be sent for various reasons (e.g. missing authorization, network problems, etc.).
  • receipts/
    The sedex Client generates a receipt containing the status of every sent message. Your business application gets the status of its sent messages by reading these receipt files.
  • working/
    While processing sedex messages, the sedex Client will store temporary data in this folder. This folder is managed by the sedex Client. Do not delete or modify files in this folder.

Permanent storage "sedex-data"

The second permanent storage folder that has to be mounted into the container from the outside is named "sedex-data". This external storage folder contains important sedex Client data (e.g. configuration, credentials, log files, etc.) as well as internal status data that must be persisted. Access to this data by other users and applications must be restricted as far as possible and strictly managed.

In the "sedex-data" permanent storage contains the following subfolders:

  • conf/
    Configuration data of the sedex Client, including the participant certificate and private key. Keep them safe and secure!
  • internal/
    Technical data required and used by the sedex Client itself.
  • logs/
    Log files of the sedex Client with events and errors, primarily of interest to your operations personnel.
  • messaging-state/
    In this subfolder the sedex Client maintains an internal database for tracking all messages it receives or sends. This database must be stored permanently, otherwise sedex messages or receipts could be lost.
  • monitoring/
    A simple text page with state information and metrics for your operations monitoring.

Mounting permanent storage with Docker

For mounting permanent storage into a container from the outside, Docker offers two main concepts: bind mounts and volumes.

Both bind mounts and volumes can be used with the sedex Client to mount the permanent storage. You can choose the variant that fits better into your specific operating environment.

Bind mounts and volumes are briefly introduced below. For more details, please refer to the Docker documentation.

Using bind mounts

Bind mounts are based on normal folders in the local file system of the host running the Docker container. Bind mounts are an older Docker concept and are typically used for test installations and smaller production installations.

The following excerpt from a Docker command shows the relevant options to mount the permanent storage into the sedex Client container using two bind mounts. The two parameters </ABSOLUTE_PATH_TO/SEDEX_INTERFACE> and </ABSOLUTE_PATH_TO/SEDEX_DATA> must be replaced by the absolute paths of the two permanent storage folders you have created before:

  [...]
  --mount type=bind,source=</ABSOLUTE_PATH_TO/SEDEX_INTERFACE>,destination=/sedex-interface/ \
  --mount type=bind,source=</ABSOLUTE_PATH_TO/SEDEX_DATA>,destination=/sedex-data/ \
  [...]

  [...]
  --mount type=bind,source=/home/app-data/sedex-interface-1-1234-1,destination=/sedex-interface/ \
  --mount type=bind,source=/home/app-data/sedex-data-1-1234-1,destination=/sedex-data/ \
  [...]

The destination path is given

While the source folder on the host can have any name, it must always be mounted to the same given destination path in the container: /sedex-interface and /sedex-data respectively.

Using volumes

Volumes are storage folders managed by the container platform, possibly mounted from a server over a network. Volumes are a more recent Docker concept and are typically used in larger (fail-safe) environments because they are not necessarily bound to a specific host.

The following excerpt from a Docker command shows the relevant options to mount the permanent storage into the sedex Client container using two volumes. The two parameters <SEDEX_INTERFACE_VOLUME> and <SEDEX_DATA_VOLUME> must be replaced by the names of the two permanent storage volumes you have created on your container platform before:

  [...]
  --mount type=volume,source=<SEDEX_INTERFACE_VOLUME>,destination=/sedex-interface/ \
  --mount type=volume,source=<SEDEX_DATA_VOLUME>,destination=/sedex-data/ \
  [...]

  [...]
  --mount type=volume,source=sedex-interface-1-1234-1,destination=/sedex-interface/ \
  --mount type=volume,source=sedex-data-1-1234-1,destination=/sedex-data/ \
  [...]

The destination path is given

While the source volume can have any name, it must always be mounted to the same given destination path in the container: /sedex-interface and /sedex-data respectively.

Notes on permanent storage

Ensure security and backups for your permanent storage

It is of utmost importance that the data security and safety of all permanent storage is guaranteed at all times. Your operations staff must ensure that only authorized users and applications have access to the relevant portion of data and that backups of the data are made regularly.

General information about permanent storage

  • Most of the the command line examples for Docker in this documentation primarily show the use of bind mounts. Experienced container administrators can easily adapt these examples to volumes.
  • In our examples the external folders for the permanent data storage are also named "sedex-interface" and "sedex-data" - the same as the folders have to be named inside the container. Of course you can name these external folders (or volumes) differently. For example, you could append the sedex ID to the name to indicate to which sedex participant the interface and data folders belong. If you choose different names, you have to adapt the source-part of a command to your actual folder (or volume) name.
  • Other container platforms (Kubernetes, OpenShift, etc.) provide similar and more specific concepts for persisted volumes. Please refer to the corresponding documentation for your platform.