Hello All!

I've been getting few questions about how I got my Portal 4.2 running into a pure CentOS 7.0 Linux AMI instance, without using the provided OVA. I often respond back to those questions by sending a cheat sheet I put together but they are notes that not everybody can understand.   Because of that, I decided to write down some step-by-steps that can help you to get your own Portal 4.2 instance.

Let's go through some things you're going to need before:

• A CentOS 7.0 x64 AMI with enough memory. The Portal documentation says that 32GB+ of memory is required. I've heard it is possible to run with less memory, but I haven't tried myself. If you did, please share a comment/feedback below;
• Go to this link and download the online (or offline - I will be using the online in this tutorial) version of the Portal 4.2.0.2;

If you do not have your CentOS image or need some help on getting one, just follow these steps to get your AMI. If you already have it, just skip to the next topic:

Create your CentOS 7 x64 AMI

Step 1: Choose your AMI:

Step 2: Instance Type

Step 3: Configure Instance Details 

Usually, I keep the default and just click on Next

Step 4: Add Storage

Here I change the Root volume from 8 to 20 and add a new EBS volume that it is going to be used by Docker and to install anything you want later.

Step 6: Configure Security Group

You can create a new Security-Group to be used whenever you have a Portal. Those are the ports I'm using:

Review and launch your instance now. Once you have it running, then you're going to need to get its public IP address in order to create some local DNS names for your new portal:

You got yourself an instance! Let's get started with the Portal installation now!

Adding the DNS entries / hosts file

Before we even access your new server, let's add the DNS entries into your local hosts file. If you want to use a real DNS server, that's fine and you can even use a *.domain pointing directly to your AMI's public address. I have a domain of my own and have been using CloudFlare as my DNS server, but if you don't want to mess with DNS server, you can just use your hosts file and add the following entries:

If you want to copy it here you go:

<YOUR AMI PUBLIC IP/DNS> admin-ssg.apicarocks.lab admin.apicarocks.lab admin-ssg.apicarocks.lab analytics.apicarocks.lab broker.apicarocks.lab enroll.apicarocks.lab sso.apicarocks.lab sync.apicarocks.lab

Preparing your server for the Portal

Obtaining root shell

In order to deploy the Portal 4.2, you are going to need to tweak your new Linux CentOS 4.2 server to accomplish all the requirements. Log in into your new Linux server and get the root shell as follows:

[centos@ip-172-31-44-19 ~]$
[centos@ip-172-31-44-19 ~]$ sudo su -
[root@ip-172-31-44-19 ~]#
[root@ip-172-31-44-19 ~]#

Updating your CentOS

Update your CentOS by running the following command. This might take a little while to finish:

[root@ip-172-31-44-19 ~]# yum update -y

Optional: Docker installation

You can either install Docker manually or let the config.sh portal script do it for you when you run it later. This is how you do it manually if you want to:

[root@ip-172-31-44-19 ~]# yum install -y yum-utils \
  device-mapper-persistent-data \
  lvm2

[root@ip-172-31-44-19 ~]# yum-config-manager \
    --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo

[root@ip-172-31-44-19 ~]# yum install docker-ce -y

[root@ip-172-31-44-19 ~]# systemctl start docker

[root@ip-172-31-44-19 ~]# chkconfig docker on

After running all the above commands, run docker info to see if your docker is running fine:

Time synchronization (NTP)

After installing the Docker, let's install the NTP and make sure both the Portal and any gateway you might want to enroll with this portal are using the same NTP server and have their time synchronized:

[root@ip-172-31-44-19 ~]# yum install ntp ntpdate ntp-doc -y

[root@ip-172-31-44-19 ~]# chkconfig ntpd on

[root@ip-172-31-44-19 ~]# ntpdate pool.ntp.org

Optional: changing your server's timezone

You can change your server timezone if you want. This is how you do it to set the Central Time:

[root@ip-172-31-44-19 ~]# mv /etc/localtime /etc/localtime.bak
[root@ip-172-31-44-19 ~]# sudo ln -s /usr/share/zoneinfo/America/Chicago /etc/localtime

Installing the FirewallD

The portal needs the FirewallD and this is how you install it:

[root@ip-172-31-44-19 ~]# yum install firewalld -y

Optional: Install DNS tools

You can install the DNS tools to test name resolution if you want. To do that just type this: 

[root@ip-172-31-44-19 ~]# yum install bind-utils -y

Portal Installation

Now the fun part! After getting our server ready to rock and roll, let's run the greatly improved Portal 4.2.X installation. Big shout out to the BU for putting together a really easy way to install the Portal. I have never been able to do 2 installations on the same day before  

Copying the installation to your server

You need to put the Portal 4.2 online downloaded installation into your Linux server. I like to use CyberDuck to do the SCP, but you can use your Terminal too. That's how you configure Cyberduck to use an SSH private key:

Copy the online portal installation file to your Linux server and (important) your portal license file too:

Extract the installation file

Now go back to your SSH session, still logged as root, to get started with the configuration and installation process. Execute the following commands to extract the copied portal installation into /opt folder. You can use whatever folder you want:

[root@ip-172-31-44-19 centos]# cd /home/centos/
[root@ip-172-31-44-19 centos]# cp apim-portal-4.2.0.2-final.tar.gz /opt/
[root@ip-172-31-44-19 centos]# cd /opt/
[root@ip-172-31-44-19 opt]# tar -xvzf apim-portal-4.2.0.2-final.tar.gz

Run the config.sh script

You can now delete the installation file once you have it extracted into your /opt/apim-portal-4.2.0.2-final folder. The first thing you need to do is to run the config.sh file. You will be also asked for some information about your portal installation. Be ready to answer the following questions:

Run the following commands to configure your portal:

[root@ip-172-31-44-19 apim-portal-4.2.0.2-final]# ./config.sh

APIM Portal configuration

Tenant ID (PORTAL_TENANT_ID) [apim]: admin
Portal subdomain (PORTAL_SUBDOMAIN) [example.com]: apicarocks.lab
Path to license file (PORTAL_LICENSE_FILENAME) []: /opt/apim-portal-4.2.0.2-final/license.xml
Enroll notification email address (PORTAL_ENROLL_NOTIFICATION_EMAIL) [noreply@mail.example.com]: noreply@apicarocks.lab
Analytics enabled (PORTAL_ENABLE_ANALYTICS) [y]: y

                  PORTAL_TENANT_ID:     admin
                  PORTAL_SUBDOMAIN:     apicarocks.lab
           PORTAL_LICENSE_FILENAME:     /opt/apim-portal-4.2.0.2-final/license.xml
  PORTAL_ENROLL_NOTIFICATION_EMAIL:     noreply@apicarocks.lab
           PORTAL_ENABLE_ANALYTICS:     y

Do you want to keep these settings? [Y/n]: y

Running the portal.sh script

Now that you have configured the portal, run the portal.sh script to start the portal deployment. This script will download all the required docker images and make all the configuration to run them properly. This can take between 10 to 20 minutes before everything is downloaded and started.

Checking the status

There are two ways to check. The first one is by running the script status.sh. It will check all the images and print whether they are running or not. The second way to check is by running the command docker service ls and check the REPLICAS. You want every REPLICA to be 1/1. Usually the portal_dispatcher is the last one to come up. This is my installation:

Accessing my new installed Portal

Now you can access your portal by opening the URL http://TENANTID.SUBDOMAIN, which in our case here would be https://admin.apicarocks.lab 

Remember that the default credentials are: admin / 7layereyal7

Enroll a tenant

Now you might want to enroll your own Gateway. In order to do that you first need to generate a tenant record and then posting the generated JSON to your TENANDID-ssg.SUBDOMAIN:9443. Make sure the gateway you want to enroll checks all the requisites. Below an example:

Copy the generated JSON

{
          "adminEmail": "admin@apicarocks.lab",
          "auditLogLevel": "TRACE",
          "multiclusterEnabled": true,
          "noReplyEmail":"noreply@apicarocks.lab",
          "performanceLogLevel": "ERROR",
          "portalLogLevel": "ERROR",
          "portalName": "My API Portal",
          "subdomain": "apicarocks.lab",
          "tenantId": "portal",
          "tenantType": "ON-PREM",
          "termOfUse": "Eula"
}

Now you can use cURL or any other REST client you want to do a POST and create the tenant record on the portal. I'm using Paw to do that. Make sure you copy the /opt/apim-portal-4.2.0.2-final/certs/apim.pem content or the mutual SSL will not work and the request will thus fail.

I hope this tutorial can help you out!