Nexus Documentation
Nexus Documentation
Breadcrumbs

Deploy Digital Access using Podman

This article is new for Digital Access 6.11.

This article describes how to deploy the Smart ID Digital Access component using Podman.

You can also deploy Smart ID complete package using docker compose for which you can refer to Deploy Smart ID.

Prerequisites

The following is needed:

  • Linux machine with podman version 4.9.3 or later installed

  • Non-root user account to run Digital Access services

  • Non-root users cannot bind to low-numbered ports (below 1024). Therefore, configure services to use higher port numbers.
    To expose services on standard ports, set up a load-balancer or reverse proxy to forward traffic from low to high ports.

  • Software Components: Any of the PostgreSQL, MySQL, Sql-server, or Oracle database

  • Configuration files: DA-<version>-podman.tgz

  • System Requirements: 8cpu with 32GB RAM and 100 GB physical space is recommended

Preparations

  • Download the DA-<version>-podman.tgz file on system from the support portal. In following steps, we will use DA-6.11.0-podman.tgz for example and must be replaced by the version you plan to deploy.

  • It is always recommended to take backup/snapshot before starting setup.

  • Podman containers associated with a user session will stop when the user logs out of the podman host machine.
    To prevent containers from shutting down after logout, enable lingering for the user with loginctl:

Bash
loginctl enable-linger <DAUSER>

  • This example uses xmlstarlet, using this tool is optional.

Step-by-step instruction

This section provides a sample step-by-step deployment procedure for running Digital Access on a single node using Podman. The instructions and configuration shown here are intended as a reference example to help you understand the overall process and requirements. For production or multi-node environments, you will need to adapt and extend these steps to fit your own infrastructure, network, and security needs. Review each step carefully and modify the deployment as appropriate for your use case.

Extract the setup files

  1. Copy DA-6.11.0-podman.tgz to your working directory.

  2. Extract the file using tar command:

    Bash
    tar -xf DA-6.11.0-podman.tgz

  3. Refer README.md inside the extracted folder for version specific details.

Create Digital Access home directory

To perform these steps root privilege is required.

  1. Create base directories for rootless user, replace the <username> in the command below to the rootless user for running the digital access

    Bash
    sudo mkdir -p /opt/nexus
sudo chown -R <username>:<username> /opt/nexus

  2. Switch to the rootless user

  3. Create Digital Access directories and digital access volume mounts

    Bash
    mkdir -p /opt/nexus/config/administration-service/config
mkdir -p /opt/nexus/config/authentication-service/config
mkdir -p /opt/nexus/config/distribution-service/config
mkdir -p /opt/nexus/config/policy-service/config
mkdir -p /opt/nexus/config/access-point/config

  4. Grant pwuser access to the volumes

    Bash
    podman unshare chown -R 1003:1003 /opt/nexus/config

  5. Ensure podman systemd path is present, for more information on available paths see podman documentation FILE PATHS. Following in this document we will base the example using ~/.config/containers/systemd/

    Bash
    mkdir -p ~/.config/containers/systemd/

Configure Podman network

  1. Open digital-access.network in a text editor

  2. If it is required to bind to any specific NIC for communication -

    1. Uncomment the line

      PodmanArgs=--network-interfaceIf=<device>

    2. and replace place holder <device> with the chosen interface

  3. In case it is needed to change digital-access container IP address then update Subnet and Gateway to match the container IPs

  4. Save the changes

Services can be reached only by host machine IP address. And container IPs are for digital access services to communicate with each other on the same machine and subnet.

Configure Digital Access service systemd units

Configure the quadlet unit files to match your deployment requirements. Please refer to podman quadlet documentation for
details on the unit file options. Please make sure that the corresponding version documentation is used. For podman v4.9.3 refer to https://docs.podman.io/en/v4.9.3/markdown/podman-systemd.unit.5.html

  1. Repeat following for each service container

  2. Open the service ‘.container’ file

  3. Go to section named [Container]

  4. Change the Digital Access container IPs

    1. Find the line starting with ‘IP=’ and change it to the desired IP address for the service

    2. Find the lines starting with 'PodmanArgs=--add-host=' and update all IP address to match the deployment.

For the services on different machine use machine’s IP address

Deploy podman systemd units

  1. Copy .container and .network files from the directory to the following location, assuming that the current user is the rootless user running the services

    cp digital-access.network ~/.config/containers/systemd/
cp access-point.container ~/.config/containers/systemd/
cp administration-service.container ~/.config/containers/systemd/
cp authentication-service.container ~/.config/containers/systemd/
cp distribution-service.container ~/.config/containers/systemd/
cp policy-service.container ~/.config/containers/systemd/

  2. Verify systemd units' correctness, make sure no errors reported

    /usr/libexec/podman/quadlet -dryrun -user

There may be some error messages related to missing folders or files. These can be ignored if they are related to files or folders that are not part of Digital Access configuration. For further information refer to https://github.com/containers/podman/issues/23620.

  1. Refresh systemd units

    systemctl --user daemon-reload

  2. List the services and make sure all the desired services are present

    systemctl --user  list-unit-files  --no-pager | grep generated

  3. Start services to populate initial configuration

    systemctl --user start administration-service
systemctl --user start policy-service
systemctl --user start authentication-service
systemctl --user start access-point
systemctl --user start distribution-service

  4. Check the status of the services

    systemctl --user --no-pager -l status access-point
systemctl --user --no-pager -l status administration-service
systemctl --user --no-pager -l status authentication-service
systemctl --user --no-pager -l status distribution-service
systemctl --user --no-pager -l status policy-service

  5. Stop the services and proceed with service configuration

    systemctl --user stop administration-service
systemctl --user stop policy-service
systemctl --user stop authentication-service
systemctl --user stop access-point
systemctl --user stop distribution-service

Configure Digital Access services

This configuration is needed to make the services aware of administration service so they can connect receive the configuration updates. It is recommended to use xmlstarlet to edit the configuration but can also be done using any text editor.

  • Edit LocalConfiguration.xml file in each service configuration at /opt/nexus/config/<service-name>/config

    1. Find the element with

      <attribute name="mHost" value="admin" type="string"/>

    2. set value="admin.cluster.local"

      <attribute name="mHost" value="admin.cluster.local" type="string"/>

  • Or use following command to edit configuration files with xmlstarlet

    Bash
    cd /opt/nexus/config
ADMIN_SERVICE_HOST=admin.cluster.local
podman unshare xmlstarlet ed -L -u '//object[attribute[@name="mType" and @value="5"]]/attribute[@name="mHost"]/@value' -v $ADMIN_SERVICE_HOST access-point/config/LocalConfiguration.xml
podman unshare xmlstarlet ed -L -u '//object[attribute[@name="mType" and @value="5"]]/attribute[@name="mHost"]/@value' -v $ADMIN_SERVICE_HOST policy-service/config/LocalConfiguration.xml
podman unshare xmlstarlet ed -L -u '//object[attribute[@name="mType" and @value="5"]]/attribute[@name="mHost"]/@value' -v $ADMIN_SERVICE_HOST authentication-service/config/LocalConfiguration.xml
podman unshare xmlstarlet ed -L -u '//object[attribute[@name="mType" and @value="5"]]/attribute[@name="mHost"]/@value' -v $ADMIN_SERVICE_HOST distribution-service/config/LocalConfiguration.xml

Start Digital Access

After making changes to the configuration files, start the services to apply the changes.

  1. Start all the services again using the commands mentioned in previous section

  2. Check the status of the services

Configure services through web UI

Configure service to listen on all interfaces

After logging into the administration console, configure the services to listen on all interfaces.

Please remember to save the changes after each step.

  1. Goto 'Manage System' > 'Access Points' and set all services under 'Registered Access Points' to listen on all interfaces.

  2. Goto 'Manage System' > 'Policy Services' and set all services under 'Registered Policy Services' to listen on all interfaces.

  3. Goto 'Manage System' > 'Distribution Services' and set all services under 'Registered Distribution Services' to listen on all interfaces.

  4. Goto 'Manage System' > 'Authentication Services' and set all services under 'Registered Authentication Services' to listen on all interfaces.

  5. Goto 'Manage System' > 'Administration Services' and

  • set Internal Host to admin.cluster.local (matching to the HostName in administration-service.container quadlet unit)

  • set listen on all interfaces.

Apply changes from Administration Service

After making changes to the service configuration, click on Publish to apply the changes.

Offline setup

Offline setups consist of two steps:

Step 1: Save Container Images

For the first step you need a system with network connectivity. Download container images on the system.

  1. Make sure podman is installed.

  2. Download the images using the command podman pull. 

    podman pull nexusimages.azurecr.io/smartid-digitalaccess/administration-service:6.10.0-394020
podman pull nexusimages.azurecr.io/smartid-digitalaccess/policy-service:6.10.0-394020
podman pull nexusimages.azurecr.io/smartid-digitalaccess/authentication-service:6.10.0-394020
podman pull nexusimages.azurecr.io/smartid-digitalaccess/distribution-service:6.10.0-394020
podman pull nexusimages.azurecr.io/smartid-digitalaccess/access-point:6.10.0-394020

  3. To verify that all images are downloaded, run this command:

    podman image ls

  4. Save all images in tar.gz files. Run these commands: 

    podman save nexusimages.azurecr.io/smartid-digitalaccess/administration-service:6.10.0-394020 > admin.tar
podman save nexusimages.azurecr.io/smartid-digitalaccess/authentication-service:6.10.0-394020 > authentication.tar
podman save nexusimages.azurecr.io/smartid-digitalaccess/distribution-service:6.10.0-394020 > distribution.tar
podman save nexusimages.azurecr.io/smartid-digitalaccess/policy-service:6.10.0-394020 > policy.tar
podman save nexusimages.azurecr.io/smartid-digitalaccess/access-point:6.10.0-394020 > accesspoint.tar

gzip *.tar

  5. Copy all the tar.gz files onto the system where you want to setup Digital Access.

Step 2: Load Container Images

On the system where the Digital Access setup will be done:

  1.  Go to the folder where all the tar.gz files are copied.

  2. Load the images to a local container image cache using the command:

    Bash
    find -name *.tar.gz | xargs --no-run-if-empty -L 1 podman load -i

  3. To verify that all of the required images are loaded, run this command:

    podman image ls

  4. Run the installation process, and follow the steps mentioned above.

Additional information

Useful links