API BaaS Installation

Edge for Private Cloud v. 4.17.09

Installation overview

After you install the Edge the apigee-setup utility on a node, use that utility to install one or more BaaS components on the node.

Note: See Install the Edge apigee-setup utility for more on installing the Edge apigee-setup utility.

The apigee-setup utility has the form:

sudo /opt/apigee/apigee-setup/bin/setup.sh -p component -f configFile

Pass a configuration file to the apigee-setup utility that contains the information about the installation. If the configuration file is missing any required information, the apigee-setup utility prompts you to enter it on the command line.

The only requirement is that the configuration file must be accessible or readable by the "apigee" user.

For example, use the following command to install the API BaaS Stack:

sudo /opt/apigee/apigee-setup/bin/setup.sh -p b -f myConfig

Specifying the components to install

The Apigee setup.sh utility supports several options for installing API BaaS components. The instructions below use the standalone options (c, e, b, and p) but you can use different options based on your node configuration:

Option	Description
e	Install ElasticSearch only.
b	Install API BaaS Stack only, which also installs Tomcat.
p	Install API BaaS Portal only, which also installs the Nginx router to be used as a web server.
c	Install Cassandra only.
eb	Install ElasticSearch, API BaaS Stack, and Tomcat on the node.
ebp	Install ElasticSearch, API BaaS Portal, API BaaS Stack, and Tomcat but not Cassandra. The portal is so lightweight no additional resources needed for this.
asa	Install all API BaaS components on a single node (Cassandra, Elasticsearch, API BaaS Stack, API BaaS Portal, Tomcat). Use this option for development and testing only, not for production.

Creating a configuration file

The configuration file contains all the information necessary to install API BaaS. You can often use the same configuration file to install all components in a BaaS installation.

Each installation topology described below shows an example config file for that topology. For a complete reference on the config file, see BaaS Configuration File Reference.

Note: API BaaS 4.17.09 added a new required parameter to the configuration file used when you enable an SMTP server. You must now set SMTPMAILFROM in the configuration file when enabling the SMTP server. See the examples below.

Warning: Creating a config file on a Windows machine and then copying it to a Linux machine can add additional end-of-line, carriage return, or newline characters to the file that are not compatible with all Linux utilites. This situation can also occur if you copy text from a Windows editor and paste into a Linux window. As an alternative, you can use the Linux dos2unix utility to clean up a config file created on Windows. Or, make sure to do all editing of config files in a Linux editor.

Install API BaaS on a single node

Shown below is the config file for installing API BaaS on a single node. Edit this file as necessary for your configuration. For a complete reference on the config file, see BaaS Configuration File Reference.

IP1=192.168.56.101   # IP address of single node

# Must resolve to IP address or DNS name of host - not to 127.0.0.1 or localhost.
HOSTIP=$(hostname -i)

# Define the API BaaS administrator account.
AS_ADMIN="superuser"    # User name - default is "superuser".
AS_ADMIN_EMAIL=stackAdmin@email.com
AS_PASSWD=stackAdminPWord

# Because you are installing Cassandra,
# specify Cassandra data center and rack suffix.
# Must use IP addresses for CASS_HOSTS, not DNS names.
CASS_HOSTS="$IP1:1,1"

# Specify the Cassandra region.
REGION=dc-1

# Cassandra uname/pword.
# Even if Cassandra authentication is disabled,
# you must still pass values for these properties.
CASS_USERNAME=cassandra    # Default value
CASS_PASSWORD=cassandra    # Default value

# Specify Cassandra data center name.
BAAS_CASS_LOCALDC=dc-1

# For a single data center, specify the same value as BAAS_CASS_LOCALDC.
BAAS_CASS_DC_LIST=dc-1

# Replication is in the form "dataCenterName:#CassandraNodes".
# For dc-1 with one Cassandra node, it is dc-1:1.
BAAS_CASS_REPLICATION=dc-1:1

# Defines the initial contact points for members of the BaaS cluster.
# For a single node install, specify the IP address of the node.
BAAS_CLUSTER_SEEDS="dc-1:$IP1"

# Single ElasticSearch IP.
ES_HOSTS="$IP1"

# API BaaS Stack information.
# Default cluster name is "apigee_baas"
BAAS_USERGRID_CLUSTERNAME="apigee_baas"

# IP/DNS and port 8080 of a single Stack node.
BAAS_USERGRID_URL="http://$IP1:8080"

# URL and port of the BaaS Portal node.
BAAS_PORTAL_URL="http://$IP1:9000"

# Portal port. Default value is 9000.
BAAS_PORTAL_LISTEN_PORT=9000

# SMTP information. BaaS requires an SMTP server.
SMTPHOST=smtp.gmail.com
SMTPPORT=465
SMTPUSER=your@email.com
SMTPPASSWORD=yourEmailPassword
SMTPSSL=y
SMTPMAILFROM="My Company <myco@company.com>"

To install API BaaS on its own node:

Install the Edge apigee-setup utility on the node using the internet or non internet procedure. See Install the Edge apigee-setup utility for more.
At the command prompt, run the setup script:
```
/opt/apigee/apigee-setup/bin/setup.sh -p asa -f configFile
```
The "-p asa" option specifies to install all API BaaS components on a single node (Cassandra, Elasticsearch, API BaaS Stack, API BaaS Portal, Tomcat).

The configuration file must be accessible or readable by the "apigee" user.
Because you installed ElasticSearch on a standalone node, adjust the default memory option to increase the memory allocated for ElasticSearch from 4GB to 6GB:
1. Open /opt/apigee/customer/application/elasticsearch.properties in an editor. If this file does not exist, create it.
2. Set the setenv_elasticsearch_max_mem_size property to 6g (the default is 4g):
```
setenv_elasticsearch_max_mem_size=6g
```
3. Save the file.
4. Run the following command:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-elasticsearch restart
```
Onboard an organization as described below in Onboarding a new organization.

The configuration successfully completes the setup on the node.

Install API BaaS on 7 or 10 nodes

The procedure for installing a 7 or 10 node version of API BaaS is very similar. The only difference is that for a:

10 node installation, you install the three ElasticSearch components and three API BaaS Stack components on separate nodes, for a total of six nodes. This is the recommended configuration for highest performance because ElasticSearch requires a high amount of disk I/O and memory.
7 node installation, you install the three ElasticSearch components and three API BaaS Stack components on the same nodes, for a total of three nodes.

For both the 7 and 10 node versions of API BaaS, you must connect to a Cassandra cluster. If you have already installed Edge, you can connect to its Cassandra cluster, meaning you do not have to install Cassandra as part of installing API BaaS.

Shown below is an example silent configuration file for a 10-node API BaaS installation. If you are installing the ElasticSearch and API BaaS Stack components on the same three nodes, edit the file to so that:

IP1 and IP4 are set to the same IP address
IP2 and IP5 are set to the same IP address
IP3 and IP6 are set to the same IP address

Edit this file as necessary for your configuration. For a complete reference on the config file, see BaaS Configuration File Reference.

# Specify IP address or DNS name of node.
IP1=192.168.1.1   # ElasticSearch
IP2=192.168.1.2   # ElasticSearch
IP3=192.168.1.3   # ElasticSearch
IP4=192.168.1.4   # API BaaS Stack
IP5=192.168.1.5   # API BaaS Stack
IP6=192.168.1.6   # API BaaS Stack
IP7=192.168.1.7   # API BaaS Portal
IP8=192.168.1.8   # Cassandra (shared with Edge or standalone)
IP9=192.168.1.9   # Cassandra (shared with Edge or standalone)
IP10=192.168.1.10  # Cassandra (shared with Edge or standalone)

# Must resolve to IP address or DNS name of host - not to 127.0.0.1 or localhost.
HOSTIP=$(hostname -i)

# Define the API BaaS administrator account.  
AS_ADMIN="superuser"    # User name - default is "superuser".
AS_ADMIN_EMAIL=stackAdmin@email.com
AS_PASSWD=stackAdminPWord

# Only if you are installing Cassandra.
# Specify Cassandra data center and rack suffix.
# Must use IP addresses for CASS_HOSTS, not DNS names.
# CASS_HOSTS="$IP8:1,1 $IP9:1,1 $IP10:1,1"

# If connecting to existing Cassandra nodes, 
# specify Cassandra IPs.
# Must use IP addresses for CASS_HOSTS, not DNS names.
CASS_HOSTS="$IP8 $IP9 $IP10"

# Specify the Cassandra region.
REGION=dc-1

# Cassandra uname/pword.
# Even if Cassandra authentication is disabled,
# you must still pass values for these properties.
CASS_USERNAME=cassandra    # Default value
CASS_PASSWORD=cassandra    # Default value

# Specify BaaS Cassandra connection information.
# Specify the data center name.
BAAS_CASS_LOCALDC=dc-1    # Default is dc-1.

# For a single data center, specify the same value as BAAS_CASS_LOCALDC.
BAAS_CASS_DC_LIST=dc-1

# Replication is in the form "dataCenterName:#CassandraNodes". 
# For example, for dc-1 with three Cassandra nodes, it is dc-1:3.
BAAS_CASS_REPLICATION=dc-1:3

# Defines the initial contact points for members of the BaaS cluster. 
# Specify the IP address of no more than two Stack nodes. 
BAAS_CLUSTER_SEEDS="dc-1:$IP4,dc-1:$IP5"

# ElasticSearch IPs or DNS names, separated by spaces.
ES_HOSTS="$IP1 $IP2 $IP3"

# API BaaS Stack information.
# Default cluster name is "apigee_baas"
BAAS_USERGRID_CLUSTERNAME="apigee_baas" 

# URL and port of the load balancer for the API BaaS Stack nodes, 
# or IP/DNS and port 8080 of a single Stack node with no load balancer.
BAAS_USERGRID_URL=http://myloadbalancer:8443

# API BaaS Portal information.
# URL and port number of load balancer, if there is one in front of the Portal,
# or the URL and port of the Portal node.  
BAAS_PORTAL_URL="http://$IP7:9000"

# Portal port. Default value is 9000.
BAAS_PORTAL_LISTEN_PORT=9000 

# SMTP information. BaaS requires an SMTP server.
SMTPHOST=smtp.gmail.com
SMTPPORT=465
SMTPUSER=your@email.com
SMTPPASSWORD=yourEmailPassword
SMTPSSL=y
SMTPMAILFROM="My Company <myco@company.com>"

Optional - Install Cassandra: Machine 8, 9, and 10

You can connect API BaaS to the same Cassandra cluster as used by Edge. If you have not installed Edge, you can optionally install Cassandra for use by API BaaS.

The Cassandra cluster can use authentication, or Cassandra authentication can be disabled. See Enable Cassandra authentication for more.

Install the Edge apigee-setup utility on the node using the internet or non-internet procedure. See Install the Edge apigee-setup utility for more.
At the command prompt, run the setup script:
```
/opt/apigee/apigee-setup/bin/setup.sh -p c -f configFile
```
The "-p c" option specifies to install Cassandra.

The configuration file must be accessible or readable by the "apigee" user.

The configuration successfully completes the datastore setup on the node.

Note that JMX is enabled by default for Cassandra. The JMX remote access to Cassandra does not require a password. You can configure Cassandra to use authentication for JMX. For more, see How to Monitor.

Set up Cassandra cron job

If you have to install Cassandra, set up a cron job that uses nodetool to flush for locks to run every hour on every Cassandra node.

If you have multiple Cassandra nodes, offset the cron job on each server by five minutes so that all nodes do not flush at the same time.

The cron job must execute the following command:

/opt/apigee/apigee-cassandra/bin/nodetool -h IP_address flush Apigee_Baas_Locks

where IP_address is the IP address of the Cassandra node.

Install ElasticSearch: Machine 1, 2, and 3

To install the ElasticSearch on its own node:

Install the Edge apigee-setup utility on the node using the internet or non internet procedure. See Install the Edge apigee-setup utility for more.

At the command prompt, run the setup script:

/opt/apigee/apigee-setup/bin/setup.sh -p e -f configFile

The "-p e" option specifies to install ElasticSearch. The configuration file must be accessible or readable by the "apigee" user.

(Optional) If you install ElasticSearch on a standalone node, meaning it is not installed with API BaaS Stack, then adjust the default memory option to increase the memory allocated for ElasticSearch from 4GB to 6GB:
1. Open /opt/apigee/customer/application/elasticsearch.properties in an editor. If this file does not exist, create it.
2. Set the setenv_elasticsearch_max_mem_size property to 6g (the default is 4g):
```
setenv_elasticsearch_max_mem_size=6g
```
3. Save the file.
4. Run the following command:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-elasticsearch restart
```

The configuration successfully completes the setup on the node.

Install API BaaS Stack: Machine 4, 5, and 6

Note: When restarting BaaS Stack nodes, restart them in the same order that they are listed in BAAS_CLUSTER_SEEDS. BAAS_CLUSTER_SEEDS lists at most two of the Stack nodes. After restarting those two nodes in order, you can restart the remaining nodes in any order.

To install the API BaaS Stack on its own node:

Install the Edge apigee-setup utility on the node using the internet or non internet procedure. See Install the Edge apigee-setup utility for more.
At the command prompt, run the setup script:
```
/opt/apigee/apigee-setup/bin/setup.sh -p b -f configFile
```
The "-p b" option specifies to install API BaaS Stack. The configuration file must be accessible or readable by the "apigee" user.

After the installer fetches the correct admin credentials, it installs Tomcat, creates API BaaS keyspaces, and sets up the API BaaS Stack on the server. SMTP is also configured to allow the UI to send password confirmation emails.

Install API BaaS Portal: Machine 7

To install the API BaaS Portal:

Install the Edge apigee-setup utility on the node using the internet or non internet procedure. See Install the Edge apigee-setup utility for more.
At the command prompt, run the setup script:
```
/opt/apigee/apigee-setup/bin/setup.sh -p p -f configFile
```
The "-p p" option specifies to install API BaaS Portal. The configuration file must be accessible or readable by the "apigee" user.

The installer starts the Nginx webserver and then finishes the API BaaS Portal configuration.
Your next step depends on your installation.
1. If you have a load balancer in front of the Portalor Stack nodes, the next section describes how to configure API BaaS for the load balancers.
2. If you do not have a load balancer in front of the Portalor Stack nodes, onboard an organization as described below in Onboarding a new organization.

Make a note of the API BaaS Portal URL. This is the URL you enter into a browser to access the API BaaS Portal user interface.

Configure API BaaS nodes for a Stack or Portal load balancer

If you include a load balancer in front of the Stack or Portal nodes, you have to configure the nodes with the correct URL of the load balancer. For example, the Stack nodes require this information when:

Including a URL in responses in BaaS API requests.
Adding links in email templates when resetting a password, or sending other notifications.
Redirecting users to specific Portal pages.

If you use a load balancer in front of the Stack nodes, set the following property in /opt/apigee/customer/application/usergrid.properties:

usergrid-deployment_usergrid.api.url.base=http://localhost:8080

Replace http://localhost:8080 with the URL of the load balancer. If the load balancer is configure to use TLS, use the HTTPS protocol. You only need to include the port if you are using a non-standard port, meaning something other than port 80 for HTTP and port 443 for HTTPS.

You also have to set the following property in /opt/apigee/customer/application/portal.properties if you use a load balancer in front of the Stack nodes:

baas.portal.config.overrideUrl=http://localhost:8080

Replace http://localhost:8080 with the URL of the load balancer for the Stack.

If you use a load balancer in front of the Portal node, set the following properties in usergrid.properties:

usergrid-deployment_portal.url=http://localhost:9000

Replace http://localhost:9000 with the URL of the load balancer. If the load balancer is configure to use TLS, use the HTTPS protocol. You only need to include the port if you are using a non-standard port, meaning something other than port 80 for HTTP and port 443 for HTTPS.

After editing usergrid.properties and portal.properties:

Configure the Stack node:

/opt/apigee/apigee-service/bin/apigee-service baas-usergrid configure

Restart the BaaS Stack:
```
/opt/apigee/apigee-service/bin/apigee-service baas-usergrid restart
```
Note: When restarting BaaS Stack nodes, restart them in the same order that they are listed in BAAS_CLUSTER_SEEDS. BAAS_CLUSTER_SEEDS lists at most two of the Stack nodes. After restarting those two nodes in order, you can restart the remaining nodes in any order.

If you modified portal.properties, configure the Portal node:

/opt/apigee/apigee-service/bin/apigee-service baas-portal configure

Restart the BaaS Portal:

/opt/apigee/apigee-service/bin/apigee-service baas-portal restart

Onboarding a new organization

Onboarding is the process of creating an organization and organization administrator. After creating the organization and organization administrator, you can log in to the API BaaS Portal UI and make requests to the API BaaS REST API.

When you create an organization, the organization administrator's email address:

Must be different from the system administrator's email address.
Must be unique among all other organizations. That is, you cannot create two organizations with the same email address for the organization administrator. However, after creating the organization, you can add additional administrators that can be duplicated across multiple organizations.

To perform onboarding, use the create_org_and_user.py Python script. Invoking this script with no command-line arguments causes it to prompt you for all information:

python create_org_and_user.py

Alternatively, you can pass any or all options as command line argument. You are prompted for any information that you omit from the command line:

python create_org_and_user.py -o '<org name>'
python create_org_and_user.py -o '<org name>' -a '<new admin email>' -p '<new admin password>'

To create an organization:

Change directory to /opt/apigee/baas-usergrid/bin.
Invoke the create_org_and_user.py Python script.
You are prompted for the BaaS system administrator username and password so that only a sys admin can run it.
Log in to the API BaaS Portal in a web browser using the URL you noted at the end of the API BaaS Portal URL installation. To access the portal, enter the API BaaS Portal URL in the form:
```
http://portalExternalIP:9000/
```
Note: The IP is the external IP address/host name of Portal machine. Ensure that port is open.
When the portal login screen appears, you can either:
- Log in using the organization administrator's username and password.
- Log in using the system administrators administrator's username and password.

Accessing the API BaaS REST API

To access the API BaaS REST API, use a URL in the form:

https://loadBalancerIP:8080/your-org/your-app

In a development environment, you can install all API BaaS components on a single node, meaning you have a single API BaaS Stack. Or, you might have a small environment with a single API BaaS Stack node and no load balancer. In these types of environments, you can make API calls directly to the API BaaS Stack node:

curl -v "http://portalExternalIP:8080/status"

For more information on getting started with API BaaS Portal, see the Apigee documentation at: http://apigee.com/docs/content/build-apps-home.