Configuring a Single Node
This page walks you through how to manually configure the API Manager as a single node when deploying as an all-in-one instance.
- Unzip the WSO2 API Manager pack. Let's call it
<APIM_HOME>
. Open the
<APIM_HOME>/repository/conf/datasources/master-datasources.xml
file. This file contains the different datasources used by WSO2 API Manager. By default, the API Manager connects to the local H2 database and it is recommended to use a separate RDBMS server for a production deployment.Follow the steps below to integrate the API Manager with an external database (in this case, an external MySQL Server).
- Update the existing WSO2AM_DB with the configuration given below.
Add two new entries, WSO2GOV_DB and WSO2UM_DB, as shown below.
<datasource> <name>WSO2AM_DB</name> <description>The datasource used for API Manager database</description> <jndiConfig> <name>jdbc/WSO2AM_DB</name> </jndiConfig> <definition type="RDBMS"> <configuration> <driverClassName>com.mysql.jdbc.Driver</driverClassName> <url>jdbc:mysql://localhost:3306/apimgtdb</url> <username>root</username> <password>root</password> <maxActive>50</maxActive> <maxWait>60000</maxWait> <minIdle>5</minIdle> <testOnBorrow>true</testOnBorrow> <validationQuery>SELECT 1</validationQuery> <validationInterval>30000</validationInterval> <defaultAutoCommit>false</defaultAutoCommit> </configuration> </definition> </datasource> <datasource> <name>WSO2GOV_DB</name> <description>The datasource used for registry and user manager</description> <jndiConfig> <name>jdbc/WSO2GovDB</name> </jndiConfig> <definition type="RDBMS"> <configuration> <driverClassName>com.mysql.jdbc.Driver</driverClassName> <url>jdbc:mysql://localhost:3306/regdb</url> <username>root</username> <password>root</password> <maxActive>50</maxActive> <maxWait>60000</maxWait> <minIdle>5</minIdle> <testOnBorrow>true</testOnBorrow> <validationQuery>SELECT 1</validationQuery> <validationInterval>30000</validationInterval> <defaultAutoCommit>false</defaultAutoCommit> </configuration> </definition> </datasource> <datasource> <name>WSO2UM_DB</name> <description>The datasource used for API Manager database</description> <jndiConfig> <name>jdbc/WSO2UM_DB</name> </jndiConfig> <definition type="RDBMS"> <configuration> <driverClassName>com.mysql.jdbc.Driver</driverClassName> <url>jdbc:mysql://localhost:3306/userdb</url> <username>root</username> <password>root</password> <maxActive>50</maxActive> <maxWait>60000</maxWait> <minIdle>5</minIdle> <testOnBorrow>true</testOnBorrow> <validationQuery>SELECT 1</validationQuery> <validationInterval>30000</validationInterval> <defaultAutoCommit>false</defaultAutoCommit> </configuration> </definition> </datasource>
Create the required databases.
WSO2 API Manager is shipped with an H2 database. This embedded H2 database is suitable for development and testing environments. However, for production environments, it is recommended to use an industry-standard RDBMS such as Oracle, PostgreSQL, MySQL, MS SQL, etc.
The following steps describe how to download and install MySQL Server, create the databases, configure the datasources, and configure the API Manager components to connect to them.
- Download and install MySQL Server.
- Download the MySQL JDBC driver and unzip the downloaded MySQL driver zipped archive.
- Copy the MySQL JDBC driver JAR file (
mysql-connector-java-x.x.xx-bin.jar
) into the<APIM_HOME>/repository/components/lib
directory. To define the host name for configuring permissions for the new database, open the
/etc/hosts
file and add the following:Do this step only if your database is not on your local machine and on a separate server.
<MYSQL-DB-SERVER-IP> carbondb.mysql-wso2.com
Enter the following command in a command window, where username is the username you want to use to access the databases,
mysql -u username -p
- When prompted, specify the password that will be used to access the databases with the username you specified.
Create the three databases using the following commands, where
<APIM_HOME>
is the path to any of the API Manager instances you installed, and username and password are the same as those you specified in the previous steps.For Microsoft Windows users: When creating the database in MySQL, it is important to specify the character set as latin1. Failure to do this may result in an error (error code: 1709) when starting your cluster. This error occurs in certain versions of MySQL (5.6.x), and is related to the UTF-8 encoding. MySQL originally used the latin1 character set by default, which stored characters in a 2-byte sequence. However, in recent versions, MySQL defaults to UTF-8 to be friendlier to international users. Therefore, in order to avoid this problem, use latin1 as the character set as indicated below in the database creation commands. Note that this may result in issues with non-latin characters (like Hebrew, Japanese, etc.). The database creation command should be as follows:
mysql> create database <DATABASE_NAME> character set latin1;
For users of other operating systems: The standard database creation commands will suffice. For these operating systems, the database creation command should be as follows:.
mysql> create database <DATABASE_NAME>;
From WSO2 API Manager 2.0.0 onwards there are two MySQL DB scripts available in the product distribution. Click here to understand as to which version of the MySQL script to use.
mysql> create database apimgtdb; mysql> use apimgtdb; mysql> source <APIM_HOME>/dbscripts/apimgt/mysql.sql; mysql> grant all on apimgtdb.* TO username@localhost identified by "password"; mysql> create database userdb; mysql> use userdb; mysql> source <APIM_HOME>/dbscripts/mysql.sql; mysql> grant all on userdb.* TO username@localhost identified by "password"; mysql> create database regdb; mysql> use regdb; mysql> source <APIM_HOME>/dbscripts/mysql.sql; mysql> grant all on regdb.* TO username@localhost identified by "password";
If you are using MySQL version 5.7, you need to run the
mysql5.7.sql
script instead of themysql.sql
script when executing the commands above.
Configure the API Manager to refer to the WSO2UM_DB for user information by updating the following configuration in the
<APIM_HOME>/repository/conf/user-mgt.xml
file:<Property name="dataSource">jdbc/WSO2UM_DB</Property>
If you are using the WSO2UM_DB to store users, remember to change the administrator username and password.
Start the API Manager with the following command,
For Linuxsh wso2server.sh -Dsetup
For Windowswso2server.bat -Dsetup
This creates the required tables. Once the server starts successfully, you can shutdown it down and continue with the rest of the steps.
To add a registry entry to reflect the newly added datasource, add the following configurations to the
<APIM_HOME>/repository/conf/registry.xml
file as shown below:<dbConfig name="wso2gov"> <dataSource>jdbc/WSO2GovDB</dataSource> </dbConfig> <remoteInstance url="https://localhost:9453/registry"> <id>wso2gov</id> <dbConfig>wso2gov</dbConfig> <readOnly>false</readOnly> <registryRoot>/</registryRoot> </remoteInstance> <mount path="/_system/governance" overwrite="true"> <instanceId>wso2gov</instanceId> <targetPath>/_system/governance</targetPath> </mount>
Do not replace the following configuration when adding the above mounting configurations. The registry mounting configurations mentioned above must be added in addition to the following.
<dbConfig name="wso2registry"> <dataSource>jdbc/WSO2CarbonDB</dataSource> </dbConfig>
- WSO2 API Manager is shipped with a default keystore named wso2carbon.jks. It is recommended to change this default keystore in a production deployment. For more information on changing this default keystore, see Creating New Keystores.
A load balancer or reverse proxy is required to map external traffic with ports and URLs used internally by API Manager. Update the
ngnix.conf
file with the required Nginx configuration given below. In this case, the hostname is assumed to belocalhost
. Ensure that you generate a certificate and update the certificate and key path in the configuration below:http { include mime.types; default_type application/octet-stream; sendfile on; keepalive_timeout 65; upstream servlet-traffic { server 127.0.0.1:9443; } upstream traffic-http { server 127.0.0.1:8280; } upstream traffic-https { server 127.0.0.1:8243; } server { server_name localhost; listen 443; ssl on; ssl_certificate <<Certifacte.crt>>; ssl_certificate_key <<CertficateKey.key>>; #Carbon - servlet-traffic location /carbon { index index.html; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Server $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_pass https://servlet-traffic/carbon/; proxy_redirect https://servlet-traffic/carbon/ https://localhost/carbon/; #proxy_cookie_path / /carbon/; } #Store Registry for images - servlet-traffic location ~ ^/store/(.*)registry/(.*)$ { index index.html; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Server $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_pass https://servlet-traffic/$1registry/$2; } #Publisher Registry for images - servlet-traffic location ~ ^/publisher/(.*)registry/(.*)$ { index index.html; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Server $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_pass https://servlet-traffic/$1registry/$2; } # Publisher location /publisher { index index.html; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Server $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_pass https://servlet-traffic/publisher; proxy_redirect https://servlet-traffic/publisher https://localhost/publisher; proxy_cookie_path /publisher /publisher; } # Admin Console location /admin { proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Server $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_pass https://servlet-traffic/admin; proxy_redirect https://servlet-traffic/admin https://localhost/admin; proxy_cookie_path /publisher /publisher; } #API traffic - All nodes - HTTPS location / { proxy_pass https://traffic-https/; } # All Store - All nodes location /store { index index.html; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Server $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_pass https://servlet-traffic/store; proxy_redirect https://servlet-traffic/store https://localhost/store; proxy_cookie_path /store /store; } } server { server_name localhost; listen 80; #API traffic - All nodes - HTTP location / { proxy_pass http://traffic-http/; } } }
The ports and URLs that are used internally by API Manager are given below:
Usage
URL
Port
HTTP Servlet
localhost
9763
HTTPS Servlet (UI Consoles)
localhost
9443
NIO transport (HTTP API Traffic)
localhost
8280
NIO transport (HTTPS API Traffic)
localhost
8243
Ensure that the ports and URLs are mapped correctly in the load balancer.
Follow the steps below to update the API Store, API Publisher and Admin Portal to work with the Proxy Server configuration.
API Store - Update the
<APIM_Home>\repository\deployment\server\jaggeryapps\store\site\conf\site.json
file as shown below:"reverseProxy" : { "enabled" : true, // values true , false , "auto" - will look for X-Forwarded-* headers "host" : "localhost", // If reverse proxy do not have a domain name use IP "context":"/store", //"regContext":"" // Use only if different path is used for registry }
API Publisher - Update the
<APIM_Home>\repository\deployment\server\jaggeryapps\publisher\site\conf\site.json
file as shown below:"reverseProxy" : { "enabled" : true, // values true , false , "auto" - will look for X-Forwarded-* headers "host" : "localhost", // If reverse proxy do not have a domain name use IP "context":"/publisher", //"regContext":"" // Use only if different path is used for registry }
Admin Portal - Update the
<APIM_Home>\repository\deployment\server\jaggeryapps\admin\site\conf\site.json
file as shown below:"reverseProxy" : { "enabled" : true, // values true , false , "auto" - will look for X-Forwarded-* headers "host" : "localhost", // If reverse proxy do not have a domain name use IP "context":"/admin", //"regContext":"" // Use only if different path is used for registry },
If a hostname is used to expose APIs, you need to add this hostname in the
<APIM_HOME>/repository/conf/api-manager.xml
file. Update the<GatewayEndpoint>
element with your chosen hostname as shown below, in this case we would be using 'localhost' as the hostname:<!-- Endpoint URLs for the APIs hosted in this API gateway.--> <GatewayEndpoint> http://localhost,https://localhost </GatewayEndpoint>
For enhanced security, encrypt and change all passwords. For more information, see Encrypting Passwords with Cipher Tool.
- If you want to configure a different userstore (other than a JDBC userstore), follow the instructions given in Configuring User Stores.
- You can also configure a scheduled task to backup daily rolling logs to separate disks in order to avoid disk space from running out.
- You can tune the performance of your API Manager deployment by tuning performance.
- In order to configure API Analytics with WSO2 API Manager, follow the instructions given in Configuring APIM Analytics.