External database

Instead of the internal database of the opcrouter/runtime image, an external database (MongoDB) can also be connected to store project data and transmitted values. For this purpose, it is recommended to use the opcrouter/service image, as it does not have an internal database and is therefore compatible with 32-bit systems.

Connecting an external database to the opcrouter/runtime image is possible, but it does not deactivate or automatically delete the internal database. The internal database continues to run within the container.

When is Using an External Database Recommended?

Using an external database is particularly recommended when deploying the OPC Router through orchestration software like Kubernetes or Docker Compose. This enables easy distribution of applications across multiple systems. For example, an opcrouter/service container can run on a 32-bit ARM system, while an opcrouter/runtime container can only run on 64-bit systems due to the integrated database.

note

MongoDB is not compatible with 32-bit systems. Therefore, an external database must also be operated on a 64-bit system.

Setting Up an External Database

For this example, we will create a MongoDB Docker container as an external database. We will use the official mongo image with the tag 6-jammy, which provides the latest MongoDB 6 version. Other MongoDB instances can also be integrated.

MongoDB is not compatible with 32-bit systems. Therefore, an external database must also be operated on a 64-bit system. Setting Up an External Database For this example, we will create a MongoDB Docker container as an external database. We will use the official mongo image with the tag 6-jammy, which provides the latest MongoDB 6 version. Other MongoDB instances can also be integrated.

warning

This MongoDB deployment does not use authentication and does not persist data on named volumes. Therefore, it is suitable for demonstration purposes only and not for production use.

Please note that MongoDB must be configured as a Replica Set for use with OPC Router 5. This is ensured here by the --replSet rs0 argument. An existing MongoDB database can also be configured as a Replica Set using the rs.initiate() command.

To make MongoDB accessible from our OPC Router container, we ensure that the externaldb container is in the same bridge network. Although this should not be necessary in most Docker environments, it is done here for demonstration purposes. Additionally, no external port needs to be opened since we only need to access the database within the network.

We determine the IP address of the created externaldb container within the bridge network so that we can use it in our connection string:

docker container inspect
-f "{{range .NetworkSettings.Networks}}{{println .IPAddress}}{{end}}"
externaldb

Here, a formatting option is used in the -f argument to display only the necessary IP address. The command should return a single IP address; for example, we will use the IP address 172.17.0.2 for further steps. This results in the connection string mongodb://172.17.0.2:27017.

Creating OPC Router Containers with External Database Connection

Now, you can easily create a container from the opcrouter/service:latest image. Here, we also explicitly specify the network as bridge, and we expose port 8080 externally so that we can access the OPC Router at localhost:8080 upon successful deployment.

warning

The connection string passed to the OR_DATABASE_CONNECTION_STRING environment variable needs to be adjusted to your connection string.

docker run -d 
	--name service 
	--network bridge 
	-e OR_I_ACCEPT_EULA=true 
	-e OR_DISABLE_AUTH=true 
	-e OR_DATABASE_CONNECTION_STRING="mongodb://172.17.0.2:27017" 
	-p 8080:8080 
	opcrouter/service:latest 

note

By running the command and setting the OR_I_ACCEPT_EULA environment variable to true, you agree to the End User License Agreement.

For demonstration purposes, the authentication of the web management is disabled using the OR_DISABLE_AUTH environment variable, although this is not recommended.

The crucial aspect here is setting the connection string to the OR_DATABASE_CONNECTION_STRING environment variable. The connection string can also include the username and password if needed to access authenticated databases. Further information about connection strings can be found in the official MongoDB documentation.

warning

For the MongoDB connection to work, MongoDB must be configured as a Replica Set. Otherwise, the OPC Router's connection attempt will fail and log a MongoDB.Driver.MongoCommandException. You can learn more about Replica Sets in the official MongoDB documentation.