Generic Configurations of the Deployment

The following topics cover the configurations generic for all four deployment patterns described in the previous section:

Prerequisites

1. In this example, we use the following products.

• WSO2 Elastic Load Balancer 2.0.1 or higher
  
• MySQL server
• SVNKit

2. When configuring a deployment pattern with all 4 API Manager components, extract the API Manager full distribution into four folders and name them as Publisher, Store, Key Manager and Gateway.

3. Different physical servers are used for the installation of the server instances. If deploying on a single machine for testing purposes, change the offset of all servers in <APIM _HOME>/repository/conf/carbon.xml file. This is done to avoid port conflicts that occur when running multiple WSO2 product instances in the same server.

4. This document is based on server installations on a single machine. Following are the port numbers used for the component servers:

Configuring Shared Databases

We use shared databases to share information among distributed sever nodes of the API Manager. The following table shows a summarized view of the shared database configuration:

Details of the configuration are given below.

User Manager Database Configuration

Let's take a look at configuring the User Manager database that is shared with the API Publisher, Store, and Key Manager servers.

1. Copy the MySQL JDBC driver jar file into the <APIM_HOME>/repository/component/lib folder for all API Manager components.

2. Create a new MySQL database by the name prod_umdb , and create user manager tables using the script available in <APIM_HOME>/dbscripts/mysql.sql. In this example we use MySQL database but you can also use other types of databases as well.

mysql -u root -p
When prompted, specify the password to the access the mySQL database with the specified username.

mysql> create database prod_umdb;
mysql> use prod_umdb;
mysql> source mysql.sql;

3. Create a new user and grant access to the database as follows.

mysql> grant all on reg_db.* TO user@localhost identified by "password";

• user : The username for the user who needs access to the database
• password : The password for the user who needs access the database

4. Update <APIM _HOME>/repository/conf/datasources/master-datasources.xml file in the Publisher, Store, and Key Manager server instances to connect to the above database.

<datasource>
   <name>WSO2UM_DB</name>
   <description>The datasource used by user manager</description>
   <jndiConfig>
      <name>jdbc/WSO2UM_DB</name>
   </jndiConfig>
   <definition type="RDBMS">
      <configuration>
         <url>jdbc:mysql://192.168.139.1:3306/prod_umdb?autoReconnect=true&amp;relaxAutoCommit=true</url>
         <username>user</username>
         <password>password</password>
         <driverClassName>com.mysql.jdbc.Driver</driverClassName>
         <maxActive>50</maxActive>
         <maxWait>60000</maxWait>
         <testOnBorrow>true</testOnBorrow>
         <validationQuery>SELECT 1</validationQuery>
         <validationInterval>30000</validationInterval>
      </configuration>
   </definition>
</datasource>

• url : The URL of the registry mySQL database
•  username : The username to access the mySQL database
•  password : The password to access the mySQL database
•  jdbc/WSO2UM_DB : The same name used for the datasource in INSTALL_HOME/repository/conf/user-mgr.xml file for all the components  

5. Configure <APIM _HOME>/repository/conf/user-mgt.xml for all the API Manager components as shown below.

This configuration is used to define the user manager database of the API Manager components, and is required in the Publisher, Store, and Key Manager server instances where the user manager database needs to be shared.

<UserStoreManager class="org.wso2.carbon.user.core.ldap.ReadWriteLDAPUserStoreManager">
   <Property name="dataSource">jdbc/WSO2UM_DB</Property>
   <Property name="ReadOnly">false</Property>
   <Property name="IsEmailUserName">false</Property>
   ...
</UserStoreManager>

• url : The URL of the mySQL user manager database
• username : The username to access the mySQL database
• password : The password to access the mySQL database
• jdbc/WSO2UM_DB : The datasource name for the datasource used as the user manager database

In the current installation, the primary user store (defined first in user-mgt.xml  file) contains administration users and passwords. These user credentials are used for the initial login to the management console UI of the API Manager. To enable user names that contain email addresses, add the following parameter in INSTALL_HOME/repository/conf/carbon.xml file:

