/
Deploying PO Box on a Linux VM

Deploying PO Box on a Linux VM

Overview

Zilla PO Box is a container that simplifies integration with on-prem applications by extending into customer environments and making outbound API calls to push user and account information to Zilla. The shell script is used to manage and deploy containers for PO Box using either Podman or Docker.

This article is designed as a playbook for completing prerequisite activities, configuring and deploying the PO Box container, and setting up a cron job to restart the container with the latest released image on a daily basis.

Option 1: Zilla Client ID and Secret-based Deployment (Recommended)

This option comes highly recommended.

Prerequisites

Machine Specs

  • 2vCPU

  • 4GB RAM

  • 25GB Disk

Libraries

PO Box Directory

  • User needs to create an empty pobox directory. This directory will be used as a volume mount for the POBox container.

    mkdir pobox

     

  • Print the absolute path of the pobox directory using below command. Keep the directory path handy. Example - /home/user/pobox

    pwd

Whitelist URLs

Customers may need to whitelist certain URLs to successfully deploy PO Box. This list includes but is not limited to:

Generate Client ID and Secret

To generate Client ID and Secret, see https://zilla.atlassian.net/wiki/spaces/ZILLA/pages/3651141644

Configuring and Deploying PO Box

  1. Download the tar file on the target VM. Use below curl command to download the tar file.

    curl -O https://zus-in-the-cloud-deployment.s3.us-east-1.amazonaws.com/prod/pobox-client-credentials/pobox-deployment.tar

  2. Run the command below to extract the pobox_deployment directory.

    tar -xvf pobox-deployment.tar

  1. Open the pobox-deployment directory. You will see the pobox_client_credentials.sh shell script file.

  2. Run the command below to deploy the PO Box container.

    bash pobox_client_credentials.sh

After running the pobox_client_credentials.sh script, you are prompted for the configuration inputs.

The script asks you to input:

  • CONTAINER_TOOL: This is the container tool used (either Podman or Docker).

  • TENANT_DOMAIN: This is the domain of your tenant. To find your tenant domain, click Settings navigation menu in Zilla and expand the Your Domains section. Your tenant domain is the first domain listed under that section.

  • ZILLA_URL: This is the host URL of the Zilla server based on your tenant. Zilla has different host URLs for different tenants, including:

  • VOLUME_MOUNT_DIRECTORY_PATH: This is the absolute path to the pobox directory outlined in the PO Box Directory section above.

  • ZILLA_CLIENT_ID: This is the Client ID generated during the prerequisite activities.

  • ZILLA_CLIENT_SECRET: This is the Client Secret generated during the prerequisite activities.

  1. The configuration is saved as pobox_environment_config to your script directory.

    path/where/you/have/extracted/script/ ├── pobox-environment-config

  1. Once the PO Box deployment is complete, run one of the two commands below based on whether Podman or Docker was used to validate that it was deployed correctly.
    For Podman installs, run the command below at the Linux $ prompt.

    podman ps


    For Docker installs, run the command below at the Linux $ prompt.

    docker ps


    The output will look similar to the below and and will show a running container with a name similar to 508384223771.dkr.ecr.us-east-1.amazonaws.com/zinc:latest.

    ubuntu@ip-172-26-13-73:~/pobox/pobox-deployment$ podman ps ID IMAGE  COMMAND  CREATED  STATUS  PORTS  NAMES 508384223771.dkr.ecr.us-east-1.amazonaws.com/zinc:latest node app/dist/src... 7 minutes ago Up 7 minutes ago zilla_pobox

Re-Configuring PO Box Deployment

If you need to update your configuration, run the command below.

./pobox_client_credentials.sh reconfigure

Scheduling a cron Job

The next step is to set the POBox deployment as a daily cron job, which is required to restart the container with the latest released image that will be pulled-down from the container registry at http://508384223771.dkr.ecr.us-east-1.amazonaws.com/.

Once the cron job has been set, the shell script pobox_client_credentials.sh will initialize the config variable and execute two tasks daily:

  • pull_image to pull the latest PO Box image

  • launch to run/restart the PO Box container

  1. Run the command below to open the crontab. If you are prompted to select a crontab editor, enter nano.

    crontab -e

  1. In the crontab editor, run the command below replacing the /absolute/directory/path/of/pobox-deployment directory path with correct value.
    In the example below, the script will be executed daily at 01:00 AM UTC.

    0 1 * * * cd /absolute/directory/path/of/pobox-deployment && bash pobox_client_credentials.sh

 

