Layer7 API Management

Running the API Portal into a pure Linux CentOS 7.0 AMI 

02-14-2018 03:58 PM

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;


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.

Our engineering did a great job with the Portal patch as now it doesn't mess up the Docker installation to use the device-mapper



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


When you first install the portal your TENANTID is going to be your postal hostname. Do not forget to also add your TENANTID-ssg.yourdomain into your hosts file. In my case, while installing in this tutorial, I will be using the admin as the TENANTID and thus I also need the admin-ssg. Without this entry you're not going to be able to add your tenant later.


When you deploy a tenant to your portal you need to point your tenantID, to the same IP address of your portal. I personally always install my portal using admin.mydomain and then when I first deploy my tenant I call it portal. That would add a new entry into my hosts file, like this: portal.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 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 \

[root@ip-172-31-44-19 ~]# yum-config-manager \
    --add-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

If you want to use your own NTP server, just replace "" with your server IP address/hostname



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:

Rename your license file to license.xml to make it easier during your portal configuration step. Also make sure you copy your license.xml to /opt/apim-portal- folder



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- /opt/
[root@ip-172-31-44-19 centos]# cd /opt/
[root@ip-172-31-44-19 opt]# tar -xvzf apim-portal-


Run the script


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


QuestionWhat is it?Example
Tenant ID (PORTAL_TENANT_ID) [apim]:This is the first TENANTID we talked about previously. For the sake of this tutorial I will be using admin as my TENANDID.admin
Portal subdomain (PORTAL_SUBDOMAIN)This is the DNS subdomain of my portal intallation. For the sake of this tutorial we are going to be using the domain apicarocks.labapicarocks.lab
Path to license file (PORTAL_LICENSE_FILENAME)Path and file name of your portal's license/opt/apim-portal-
Enroll notification email address (PORTAL_ENROLL_NOTIFICATION_EMAIL)Email address used to communicate with the developersnoreply@apicarocks.lab
Analytics enabled (PORTAL_ENABLE_ANALYTICS)Enable Portal Analycticsy


Every time you need to change something, like update your license, then you need to run your script once again.



Run the following commands to configure your portal:


[root@ip-172-31-44-19 apim-portal-]# ./

APIM Portal configuration

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

                  PORTAL_TENANT_ID:     admin
                  PORTAL_SUBDOMAIN:     apicarocks.lab
           PORTAL_LICENSE_FILENAME:     /opt/apim-portal-
  PORTAL_ENROLL_NOTIFICATION_EMAIL:     noreply@apicarocks.lab

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


If you get an error saying that your docker service is not running, then run: systemctl start docker and then docker info to make sure the daemon is running properly.


Running the script


Now that you have configured the portal, run the 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 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,
          "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- content or the mutual SSL will not work and the request will thus fail.




If you see a "Private Key is Missing" error, try to paste the private key before the certificate







Remember that the default credentials to access your new tenant are: admin / 7layer


I hope this tutorial can help you out!

0 Favorited
0 Files

Tags and Keywords


03-08-2018 08:28 AM

Now this is what I call "documentation at its best". Very nicely done Alan.

03-07-2018 05:01 PM

Terrific Work!, thanks a lot. Indeed: proud of you


We installed the 4.2.0 and after that we try the version but in an on-premises environment and using the OVA provided by CA.


We tested the 3 master node configuration with less than 32G in each node.

But I have trouble in the order the dockers started: albeit the stated in the temporary docker-compose file that some services have "depends_on",  we saw a lot of errors in the logs, showing that some services are starting before the services in the "depends_on". We found in the Docker documentation (Compose file version 3 reference | Docker Documentation ) the following note: "The depends_on option is ignored when deploying a stack in swarm mode with a version 3 Compose file". So apparently we have no order in the services in docker.

Are we understanding correctly the Docker stack/swarm info? How is your starting process? how it takes in minutes?

do you have a clean start process (a clean log) or the same try/error/eventually ok race?


Thanks a lot

02-20-2018 05:14 PM


Case someone needs to curl.. try:

curl -X POST -H "Content-Type: application/json" --insecure --cert-type pem --cert ./apim.pem -d @enrollment.json "https://<portal>-ssg.<domain>:9443/provision/tenants"

where enrollment.json is the generated JSON inside a file like the content above!

Thanks ever so much for this tutorial Alan!

02-16-2018 03:22 PM

Great work! Might be worth adding that the default username for centos is centos and that the key file needs to have 400 permissions for ssh to work on first login

02-15-2018 05:58 PM

Mic Drop, BOOM!!!   I will doing this soon Alan, will let you know how it goes, thanks ever so much for this tutorial!

Related Entries and Links

No Related Resource entered.