<EnableEmailUserName>true</EnableEmailUserName> 

Registry Database Configuration

This section describes the creation and configuration of the registry database that will be used by the Publisher and Store server instances. The Governance space (/_system/governance) of the Publisher and Store instances are mounted to a common location within a remote governance registry instance. We will use MySQL as the registry database in this particular governance registry instance.  

1. Copy the mysql jar file into <APIM _HOME>/repository/component/lib folder for all API Manager components. 

2. Create a new mySQL database by the name prod_regdb , and create tables using the script available in <APIM_HOME>/dbscripts/mysql.sql file.  folder of the API Manager distribution. In this example we use MySQL database but you can also use other types of databases as well. 

mysql> create database prod_regdb;
mysql> use prod_regdb;
mysql> source mysql.sql;

3. Create a new user and grant access to the database as follows.

mysql> grant all on reg_db.* TO user@localhost identified by "password";

• user : The username for the user who needs access to the database
• password : The password for the user who needs access the database

4. To define a datasource for the registry, update <APIM _HOME>/repository/conf/datasources/master-datasources.xml file in the API Publisher and Store server instances to connect to the database created above.

<datasource>
   <name>WSO2_REG_DB</name>
   <description>The datasource used for the registry</description>
   <jndiConfig>
      <name>jdbc/WSO2_RegDB</name>
   </jndiConfig>
   <definition type="RDBMS">
      <configuration>
         <url>jdbc:mysql://192.168.139.1:3306/prod_regdb?autoReconnect=true&amp;relaxAutoCommit=true</url>
         <username>user</username>
         <password>password</password>
         <driverClassName>com.mysql.jdbc.Driver</driverClassName>
         <maxActive>50</maxActive>
         <maxWait>60000</maxWait>
         <testOnBorrow>true</testOnBorrow>
         <validationQuery>SELECT 1</validationQuery>
         <validationInterval>30000</validationInterval>
      </configuration>
   </definition>
</datasource>

• url : The URL of the registry mySQL database
• username : The username to access the mySQL database
• password : The password to access the mySQL database 
• jdbc/WSO2_RegDB : The same name used for the datasource in the INSTALL_HOME/repository/conf/api-manager.xml file for all the components

5. Define the registry database in <APIM _HOME>/repository/conf/registry.xml file of the Publisher and Store server instances. The following configuration mounts the governance space to the remote registry instance. 

<dbConfig name="govregistry">
   <dataSource>jdbc/RegDB</dataSource>
</dbConfig>
<remoteInstance url="https://192.168.139.1"> 
   <id>gov</id>
   <dbConfig>govregistry</dbConfig>
   <readOnly>false</readOnly>
   <enableCache>true</enableCache>
   <registryRoot>/</registryRoot>
</remoteInstance>
<mount path="/_system/governance" overwrite="true">
   <instanceId>gov</instanceId>
   <targetPath>/_system/governance</targetPath>
</mount>

• remoteInstance url : the URL of the Publisher/Store server node
• datasource             : The name of the datasource provided for the registry database in the master-datasources.xml file
• username               : The username to access the mySQL database    
  

6. Start the server with the following command:

• On Linux, use wso2server.sh -Dsetup
• On Windows, use wso2server.sh -Dsetup

API Manager Database Configuration

This section describes the creation and configuration of the API manager database used by the Publisher, Store, and Key Manager server instances.

1. Create a new database by the name prodapimgt_db , and run <APIM_HOME>/dbscripts/apimgt/mysql.sql script.  

mysql> create database prod_apimgt_db;
mysql> use prodapimgt_db;
mysql> source mysql.sql

2. Define the datasource for the API Manager database in <APIM _HOME>/repository/conf/datasources/master-datasources.xml file to connect to the above databases.

<datasource>
   <name>WSO2AM_DB</name>
   <description>The datasource used for the API Manager database</description>
   <jndiConfig>
      <name>jdbc/WSO2AM_DB</name>
   </jndiConfig>
   <definition type="RDBMS">
      <configuration>
         <url>jdbc:mysql://192.168.139.1:3306/prod_apimgtdb?autoReconnect=true&amp;relaxAutoCommit=true</url>
         <username>peter</username>
         <password>password</password>
         <driverClassName>com.mysql.jdbc.Driver</driverClassName>
         <maxActive>50</maxActive>
         <maxWait>60000</maxWait>
         <testOnBorrow>true</testOnBorrow>
         <validationQuery>SELECT 1</validationQuery>
         <validationInterval>30000</validationInterval>
      </configuration>
   </definition>
</datasource>

• url : The URL of the API Manager database
•  username : The username to access the mySQL database
•  password : The password to access the mySQL database
•  jdbc/WSO2AM_DB : The same name used for the datasource in the INSTALL_HOME/repository/conf/api-manager.xml file for all the components

Next, let's take a look at deploying individual components of the API Manager.

Configuring API Manager Components

Caching Configuration

Refer to section Caching Configuration for information.

API Key Manager Server Configuration

The Key Manager server is primarily used to validate API keys. The same Auth Manager server can be used as the authentication manager as well. Key Manager is also used for caching configuration as discussed above.

API Gateway Configuration

API Gateway is used to route API calls made by API consumers. The Gateway component validates and authenticates users against given API keys that are stored in the Key Manager Server.
 

1. Ensure that the datasource in <APIM_HOME>/repository/conf/api-manager.xml file is set to the API Manager database defined above. Configuration should be as follows:

<DataSourceName>jdbc/WSO2AM_DB</DataSourceName>

2. Configure the <APIKeyManager> element in <APIM_HOME>/repository/conf/api-manager.xml as shown below. This is required to specify the Key Manager server, which the gateway uses for authentication of all incoming API calls. In this sample, key management validation caching will be stored in the gateway, so this parameter will be set to true.

<APIKeyManager> <ServerURL>https://192.168.139.1:9444/services/</ServerURL>

     <Username>admin</Username>
     <Password>admin</Password>

•   ServerURL : URL of the Key Manager Server node
• Username : Username to connect to the Key Manager Server
• Password  : Password to connect to the Key Manager Server

3. Configure caching as required.

API Publisher and API Store

API Publisher publishes APIs to the API Store, where users can access them. When users subscribes to an API, they generates access tokens to make API calls to that API.  

1. Connect to the API manager database created above by configuring <APIM_HOME>/repository/conf/api-manager.xml as follows:         

<DataSourceName>jdbc/WSO2AM_DB</DataSourceName>

2. Connect the API provider instance to the API Key manager in <APIM_HOME>/repository/conf/api-manager.xml file.

<APIKeyManager>
   <ServerURL>https://192.168.139.1:9444/services/</ServerURL>
   <Username>admin</Username>
   <Password>admin</Password>
...

 3. Configure the <AuthManager> element to the Key Manager server node. For example,  

<AuthManager>
    <ServerURL>https://192.168.139.1:9444/services/</ServerURL>
    <Username>admin</Username>
    <Password>admin</Password>
</AuthManager>

• ServerURL   : The URL of the Key Manager server
• Username   : Username to connect to the Key Manager Server
• Password    : Password to connect to the Key Manager Server

4. Configure the <APIGateway> element to the API Gateway server node. For example,  

<APIGateway>
    <ServerURL>https://192.168.139.1:9445/services/</ServerURL>
    <Username>admin</Username>
    <Password>admin</Password>          
    <APIEndpointURL>http://192.168.139.1:8282,https://192.168.139.1:8245</APIEndpointURL>   
</APIGateway>

• ServerURL           : The URL of the API Gateway Server
• Username           : Username to connect to the API Gateway Server
• Password            : Password to connect to the API Gateway Server
• APIEndpointURL   : Endpoint URL for APIs hosted on the Gateway

Next, refer to Clustering the Gateway Server Nodes.