On-Premises Deployment Using Docker

Introduction

This manual will describe a normal deployment procedure for API Fortress on-premises.

The apifortress_starter.zip file you’ve been provided contains the following files:

certs/apifortress.crt
core/docker-compose.yml
core/tomcat_conf/conf/
core/create_network.sh
downloader/docker-compose.yml

1. Copy the Provided Script Files

Copy the provided core and downloader directories to the server and then type cd core/.

2. Configure the Core Services

Before anything else, let’s configure each service and prepare the environment.
Most configuration keys are stored within the core/docker-compose.yml file.

PostgreSQL
The only special configuration will be the storage on the host machine.
Create a directory that will host PostgreSQL data in the host machine, and edit the first part (before the : ) in the configuration, accordingly:

    volumes:
   - /var/tmppostgres:/var/lib/postgresql/data

MongoDB
As with PostgreSQL, you are required to provide a storage location and edit the volumes key accordingly:

  volumes:
  - /var/tmpmongo:/data/db

API Fortress
There are a lot of configuration keys here. None of them should be left empty (a fake value is fine if you’re not using a certain feature). See the API Fortress Configuration Guide below for an explanation of each key.
The essential keys for bootstrap (with dummy values) are:

Admin user creation
adminEmail: solomon_pi@gmail.com
adminFullName: Solomon Pi

Company creation
defaultCompanyName: The PI

Base URL that will respond to HTTP requests
grailsServerURL: http://anythinghere.com/app

API Fortress Mailer
Refer to the API Fortress Configuration Guide below.

API Fortress Downloader
To be configured after the dashboard bootstrap.
Refer to the API Fortress Configuration Guide below.

3. Install Docker

Install Docker on a supported Linux distribution following the official instructions:
https://docs.docker.com/engine/installation/
The API Fortress stack runs successfully on Docker 1.12.

4. Install Docker Compose

Docker Compose is a utility that simplifies the deployment and management of complete stacks. Follow the official instructions for installation:
https://docs.docker.com/compose/install/

5. Install the API Fortress Registry Certificate

To access the API Fortress registry you will need to install the provided certificate. To do so, copy it to the following locations:
/etc/docker/certs.d/utils.apifortress.com:5000/
/usr/local/share/ca-certificates/
Then invoke sudo update-ca-certificates

Additionally, on RedHat copy the certificate to:
/etc/pki/ca-trust/source/anchors/
and invoke update-ca-trust

6. Login

Enter sudo docker login utils.apifortress.com:5000 and input the username and password that have been provided to you.

7. Create the API Fortress network

The default API Fortress subnet is 172.18.0.0/16. Make sure the default subnet is not in use. If it is then edit it in the create_network.sh script. Issue sudo ./create_network.sh  to create a virtual subnet for API Fortress.

8. Launch the Services

While all services can be launched with one single command, it is possible that slow servers might not be able to launch required services before the consuming service. For this reason we recommend to launch the services individually. The first time the commands are issued, Docker will download the images and then run them. From within the core/ directory, issue the following commands:

PostgreSQL
sudo docker-compose up -d apifortress-postgres

MongoDB
sudo docker-compose up -d apifortress-mongo

RabbitMQ
sudo docker-compose up -d apifortress-rabbit

API Fortress Dashboard
sudo docker-compose up -d apifortress

API Fortress Mailer
sudo docker-compose up -d apifortress-mailer

API Fortress Scheduler
sudo docker-compose up -d apifortress-scheduler

API Fortress Connector
sudo docker-compose up -d apifortress-connector

9. Verify the Deployment

At the end of the process, the API Fortress dashboard should be up and running in the host server on port 80. You can also check for errors in the logs by issuing the: sudo docker-compose logs command.

The admin user login details are as follows:

  • username: the email address provided in the docker-compose configuration, in the adminEmail field;
  • password: ‘foobar’, change it as soon as you log in.

10. Configure and Run the Downloader

The API Fortress downloader is the agent retrieves the resources to be tested. Downloaders can be installed in various locations, so factors such as latency and download time can be measured by remote consumers.

In this configuration path, we are deploying a downloader in the same server as API Fortress, and it will serve as the default downloader.

1. Edit the downloader/docker-compose.yml file and take note of the value of the ipv4_address configuration key.

2. Login to API Fortress with the admin user, access the API Fortress admin panel by clicking the “user” icon in the top right, then click Admin Panel.

login

3. Choose “Downloaders” from the list of actions and click on the “Add Downloader” button.

4. Fill the fields:
Name: give the downloader a recognizable name
Location: a textual representation of where the downloader is. Ie. San Diego
Latitude / Longitude: express the geographical position of the downloader
Last resort: check it if this is your first downloader. It will be chosen automatically when you don’t make a explicit downloader selection.
URL: the address of the downloader, followed by port (default 8819) and path /api. In this scenario, the ipv4_address we previously noted down is our downloader address. Ie. http://172.18.1.1:8819/api
API Key, API Secret: take note of these two values and save.

