> [!CAUTION]
> **Caution:** This documentation covers Edge for Private Cloud 4.18.05, which is no longer supported. Google does not provide security patches, bug fixes, or technical support for this version. The current supported version is 4.54.00. See the [Edge for Private Cloud documentation](https://docs.apigee.com/private-cloud/latest/overview) for the current version, or [All versions](https://docs.apigee.com/private-cloud/versions) to compare releases.

*Edge for Private Cloud v4.18.05*

You can create an organization, environment, and virtual host on the command line in a single
command, or you can create each one separately. In addition, you can use the
[management API](https://apidocs.apigee.com/api-reference/content/api-reference-getting-started)
to perform many of these actions.
**Video:**Watch a short video for an overview of Apigee Organization setup and configuration.
<iframe allowfullscreen frameborder="0" height="315" src="https://www.youtube.com/embed/HkVp2yPRb34" width="560"></iframe>

## Creating an organization,
environment, and virtual host at the same time

Before you create an API proxy on Apigee Edge, you must create at least one organization and,
within each organization, one or more environments and virtual hosts.

> [!NOTE]
> **Note:** When creating a virtual host, you specify the Router port used by the virtual host.
>
> For example, port 9001. By default, the Router runs as the user "apigee"
> which does not have access to privileged ports, which are typically ports 1024 and below.
> To create a virtual host that binds the Router to a protected port, you must configure the
> Router to run as a user with access to those ports.
>
> For more information, see [Setting up a virtual host](https://docs.apigee.com/private-cloud/v4.18.05/setting-virtual-host).

Typically, organizations and environments are created together. To simplify the process, use
the `apigee-provision` utility. Invoke it from the command line on the Edge Management
Server:

```
/opt/apigee/apigee-service/bin/apigee-service apigee-provision setup-org -f configFile
```

Where <var translate="no">configFile</var> is the path to a configuration file that looks similar to the
following:

```
# Set Edge sys admin credentials.
ADMIN_EMAIL=your@email.com
APIGEE_ADMINPW=admin_password  # If omitted, you are prompted for it.
NEW_USER="y"
USER_NAME=orgAdmin@myCo.com
FIRST_NAME=foo
LAST_NAME=bar
USER_PWD="userPword"
ORG_NAME=example  # lowercase only, no spaces, underscores, or periods.
ENV_NAME=prod  # lowercase only
VHOST_PORT=9001
VHOST_NAME=default
VHOST_ALIAS="$IP1: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.
# Optionally set the base URL displayed by the Edge UI for an
# API proxy deployed to the virtual host.
# VHOST_BASEURL="http://myCo.com"
# AXGROUP=axgroup-001 # Default value is axgroup-001
```

> [!NOTE]
> **Note:** For TLS/SSL configuration, see [Keystores and
> Truststores](https://docs.apigee.com/api-platform/system-administration/keystores-and-truststores) and [Configuring TLS access to an API
> for the Private Cloud](https://docs.apigee.com/api-platform/system-administration/creating-virtual-host) for more information on creating the JAR file, and other aspects of configuring TLS/SSL.

When setting up an organization, the `setup-org` script does the following:

- Creates the organization.

  > [!NOTE]
  > **Note**: You cannot rename an organization after you create it.

- Associates the organization with the "gateway" pod. You cannot change this.
- Adds the specified user as the organization admininstrator. If the user does not exist, you can create one.
- Creates one or more environments.
- Creates one or more virtual hosts for each environment.
- Associates the environment with all Message Processor(s).
- Enables analytics.

By default, the maximum length of the organization name and environment name is 20 characters
when using the `apigee-provision` utility. This limit does not apply if you use the
Edge API directly to create the organization or environment.

> [!NOTE]
> **Note:** Rather than using the `apigee-provision` utility, you can use a set of additional scripts, or the Edge API itself, to create and configure an organization. For example, use thee scripts to add an organization and associate it with multiple pods. The following sections describe those scripts and APIs in more detail.

## Create an organization

Use the `create-org` command to create an organization, as the following example
shows:

```
/opt/apigee/apigee-service/bin/apigee-service apigee-provision create-org -f configFile
```

This script creates the organization, but does not add or configure the environments and
virtual hosts required by the organization to handle API calls.

> [!NOTE]
> **Note:** You cannot rename an organization after you create it.

The configuration file contains the name of the organization and the email address of the organization
admin. The characters you can use in the `name` attribute are restricted to
`a-z0-9\-$%`. Do not use spaces, periods or upper-case letters in the name:

```
APIGEE_ADMINPW=admin_password  # If omitted, you are prompted for it.
ORG_NAME=example  # lowercase only, no spaces, underscores, or periods.
ORG_ADMIN=orgAdmin@myCo.com
```

The `create-org` script:

- Creates the organization.
- Associates the organization with the "gateway" pod.
- Adds the specified user as the organization admininstrator. The user must already exist; otherwise the script issues an error.

> [!NOTE]
> **Note:** You cannot create two organizations with the same name. In that case, the second create will fail, like this:
>
> ```
> <Error>
>   <Code>organizations.OrganizationAlreadyExists</Code>
>   <Message>Organization : test already exists</Message>
>   <Contexts/>
> </Error>
> ```

### Create an organization by using
API calls

You can use the following API calls to create an organization. The first call creates the
organization:

```
curl -H "Content-Type:application/xml" -u sysAdminEmail:adminPasswd \
  -X POST http://management_server_IP:8080/v1/organizations \
  -d '<Organization name="org_name" type="paid"/>'
```

The next call associates the organization with a pod:

```
curl -H "Content-Type:application/x-www-form-urlencoded" \
  -u sysAdminEmail:adminPasswd -X POST \
  http://management_server_IP:8080/v1/organizations/org_name/pods \
  -d "region=default&pod=gateway"
```

The final call adds an existing user as the org admin for the org:

```
curl -H "Content-Type:application/xml" -u sysAdminEmail:adminPasswd \
  -X POST http://<ms-ip>:8080/v1/organizations/org_name/users/user_email/userroles/ \
  -d '<Roles><Role name="orgadmin"/></Roles>'
```

> [!NOTE]
> **Note:** Currently, Apigee Edge for Private Cloud supports the roles -- orgadmin, opsadmin, user, and businessuser, all having a default permission of full access to entities (APIs, API products, apps, developers, and reports) in an Apigee organization. Depending on the customer's needs, you can customize the pre-defined or configure more complex roles and permissions using RBAC API. See [http://apigee.com/docs/api/user-roles](https://docs.apigee.com/api/user-roles).
>
> Note that the `readonlyadmin` role is available in the Cloud only.

If the user does not exist, you can use the following call to create the user as described in
[Adding a user](https://docs.apigee.com/private-cloud/v4.18.05/managing-users-roles-and-permissions#addingauser).

## Create an environment

Use the `add-env` script to create an environment in an existing organization:

```
/opt/apigee/apigee-service/bin/apigee-service apigee-provision add-env -f configFile
```

This config file contains the information necessary to create the environment and virtual
host:

```
APIGEE_ADMINPW=admin_password  # If omitted, you are prompted for it.
ORG_NAME=example  # lowercase only, no spaces, underscores, or periods.
ENV_NAME=prod  # lowercase only
VHOST_PORT=9001
VHOST_NAME=default
VHOST_ALIAS="$IP1: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. 
# Optionally set the base URL displayed by the Edge UI for an
# API proxy deployed to the virtual host.
# VHOST_BASEURL="http://myCo.com"
# AXGROUP=axgroup-001 # Default value is axgroup-001
```

> [!NOTE]
> **Note:** For TLS/SSL configuration, see [Keystores and
> Truststores](https://docs.apigee.com/api-platform/system-administration/keystores-and-truststores) and [Configuring
> TLS access to an API for the Private Cloud](https://docs.apigee.com/api-platform/system-administration/creating-virtual-host) for more information on creating the JAR file, and other aspects of configuring TLS/SSL.

The `add-env` command:

- Creates the environment.
- Creates a single virtual host for the environment.
- Associates the environment with all Message Processor(s) in the pod associated with the organization containing the environment.
- Enables analytics

  > [!NOTE]
  > **Note**: If you enable analytics for one environment in an organization, you must enable analytics for all environments in the organization.

### Create an environment by using
API calls

Alternatively, you can use the following API calls to create an environment. The first call
creates the environment:

```
curl -H "Content-Type:application/xml" -u sysAdminEmail:adminPasswd \
  -X POST http://management_server_IP:8080/v1/organizations/org_name/environments \
  -d  '<Environment name="env_name"/>'
```

> [!NOTE]
> **Note:** The characters you can use in the name attribute are restricted to: a-zA-Z0-9._\\-$ %.

The next call associates the environment with a Message Processor. Make this call for each
Message Processor that you want to associate with the environment:

```
curl -H "Content-Type:application/x-www-form-urlencoded" \
  -u sysAdminEmail:adminPasswd -X POST \
  http://management_server_IP:8080/v1/organizations/org_name/environments/env_name/servers \
  -d "action=add&uuid=uuid"
```

Where <var translate="no">uuid</var> is the UUID of Message Processor. You can obtain the UUID by using the
command:

```
curl http://Message_Processor_IP:8082/v1/servers/self
```

Where <var translate="no">Message_Processor_IP</var> is the IP address of the Message Processor.

The next API call enables Analytics for a given environment. It validates the existence of
Qpid and Postgres Servers in the PODs of all datacenters. Then it starts the Analytics onboarding
for the given organization and environment.

> [!NOTE]
> **Note:** Rather than use the following API call, use the following command to enable Analytics:
>
> ```
> /opt/apigee/apigee-service/bin/apigee-service apigee-provision enable-ax -f configFile
> ```

This config file contains:

```
ORG_NAME=orgName  # lowercase only, no spaces, underscores, or periods.
ENV_NAME=envName  # lowercase only
```

> [!NOTE]
> **Note:** If you enable analytics for one environment in an organization, you must enable analytics for all environments in the organization:
>
> ```
> curl -H "Content-Type:application/json" -u sysAdminEmail:adminPasswd \
>   -X POST http://management_server_IP:8080/v1/organizations/org_name/environments/env_name/analytics/admin -d "@sample.json"
> ```

Where sample.json contains the following:

```
{
  "properties" : {
    "samplingAlgo" : "reservoir_sampler",
    "samplingTables" : "10=ten;1=one;",
    "aggregationinterval" : "300000",
    "samplingInterval" : "300000",
    "useSampling" : "100",
    "samplingThreshold" : "100000"
  },
  "servers" : {
    "postgres-server" : [ "1acff3a5-8a6a-4097-8d26-d0886853239c", "f93367f7-edc8-4d55-92c1-2fba61ccc4ab" ],  
    "qpid-server" : [ "d3c5acf0-f88a-478e-948d-6f3094f12e3b", "74f67bf2-86b2-44b7-a3d9-41ff117475dd"] 
  }
}
```

The `postgres-servers` property
contains a comma-separated list of the Postgres UUIDs, and the `qpid-server` property contains the Qpid UUIDs.
If you need to obtain these UUIDs, use the following commands.

For Qpid, run the following command:

```
curl -u sysAdminEmail:password http://management_server_IP/v1/servers?pod=central
```

The output of this command is a JSON object. For each Qpid server, you will see output in the
form:

```
"type" : [ "qpid-server" ],
"uUID" : "d3c5acf0-f88a-478e-948d-6f3094f12e3b"
```

For Postgres, run the following command:

```
curl -u sysAdminEmail:passwor http://management_server_IP/v1/servers?pod=analytics
```

For each Postgres server, you will see output in the form:

```
"type" : [ "postgres-server" ],
"uUID" : "d3c5acf0-f88a-478e-948d-6f3094f12e3b"
```

## Create a virtual host

You can create a virtual host in an existing environment in an organization. Often an
environment supports multiple virtual hosts. For example, one virtual host might support the HTTP
protocol, while another virtual host in the same environment supports the encrypted HTTPS
protocol.

Use the following API call to create additional virtual hosts, or to create a virtual host for
an environment with no virtual host:

```
curl -H "Content-Type:application/xml" -u sysAdminEmail:adminPasswd \
  -X POST http://management_server_IP:8080/v1/organizations/org_name/environments/env_name/virtualhosts \
  -d '<VirtualHost name="default"> \
    <HostAliases> \
      <HostAlias>myorg-test.apigee.net</HostAlias> \
    </HostAliases> \
    <Interfaces/> \
    <Port>443</Port> \
  </VirtualHost>'
```

> [!NOTE]
> **Note:** The characters you can use in the name attribute are restricted to `a-zA-Z0-9._\-$%`.

For a complete description of creating a virtual host, including creating a secure virtual
host that uses TLS/SSL over HTTPS, see [Configuring TLS access to an API
for the Private Cloud](https://docs.apigee.com/api-platform/system-administration/creating-virtual-host).