Deployment using Quadlets

This article describes how to install Smart ID Certificate Manager (CM) server components using quadlets.

Deployment directory

When deploying using quadlets the name of the directory in which the distributable deployment files are located will be dictated by the user running the container. It will map to the following directory:

$HOME/.config/containers/systemd/

Initialize the CM deployment

Before continuing with the CM deployment on quadlets, follow the steps for the corresponding database from one of the following pages:

• MS SQL Server/Azure SQL

• Oracle database

• PostgreSQL

• MySQL

• MariaDB

To handle CM on Podman in a production system, it is recommended to create quadlets for each container. Example quadlets can be found in the quadlets directory inside the distributable cm directory.

For rootless deployment, the .container, .volume and .network files from the quadlets directory need to be copied to the following location, assuming that the current user is the operator for the container deployment:

$HOME/.config/containers/systemd

If the directory does not exist it can be created.

The license directory containing the CM license files must also be copied to the above directory.

Once the .container, .volume, .network and license files are in place they can be loaded into systemd using:

systemctl --user daemon-reload

This will create a systemd service for each container and volume and can be started up accordingly.

The deployment procedure for CM with quadlets is essentially the same as for podman-compose, with the exception that the containers are managed by using systemd. Volumes only need to be started once, but may be restarted if the volumes are removed for any reason.

Examples (for rootless deployment):

The container images should be pulled or loaded manually before starting any of the containers using systemd. Due to lack of TTY (a virtual text console) it might cause startup problems with the containers, the systemctl command will appear to time out due to halting and waiting for console user input. Pulling the images manually with "podman pull" is preferable, which will permit user input in case an option needs to be selected.

Add the CM database connection

To add the CMDB connection to the CM configuration, a JDBC connection must be added.

Add the folloing --cm-param flags to the /quadlets/cf-server.container Exec property to make the CF container start with a correctly configured JDBC connection:

Alternatively, add the JDBC connection manually to the cm.conf file in the following way.

The CF container needs to be started to initialize the volumes with the configuration files, this start of CF will fail because no JDBC connection is yet configured.

systemctl --user start cf-server

The cm.conf can then be configured with the JDBC connection at the following path:

$HOME/.local/share/containers/storage/volumes/systemd-cf-server-config/_data/

Then restart the CF container by running the below command again:

systemctl --user restart cf-server

Post-configuration

Accessing the CM containers using the CM clients

At this point the CF is ready to accept connections on the exposed CF container port, so it is now possible to connect using Administrator's Workbench and Registration Agent clients. These clients can be installed from the CM distributable zip package.

Configuring the Protocol Gateway container

At this point the deployment will have configuration, certificates, and other persistent data on volumes mounted in the CF containers. To make changes in any of the configuration files or just copy files, the volumes needs to be accessed either inside the containers or mounting the volumes elsewhere.

For example, to edit configuration in CM from inside the container:

podman exec -ti cf-server bash

This will start a new shell inside the cf-server container, which allows editing of the cm.conf, and other files. The base directory where the tools and configuration can be found is /opt/cm/server/. It is also possible to mount a named volume to the host in case the container cannot start properly for some reason. For more details please consult the podman documentation.

The volumes can also be reached from the local file system in most cases by viewing the container volume mount list using the below command:

podman inspect cf-server

Initializing the Protocol Gateway container

The Protocol Gateway container, here named pgw, is based on an Apache Tomcat version 10 image and contains a configuration for a minimal deployment. The Protocol Gateway servlets are deployed but none of them are started.

For HTTPS in Tomcat, there is a default PKCS#12 TLS server token file name and password in the server.xml, "protocol-gateway-tls.p12", but the token file is not included. It needs to be issued and then it can be uploaded to the Tomcat configuration directory, (or a different volume backed path configured in server.xml.)

To initialize the volumes from the Protocol Gateway image data, the pgw container should be started up, and once Tomcat has started, the container should be stopped again:

Configuring the Protocol Gateway container

The pgw container has two volumes by default:

The systemd_pgw-config-gw volume contains configuration related to PGW, this includes configuration of the different certificate issuance protocols that PGW supports.

The systemd-pgw-config-tomcat volume contains configuration related to Tomcat, this includes configuration of the different connectors that tomcat should listen on.

It should be configured in a stopped state, and in order to modify the configuration in these volumes one method is to access the container's file system from the Podman host. The volumes can be found in the following directories:

It is possible to edit the files from within the pgw container. However, this is not recommended due to the limit amount of utility tools available inside the container.

Enabling the pgw container health check

For the health check to pass successfully, the Ping servlet requires a valid virtual registration officer token from the previous step, and the ping servlet should also have a ping procedure configured in CM.

Once the token is configured and the ping procedure is available, the Ping servlet must be started by setting the "start=true" parameter in the ping.properties file in the systemd-pgw-config-gw volume.

Starting the pgw container

Once the configuration has been edited the pgw container can be started:

systemctl --user start pgw

This is the required minimum configuration for setting up the Protocol Gateway. Additional volumes for possible output directories or HSM/other libraries, additional configuration, or web applications may be added if so required.

Connecting to services running on the Podman host

While it is not recommended to do so, there might be situations where a connection from a container to the Podman container host machine is needed. As Podman uses the slirp4netns driver by default, there is no directly available routing configured to reach the Podman localhost/127.0.0.1 address. To achieve this, a special IP address 10.0.2.2 can be used to reach the Podman machine localhost, while adding the following configuration depending on the deployment type: