API BaaS Installation

Edge for Private Cloud v. 4.16.09

Using a Load Balancer

A production installation of API BaaS uses a load balancer between the API BaaS Portal node and API BaaS Stack nodes. When configuring the Portal, you specify the IP address or DNS name of the load balancer, not of the Stack nodes.

As an alternative to a load balancer, you could use round-robin DNS. In this scenario, you create a DNS entry with multiple A records corresponding to BaaS stack IP addresses. During a DNS lookup, the DNS server automatically returns A record values in a round robin fashion.

Connecting to Cassandra

When installing BaaS, you can choose to connect BaaS and Edge to the same Cassandra cluster, or create a separate Cassandra cluster for BaaS. Smaller BaaS installations, meaning those with lower traffic volumes, often share a Cassandra cluster with Edge.

For the high throughput and availability, or to separate Cassandra clusters into different network zones, Apigee recommends that you use separate Cassandra clusters. Separate clusters maximize performance if you are experiencing high traffic loads on BaaS.

Date synchronization

You must have the date/time on all servers synchronized. If not already configured, ‘ntpdate’ utility could serve this purpose, which verifies whether servers are time synchronized. You can use “yum install ntp” to install the utility.

Tomcat security

The API BaaS installer also installs the Apache Tomcat server on all API BaaS Stack nodes, including the Tomcat administrator UI. The installer leaves the default administrator credentials unchanged from admin:admin.

If necessary, you can change these credentials as part of securing Tomcat. For more information, see:

• https://tomcat.apache.org/tomcat-7.0-doc/manager-howto.html
• https://www.owasp.org/index.php/Securing_tomcat

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. 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

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. The portal is so lightweight no additional resources needed for this.
asa	Install all API components on a single node (Cassandra, Elasticsearch, API BaaS Stack, and API BaaS Portal). Use this option for development and testing only, not for production.

Creating a silent configuration file

Shown below is an example silent configuration file for a 10-node API BaaS installation. Edit this file as necessary for your configuration. Use the -f option to setup.sh to include this file.

# 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=stackAdminPWrod

# Only if you are installing Cassandra.
# Specify Cassandra configuration information.
# 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"

# 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.

# 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

# 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

The following table contains additional information about these properties:

Property	Note
CASS_HOSTS	If you are installing Cassandra, specify the Cassandra node IPs (not DNS names) and include the “:dc,ra” modifier that specify the data center and rack of the Cassandra node. For example '192.168.124.201:1,1 = datacenter 1 and rack/availability zone 1, and '192.168.124.204:2,1 = datacenter 2 and rack/availability zone 1.
CASS_USERNAME CASS_PASSWORD	Cassandra user name and password. If Cassandra authentication is disabled, you still have to pass these values. However, the values are ignored.
BAAS_CASS_LOCALDC	The region names must be in the form dc-# where # corresponds to an integer value. For example, dc-1, dc-2, etc. If you are connecting to a Cassandra cluster installed with Edge, you can ask the Edge system administrator for this value. In an Edge single data center installation, the default value is dc-1. If you installed Cassandra as part of installing the API BaaS, then during Cassandra installation you added the “:dc,ra” modifier to the Cassandra IP addresses. The first value "dc" is the data center number. The data center name is the string "dc-" with the data center number as a suffix.
BAAS_CASS_REPLICATION	The format is "dataCenterName:#CassandraNodes". For example, for dc-1 with three Cassandra nodes, it is dc-1:3.
BAAS_USERGRID_URL	In a production environment, this is the URL and port of the load balancer that is in front of the API BaaS Stack nodes, in the form: http://myStackLoadBalancer:8443 In a testing or development environment, where you only have a single API BaaS Stack node, this can be the URL and port number of an API BaaS Stack node, in the form: http://stackIPorDNS:8080 The port number for the API BaaS Stack server is 8080.
BAAS_PORTAL_URL	The URL and port number of the load balancer, if there is one in front of the Portal, in the form: http://myPortalLoadBalancer:8443 If there is no load balancer, the URL and port number of the Portal node, in the form: http://portalIPorDNS:9000 By default, the port number for the API BaaS Portal is 9000.
BAAS_PORTAL_LISTEN_PORT	The port number for the API BaaS Portal server is 9000. If this port is not available, specify a different port. If you are setting BAAS_PORTAL_URL to the URL of the Portal node, the port numbers must be the same for both properties.

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

While you can connect API BaaS to the same Cassandra cluster as used by Edge, Apigee recommends that you use separate clusters.

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

1. 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.
2. 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

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:

1. 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.
2. 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.
3. (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

To install the API BaaS Stack:

1. 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.
2. 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:

1. 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.
2. 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.

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 properties in /opt/apigee/customer/application/usergrid.properties:

usergrid-deployment_swagger.basepath=http://localhost:8080
usergrid-deployment_usergrid.organization.activation.url=http://localhost:8080/management/organizations/%s/activate
usergrid-deployment_usergrid.admin.activation.url=http://localhost:8080/management/users/%s/activate
usergrid-deployment_usergrid.admin.resetpw.url=http://localhost:8080/management/users/%s/resetpw
usergrid-deployment_usergrid.admin.confirmation.url=http://localhost:8080/management/users/%s/confirm
usergrid-deployment_usergrid.user.activation.url=http://localhost:8080/%s/%s/users/%s/activate
usergrid-deployment_usergrid.user.confirmation.url=http://localhost:8080/%s/%s/users/%s/confirm
usergrid-deployment_usergrid.user.resetpw.url=http://localhost:8080/%s/%s/users/%s/resetpw

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_usergrid.view.management.organizations.organization.activate=http://localhost:9000
usergrid-deployment_usergrid.view.management.organizations.organization.confirm=http://localhost:9000
usergrid-deployment_usergrid.view.management.users.user.activate=http://localhost:9000
usergrid-deployment_usergrid.view.management.users.user.confirm=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:

1. Configure the Stack node:
   > /<inst_root>/apigee/apigee-service/bin/apigee-service baas-usergrid configure
2. Deploy the changes to Tomcat:
   > /<inst_root>/apigee/apigee-service/bin/apigee-service baas-usergrid deploy
3. Restart the BaaS Stack:
   > /<inst_root>/apigee/apigee-service/bin/apigee-service baas-usergrid restart
4. If you modified portal.properties, configure the Portal node:
   > /<inst_root>/apigee/apigee-service/bin/apigee-service baas-portal configure
5. Deploy the changes:
   > /<inst_root>/apigee/apigee-service/bin/apigee-service baas-portal deploy
6. Restart the BaaS Portal:
   > /<inst_root>/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:

1. Change directory to /opt/apigee/baas-usergrid/bin.
2. 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.
3. 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.
4. 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.