Option 2: Zilla_API_key-based Deployment (Not Recommended)

This option is not recommended.

Prerequisites

Machine Specs

  • 2vCPU

  • 4GB RAM

  • 25GB Disk

Libraries

PO Box Directory

  • User needs to create a PO Box directory based on the structure given below:

    pobox/ ├── pobox-config/ └── pobox-output/

  • The Zilla_API_Key file has been saved under the pobox-config directory for authenticating and managing deployments

    • To get the value for Zilla_API_Key via a secure credentials link, please reach out to the Zilla Customer Success Team

Whitelist URLs

Customers may need to whitelist certain URLs to successfully deploy PO Box. This list includes but is not limited to:

Configuring and Deploying PO Box

  1. Download the tar file on the target VM. Use below curl command to download the tar file.

    curl -O https://zus-in-the-cloud-deployment.s3.us-east-1.amazonaws.com/prod/pobox-zilla-api-key/pobox-deployment.tar

  2. Run the command below to extract the pobox_deployment directory.

    tar -xvf pobox-deployment.tar

  1. Open the pobox-deployment directory. You will see the pobox_zilla_api_key.sh, shell script file.

  2. Run the command below to deploy the PO Box container.

    bash pobox_zilla_api_key.sh

After running the pobox_zilla_api_key.sh script, you will be prompted for the configuration inputs.

Set the values for the variables listed below.

  1. The configuration will be saved as pobox_environment_config to your script directory.

    path/where/you/have/extracted/script/ ├── pobox-environment-config

  2. Once the PO Box deployment is complete, run one of the two commands below based on whether Podman or Docker was used to validate that it was deployed correctly.

    For Podman installs, run the command below at the Linux $ prompt.

    podman ps


    For Docker installs, run the command below at the Linux $ prompt.

    docker ps


    The output will look similar to the below and and will show a running container with a name similar to 508384223771.dkr.ecr.us-east-1.amazonaws.com/zinc:latest.

    ubuntu@ip-172-26-13-73:~/pobox/pobox-deployment$ podman ps ID IMAGE  COMMAND  CREATED  STATUS  PORTS  NAMES 508384223771.dkr.ecr.us-east-1.amazonaws.com/zinc:latest node app/dist/src... 7 minutes ago Up 7 minutes ago zilla_pobox

Re-Configuring PO Box Deployment

If you need to update your configuration, run the command below.

./pobox_zilla_api_key.sh reconfigure

Scheduling a cron Job

The next step is to set the PO Box deployment as a daily cron job, which is required to restart the container with the latest released image that will be pulled-down from the container registry at http://508384223771.dkr.ecr.us-east-1.amazonaws.com/.

Once the cron job has been set, the shell script pobox_zilla_api_key.sh will initialize the config variable and execute two tasks daily:

  • pull_image to pull the latest PO Box image

  • launch to run/restart the PO Box container

  1. Run the command below to open the crontab. If you are prompted to select a crontab editor, enter nano.

    crontab -e

  1. In the crontab editor, run the command below replacing the /absolute/directory/path/of/pobox-deployment directory path with correct value.
    In the example below, the script will be executed daily at 01:00 AM UTC.

    0 1 * * * cd /absolute/directory/path/of/pobox-deployment && bash pobox_zilla_api_key.sh

Troubleshooting

Access Denied Error for Zilla_API_Key

In order to run the PO Box container, the user inside the container needs to be able to access the Zilla_API_Key file. If the owner of the mounted directory is not the same as the container’s user, the container exits with an access denied error for the Zilla_API_Key file.

pobox/ ├── pobox-config/ ├──Zilla_API-Key └── pobox-output/

Docker Solution

When working with Docker the User-Namespace-Mapping is disabled by default. The UID-GID (user ID and group ID) of the user inside the container and the UID-GID of the owner of the PO Box directory on the host machine must be the same.

Rootless Podman Solution

When working with Rootless Podman the User-Namespace-Mapping is strictly enabled. The owner on the PO Box directory must be updated to the mapped user inside the container.

SELinux Flag Solution

  • Z: SELinux policies can restrict access based on labels, so the Z flag helps to apply the correct label automatically to prevent access denials or potential security risks.

  • U: The U flag ensures that when a volume is mounted between the host and a container, the user and group IDs (UIDs and GIDs) inside the container are properly mapped to the corresponding UIDs and GIDs on the host system.