5. Edit the  downloader/docker-compose.yml file and fill the API Key and API Secret keys with the retrieved values.

6. Run the downloader by issuing the sudo docker-compose up -d command from the downloader/ directory.

Note: as a default, for testing purposes, the downloader will run over HTTP. When running outside a protected channel, consider making it run over HTTPS. In the docker-compose.yml of the downloader, turn on HTTPS by changing the ‘use_ssl’ attribute to true, and make sure that the downloader url in the admin panel starts with https://.

API Fortress Configuration Guide

A description of each configuration field you may need to alter.

API Fortress Dashboard

Bootstrap:
 – adminEmail: The admin user email address, also used as login
 – adminFullName: The admin full name
 – defaultCompanyName: The company name

System:
 – grailsServerURL: the url the server will respond to
 – dbHost: MongoDB host
 – psqlhost: PostgreSQL host
 – rabbitHost: RabbitMQ host

Email:
 – apifortressMailUseSES: set to ‘true’ if you will use Amazon SES to send emails. When set to ‘false’, SMTP is used instead
 – apifortressMailFrom: the email address that will be used to dispatch administrative emails
 – apifortressMailSmtpHost: SMTP host to dispatch administrative emails
 – apifortressMailSmtpUsername: SMTP username
 – apifortressMailSmtpPassword: SMTP password
 – apifortressMailSmtpPort: SMTP port
 – amazonkey: Amazon key, if you’re using Amazon SES to send emails
 – amazonsecret: Amazon secret, if you’re using Amazon SES to send emails
 – apiaryClientId: client ID if you’re using Apiary services
 – apiarySecret: secret, if you’re using Apiary services
 – license: the license string

API Fortress Mailer
 – twilioSid: SID, if you’re sending SMSes via Twilio
 – twilioToken: token, if you’re sending SMSes via Twilio
 – smsFrom: the phone number of the SMS sender, if you’re sending SMSes via Twilio
 – mailFrom: the email address that will be sending notification emails
 – mailUseSES: ‘true’ if you’re sending emails via Amazon SES. False if you’re using SMTP
 – amazonKey: the Amazon key, if you’re sending emails via Amazon SES
 – amazonSecret: the Amazon secret, if you’re sending emails via Amazon SES
 – mailSmtpHost: the SMTP host
 – mailSmtpPort: the SMTP port
 – mailSmtpUsername: the SMTP username
 – mailSmtpPassword: the SMTP password
 – apifortressServerURL: the url the server will respond to

API Fortress Downloader
 – apikey: the API key, as shown in the admin panel
 – secret: the API secret, as shown in the admin panel
 – port: the HTTP port the server will be listening to, in HTTP mode
 – rabbitHost: the RabbitMQ host, when running in active mode
 – rabbitPort: the RabbitMQ port, when running in active mode
 – rabbitSsl: ‘true’ if RabbitMQ will need communicate over SSL, when running in active mode
 – rabbitUsername: the RabbitMQ username when running in active mode
 – rabbitPassword: the RabbitMQ password when running in active mode
 – use_rabbit: ‘true’ to run in active mode
 – use_http: ‘true’ to use the internal HTTP server (passive mode)
 – use_ssl: ‘true’ if the internal HTTP server has to run over SSL

The network configuration is also important as the IP address may be used for internal communication.

networks.apifortress.ipv4_address: the reserved IP address in the API Fortress subnet.

 

Appendix: Tweaking Tomcat configuration

If you need to tweak the Tomcat configuration, you will need to mount the Tomcat conf/ directory in your system.
1. Change the configuration files you need to edit in the core/tomcat_conf/conf directory
2. Mount the directory by uncommenting the following lines in the core/docker-compose.yml file:

# volumes:
# - ./tomcat_conf/conf:/usr/local/tomcat/conf

Dashboard over SSL

To have Tomcat running over SSL:
1. Copy your JKS keystore containing your certificate in the core/tomcat_conf/conf directory
2. 
Edit the core/tomcat_conf/conf/server.xml file and uncomment the block:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol" maxThreads="150" SSLEnabled="true" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" />

3. Edit the block by adding the following attributes:

keystoreFile="/usr/local/tomcat/conf/keystore.jks"
keystorePass="thePasswordHere"

4. Mount the directory by uncommenting the following lines in the core/docker-compose.yml file:

# volumes:
# - ./tomcat_conf/conf:/usr/local/tomcat/conf

5. In the core/docker-compose.yml file, change the port declaration to:
ports:

- 443:8443/tcp