External database
Instead of the internal database of the opcrouter/runtime image, an external database (MongoDB) can also be connected to store the project data and the transferred values. The use of the opcrouter/service image is recommended for this purpose, as it does not have an internal database and can therefore also run on 32-bit systems. It is also possible to connect an external database to the opcrouter/runtime image, but connecting an external database does not deactivate or automatically delete the internal database, which continues to run in the container.
When is it advisable to use an external database?
The use of an external database is particularly recommended if the OPC router is deployed via orchestration software such as Kubernetes or Docker Compose. This allows for easy distribution of applications across multiple systems, so that, 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.
MongoDB is not compatible with 32-bit systems. Therefore, an external database must also be run on a 64-bit system.
Setting up an external database
For this example, we will create a MongoDB Docker container as an external database. To do this, we will use the official mongo image with the tag 6-jammy. This provides the current 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 run on a 64-bit system.
Set up external database
For this example, we will create a MongoDB Docker container as an external database. To do this, we use the official mongo image with the tag 6-jammy. This provides the current MongoDB 6 version. Other MongoDB instances can also be integrated.
This MongoDB deployment does not use authentication and does not persist data on named volumes, and is therefore only suitable for demonstration purposes and not for productive use.
It should be noted that MongoDB must be configured as a replica set for use with OPC Router 5. This is ensured here by the argument --replSet rs0. An existing MongoDB database can also be configured as a replica set using the rs.initiate() command.
To ensure that MongoDB is accessible from our OPC Router container, we also make sure that the externaldb container is located in the same bridge network, explicitly specifying the standard Docker bridge network bridge. This should not be necessary in most Docker environments and is only done here for demonstration purposes. Furthermore, no port needs to be opened to the outside world, as we only need to address the database within the network.
We determine the IP of the created externaldb container within the bridge network so that we can use it in our connection string:
// Some codedocker container inspect \
-f "{{range .NetworkSettings.Networks}}{{println .IPAddress}}{{end}}" \
externaldb
Here, a formatting option is used in the -f argument to display only the required IP address. The command should return a single IP address. Here, we use the IP address 172.17.0.2 as an example for the rest of the procedure. This results in the connection string mongodb://172.17.0.2:27017.
Create an OPC Router container with connection to external database
Now you can simply create a container from the image opcrouter/service:latest. Here, too, we explicitly specify bridge as the network and also open port 8080 to the outside so that we can access the OPC Router at localhost:8080 after successful deployment.
The connection string that is passed to the environment variable OR_DATABASE_CONNECTION_STRING must still be adapted 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
By executing this command, you agree to the End User License Agreement by setting the environment variable OR_I_ACCEPT_EULA to true.
For demonstration purposes, Web Management authentication is disabled here by the environment variable OR_DISABLE_AUTH, but this is not recommended.
The particularly important aspect here is setting the connection string to the environment variable OR_DATABASE_CONNECTION_STRING. The connection string can also contain the user name and password if necessary to access databases with authentication. Further information on the connection string can be found in the official MongoDB documentation.
For the connection to MongoDB 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.