Installing WS02 API Manager On Ubuntu Linux 14.04

There are official instructions to installing WSO2 API Manager that can be found here, but I found them lacking in critical details. The walkthrough below lays out the detailed steps for doing this.  I spun up the cheapest $5/month VM at Digital Ocean to keep costs down as I experimented. These VMs have 20GB of hard disk and 512MB of RAM, which are FAR below the recommended sizing for API Manager. I  recommend adhering to those guidelines if you are deploying to production.

1. Login to Digital Ocean and spin up a preconfigured Ubuntu 14.4 x64 Droplet.
2. Once provisioned, update the Droplet to have the latest packages (sudo apt-get update, sudo-apt-get upgrade,sudo apt-get dist upgrade) and reboot into the latest Linux kernel.
3. I like to install HTOP for a more visual understanding of how a server is consuming resources: sudo apt-get install htop
4. Install Oracle Java 7 (NOT a newer version – the official documents explicitly state this)
   (UPDATE: the latest API Manager 1.10 fully supports JDK 1.8)
   1. sudo apt-get install python-software-properties
   2. sudo add-apt-repository ppa:webupd8team/java
   3. sudo apt-get install oracle-java7-installer
   4. Check that Java was installed properly with the “java -version” command:
      java version “1.7.0_80”
      Java(TM) SE Runtime Environment (build 1.7.0_80-b15)
      Java HotSpot(TM) 64-Bit Server VM (build 24.80-b11, mixed mode)
   5.  sudo apt-get clean all
5. Create a 2GB swapfile to ensure you can start WSO2 in a memory-constrained environment:
   1. Create a swapfile:
      1. sudo swapoff /swapfile
         sudo dd if=/dev/zero of=/swapfile bs=1024 count=1024
         sudo dd if=/dev/zero of=/swapfile bs=2048 count=2048
         sudo mkswap /swapfile
         sudo swapon /swapfile
         sudo chown root:root /swapfile
         sudo chmod 0600 /swapfile
         sudo nano /etc/fstab
         /swapfile none swap sw 0 0
6. Edit the /etc/environment file to point two variables to their proper places:
   1. Add the following:
      1. JAVA_HOME=”/usr/lib/jvm/java-7-oracle/”
         CARBON_HOME=”/usr/local/opt/wso2am-1.10.0″
      2. source /etc/environment
      3. Test the variables:  echo #JAVA_HOME
7. WSO2 needs a backing MYSQL server to run. Here is how you install it:
   1. sudo apt-get install mysql-server
   2. Set a password: mysqladmin -u root password (password)
   3. Change the max_connections variable from 100 to 2 in /etc/mysql/my.conf
      max_connections = 2
   4. Import the WSO2 database schema in MySQL:
      1. mysql -u root -p WSO2AM_STATS_DB < /usr/local/opt/wso2am-1.10.0/dbscripts/stat/sql/mysql.sql
8. Download the WS02 zipped binary from here, and copy it to the Droplet. Its 381Mb in size, so it may take awhile to download.
9. Once the file is on the server, unzip it to the /usr/local/opt directory:
   1. mkdir -p /usr/local/opt
   2. cp wso2am-1.10.0.zip /usr/local/opt
   3. unzip wso2am-1.10.0.zip
10. Note that logs for the server are kept in the /usr/local/opt/wso2am-1.10.0/repository/logs directory if you need to review them. The wso2carbon.log contains a great deal of useful information.
11. Edit the server startup script (wso2server.sh), adding the same variables you added to /etc/environment to the top of the file:
    1. sudo nano /usr/local/opt/wso2am-1.10.0/bin/wso2server.sh
    2. JAVA_HOME=”/usr/lib/jvm/java-7-oracle/”
       CARBON_HOME=”/usr/local/opt/wso2am-1.10.0″
12. Edit the server startup script (wso2server.sh) to alter the JVM size parameters:
    1. sudo nano /usr/local/opt/wso2das-3.0.0/bin/wso2server.sh
    2. Scroll down to approximately line 294
    3. Change the parameters to read: -Xms256m -Xmx1024m -XX:MaxPermSize=256m \
13. Start the server: /usr/local/opt/wso2am-1.10.0/bin/wso2server.sh start
    1. Note that it takes AWHILE to startup the server, as a number of applications have to be deployed. Be patient and expect high CPU usage.
    2. You can tail the wso2carbon.log file to watch startup happen:   tail -f /usr/local/opt/wso2am-1.10.0/repository/logs/wso2carbon.log
    3. Stopping the server is done via the same command: /usr/local/opt/wso2am-1.10.0/bin/wso2server.sh stop
14. If everything started successfully, you will see the assertions below in the wso2carbon.log

TID: [-1234] [] [2016-01-10 20:17:11,502] INFO {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent} – Server : WSO2 API Manager-1.10.0 {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent}
TID: [-1234] [] [2016-01-10 20:17:11,547] INFO {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent} – WSO2 Carbon started in 106 sec {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent}
TID: [-1234] [] [2016-01-10 20:17:13,710] INFO {org.wso2.carbon.ui.internal.CarbonUIServiceComponent} – Mgt Console URL : https://10.17.0.5:9443/carbon/ {org.wso2.carbon.ui.internal.CarbonUIServiceComponent}
TID: [-1234] [] [2016-01-10 20:17:13,715] INFO {org.wso2.carbon.ui.internal.CarbonUIServiceComponent} – API Publisher Default Context : http://10.17.0.5:9763/publisher {org.wso2.carbon.ui.internal.CarbonUIServiceComponent}
TID: [-1234] [] [2016-01-10 20:17:13,716] INFO {org.wso2.carbon.ui.internal.CarbonUIServiceComponent} – API Store Default Context : http://10.17.0.5:9763/store {org.wso2.carbon.ui.internal.CarbonUIServiceComponent}

15. You can also run the “netstat -pantl” command to verify all the ports are listening:

netstat -pantl
Active Internet connections (servers and established)
Proto Recv-Q Send-Q Local Address Foreign Address State PID/Program name
tcp 0 0 0.0.0.0:9999 0.0.0.0:* LISTEN 2373/java
tcp 0 0 0.0.0.0:8243 0.0.0.0:* LISTEN 2373/java
tcp 0 0 0.0.0.0:22 0.0.0.0:* LISTEN 884/sshd
tcp 0 0 10.17.0.5:10711 0.0.0.0:* LISTEN 2373/java
tcp 0 0 0.0.0.0:8280 0.0.0.0:* LISTEN 2373/java
tcp 0 0 0.0.0.0:48123 0.0.0.0:* LISTEN 2373/java
tcp 0 0 10.17.0.5:10397 0.0.0.0:* LISTEN 2373/java
tcp 0 0 0.0.0.0:41919 0.0.0.0:* LISTEN 2373/java
tcp 0 0 0.0.0.0:9443 0.0.0.0:* LISTEN 2373/java
tcp 0 0 0.0.0.0:9763 0.0.0.0:* LISTEN 2373/java
tcp 0 0 0.0.0.0:11111 0.0.0.0:* LISTEN 2373/java

15. OPTIONAL: change the listener.

By default the server is set to only be accessible by localhost. This may be suboptimal if you want to make the server available on the Internet. Make this change in the /usr/local/opt/wso2am-1.10.0/repository/conf/carbon.xml file:

sudo nano -c carbon.xml
Change the <HostName> and (MgtHostName> elements to reflect either your Droplet’s external IP or DNS name:

<HostName>apgmgr.yourdomain.com</HostName>
<MgtHostName>apgmgr.yourdomain.com</MgtHostName>

OR

<HostName>104.131.83.69</HostName>
<MgtHostName>104.131.83.69</MgtHostName>

16. Login to API Manager

Note that the product uses a self-signed SSL cert, and your browser will balk at it. Provision a legitimate cert or tell your browser to ignore the error. The former is recommended. Here is what that process looks like, which gets you to the main console:

  

17. The main login screen will look like the screenshot below. Note that I have deployed a sample API app.

This should get you up and running, deploying APIs with the product. Note that the API statistics portion of the API Manager product will not be available unless you install the DAS (Data Analytics Server) module on a separate server, as DAS provides that functionality. If you do not install DAS, you will not be able to view any statistics about your APIs, and will see the following soft error when you try to access the Statistics section: