Onboard an organization

To onboard an organization, you must create an onboarding configuration file and then pass it to the setup-org command. Each of these steps is described in the sections that follow.

For information on using the management API to onboard an organization, see Creating an organization, environment, and virtual host.

Create an onboarding configuration file

This section includes a sample configuration file for onboarding an organization with setup-org.

Copy the following example and edit as necessary for your organization:

IP1=192.168.1.1

# Specify the IP or DNS name of the Management Server.
MSIP="$IP1"

# Specify the Edge sys admin credentials.
ADMIN_EMAIL="admin@email.com"
APIGEE_ADMINPW=admin_password  # If omitted, you are prompted for it.

# Specify organization name.
ORG_NAME=myorg  # lowercase only, no spaces, underscores, or periods.

# Specify the organization administrator user.
# Either specify an existing user, or specify the information
# necessary to create a new user.
# Do not use the sys admin as the organization administrator.
#
# Create a new user for the organization administrator.
NEW_USER="y"
# New user information if NEW_USER="y".
USER_NAME=new@user.com
FIRST_NAME=new
LAST_NAME=user
# Org admin password must be at least 8 characters long and contain one uppercase
# letter, one lowercase letter, and one digit or special character
USER_PWD="newUserPword"
ORG_ADMIN=new@user.com
#
# Or, specify an existing user as the organization admin,
# omit USER_NAME, FIRST_NAME, LAST_NAME, USER_PWD.
# NEW_USER="n"
# ORG_ADMIN=existing@user.com

# Specify environment name.
ENV_NAME=prod  # lowercase only

# Specify virtual host information.
VHOST_PORT=9001
VHOST_NAME=default

# If you have a DNS entry for the virtual host.
VHOST_ALIAS=myorg-test.apigee.net

# If you do not have a DNS entry for the virtual host,
# specify the IP and port of each router as a space-separated list:
# VHOST_ALIAS="firstRouterIP:9001 secondRouterIP:9001"

# Optionally configure TLS/SSL for virtual host.
# VHOST_SSL=y     # Set to "y" to enable TLS/SSL on the virtual host.
# KEYSTORE_JAR=   # JAR file containing the cert and private key.
# KEYSTORE_NAME=  # Name of the keystore.
# KEYSTORE_ALIAS= # The key alias.
# KEY_PASSWORD=   # The key password, if it has one.

# Specify the analytics group.
# AXGROUP=axgroup-001 # Default name is axgroup-001.

Note that:

For VHOST_ALIAS, if you already have a DNS record that you will use to access to the virtual host, specify the host alias and optionally the port, for example, "myapi.example.com". If you do not yet have a DNS record, you can use the IP address of the Router.

For more on how to configure the virtual host, see Setting up a virtual host.
For TLS/SSL configuration, see Keystores and Truststores and Configuring TLS access to an API for the Private Cloud for more information on creating the JAR file, and other aspects of configuring TLS/SSL.
For more information on configuring virtual hosts, see Configuring TLS access to an API for the Private Cloud.
You cannot create two organizations with the same name. In that case, the second create will fail.

Execute setup-org

After you created the onboarding configuration file, you pass it to the setup-org script to perform the onboarding process. You must run the script on the Management Server node.

When onboarding an organization, the setup-org script does the following:

Creates a new organization.
Creates an environment.
Creates a virtual host for the environment.
Sets the specified user as the organization admin. Note that:
- You can use an existing user or create a new one for the organization admin.
- The organization admin must not be the same as the sys admin.
Associates the organization with the "gateway" pod. (This is the default and cannot be changed.)
Associates the environment with all Message Processor(s).
Enables analytics.

To execute setup-org:

Install apigee-provision on the Management Server node:

/opt/apigee/apigee-service/bin/apigee-service apigee-provision install

Run the setup-org script on the Management Server node and point it at the configuration file that you created in Create an onboarding configuration file:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-provision setup-org -f configFile
```
The configuration file must be readable by the "apigee" user.
Verify that you have successfully onboarded an organization. One way to do this is to log into the UI by requesting the following URL in a browser:
```
http://IP_address:9000/login
```
Where IP_address is the IP address of the server on which you installed the Edge UI.

For additional verification steps, see Verify the onboarding.
Create your first proxy!

Verify the onboarding

On completion of onboarding, verify the status of the system by issuing the following curl commands on the Management Server node:

Check for user and organization status on the Management Server by executing the following commands:

curl -u adminEmail:admin_passwd http://localhost:8080/v1/users
curl -u adminEmail:admin_passwd http://localhost:8080/v1/organizations
curl -u adminEmail:admin_passwd http://localhost:8080/v1/organizations/org_name/deployments

Check analytics by executing the following command:

curl -u adminEmail:admin_password http://localhost:8080/v1/organizations/org_name/environments/env_name/provisioning/axstatus

Check the PostgreSQL database status by executing the following commands on Node 2 (as shown in the installation topologies):
```
psql -h /opt/apigee/var/run/apigee-postgresql -U apigee apigee
```
At the command prompt, enter the following command to view the analytics table for your organization:
```
\d analytics."org_name.env_name.fact"
```
Use the following command to exit psql:
```
\q
```
Access the Apigee Edge UI using a web browser. Remember that you already noted the management console URL at the end of the installation.
1. Launch your preferred browser and enter the URL of the Edge UI. It looks similar to the following, where the IP address is for Node 1 (as shown in the installation topologies), or whichever node on which you installed the UI for alternative configurations:
```
http://192.168.56.111:9000/login
```
  9000 is the port number used by the UI.
  
  If you are starting the browser directly on the server hosting the Edge UI, then you can use a URL in the form:
```
http://localhost:9000/login
```
  Note: Ensure that port 9000 is open. If you are using a service such as Google Cloud Engine, you may need to modify the firewall rules so that you can access the Apigee services via a browser.
2. On the console login page, specify the Apigee system admin username/password.
  Note: This is the global system administrator password that you set during the installation.
Sign up for a new Apigee user account and use the new user credential to login. On the console sign in page, click the Sign In button.

The browser redirects to http://192.168.56.111:9000/platform/#/org_name/ and opens a dashboard that lets you configure the organization that you created (if you logged in using Apigee admin credentials).

Create your first proxy

After you have onboarded a new organization and verified that the onboarding process was successful, you can now create your first proxy. For more information, see Build your first API proxy.

Other resources your might find helpful include: