Developer Services portal installation

Developer Services Portal v. 4.16.05

Follow these steps to install Developer Channel Services portal.

Before proceeding with the installation, make a backup of your entire Drupal web root directory. The default install location is /var/www/html, but you might have changed it at install time. After performing the installation steps described below, you can restore your customizations from the backup.

1. Get the Developer Channel Services bundle

Go to http://community.apigee.com/content/apigee-customer-support and select Login to your Support Portal to request the Developer Channel Services .tar file in one of two ways:

  • Request access to the Edge for Private Cloud download directory.
  • Request a URL to the Developer Channel Services .tar file.

2. Ensure your system meets the system requirements

Before you install the portal, your server must meet the following requirements:

  1. Ensure that you are performing the install on the 64-bit version of a supported version of Red Hat Enterprise Linux, CentOS, or Oracle. See the list of supported versions here.
  2. Ensure that Yum is installed.
  3. (For an installation on a server without an Internet connection) You must first download all necessary files onto a server with an Internet connection as a single .tar.gz file. You then copy that .tar.gz file to the server without an Internet connection to perform the install.
    1. Log in to a server with an Internet connection as root or as superuser.
    2. Create a directory for the install files, such as portal_tar.
    3. CD to the new directory and download the Developer Channel Services DeveloperServices_x.y.z.tar file, where x.y.z corresponds to the portal version number.
    4. Extract the contents of the Developer Channel Services .tar file by using the command:
      > tar -xvf <tar file>
    5. CD to DeveloperServices-4.x.y.z.
    6. Create the portal .tar.gz file by using the command:
      > ./non-networked-install.sh

      That command downloads all the necessary files and them into a single .tar.gz file. You then copy that .tar.gz file to your server that has no Internet connection to complete the install.
  4. Test your connection to the Edge management server by executing the following cURL command from a command prompt on the portal server:
    > curl -u {EMAIL}:{PASSWORD} https://{hostname}:8080/v1/organizations/{ORGNAME}

    Where EMAIL and PASSWORD are the email address and password of the administrator for ORGNAME.

    Make sure to specify the hostname and port number specific to your installation of Edge. Port 8080 is the default port used by Edge. If you are connecting to an organizationi n the cloud, then the request URL is:
    https://api.enterprise.apigee.com/v1/organizations/{ORGNAME}

    If successful, this command returns a response similar to the following:
    {
    "createdAt" : 1348689232699,
    "createdBy" : "USERNAME",
    "displayName" : "cg",
    "environments" : [ "test", "prod" ],
    "lastModifiedAt" : 1348689232699,
    "lastModifiedBy" : "foo@bar.com",
    "name" : "cg",
    "properties" : {
    "property" : [ ]
    },
    "type" : "trial"
    }

3. Install Developer Channel Services using the automated install script

Use the following procedure to install the portal by using the automated install script. This procedure works for servers with or without an external Internet connection.

  1. Log in to the server as root or as superuser.
  2. Create a directory for the install files, such as portal.
  3. On a server with an Internet connection:
    1. CD to the new portal directory and download the Developer Channel Services DeveloperServices_x.y.z.tar file, where x.y.z corresponds to the portal version number.

      You can download a file from the link sent to you by Apigee in a browser or by copying it and then adding it to the following cURL command:
      > curl -kOL <paste link here>
    2. Extract the contents of the Developer Channel Services .tar file by using the command:
      > tar -xvf <tar file>
    3. CD to DeveloperServices-4.x.y.z.
    4. Run the install script by using the following command:
      > ./networked-install.sh
  4. On a server without an Internet connection:
    1. Copy the .tar.gz file that you created above in the section 2. Ensure your system meets the system requirements.
    2. Extract the contents of the .tar.gz file by using the command:
      > tar -xvf <tar file>
    3. CD to the directory created by the tar command.
    4. Set the permissions on the install-from-rpm-bundle.sh script:
      > chmod 755 install-from-rpm-bundle.sh
    5. Run the install-from-rpm-bundle.sh script by using the command:
      > ./install-from-rpm-bundle.sh
  5. Answer the prompts.
  6. After the installation completes, navigate to the server URL in a browser, such as:
    http://localhost. Or, if you have a specific IP or DNS configured, go to http://IP_address or http://DNS_name.

    You are redirected to the Apigee profile Database configuration page.

    Note: Typically, you will have already configured a hostname and registered it with your DNS server so that you do not have to use http://localhost.
  7. Configure the connection to MySQL. If MySQL is on a remote machine, expand the Advanced Options section and enter the connection information to that machine, then Select Save and continue.
  8. Configure the connection to the Apigee Endpoint by entering the following information, and then select Save:
    For more information on these values, see "Information Required Before You Start the Install" at Developer Services portal requirements.
    1. Dev Portal Org
    2. Dev Portal Endpoint URL
    3. Endpoint Authenticated User
    4. Authenticated Users' Password
  9. When prompted, select the Install Sample SmartDocs WADL button to install the sample SmartDocs WADL. If you skip this step, then the example SmartDocs API will not appear on your portal.
    Note: If your portal connects to an installation of Apigee Edge for Private Cloud, and that installation of Edge has no external internet connection, then you must perform additional configuration of the SmartDocs module before you can use SmartDocs. For more information on SmartDocs, see http://apigee.com/docs/developer-services/content/using-smartdocs-document-apis.
  10. Configure the SMTP Server Settings. Apigee requires that you configure an SMTP server to send email messages from the portal.
    For more information, see http://apigee.com/docs/developer-services/content/configuring-email.
  11. Configure the administrator user by entering the following information, and then select Save. Note that Drupal create an admin user named 'admin' by default, so do not use 'admin' as the username.
    If you skip this step, you can still use Drush to create an administrator as described below in 4. Create an admin user.
    1. Developer's first and last name
    2. Developer's portal username
    3. Password
    4. Email address
  12. After the installation completes, set the permissions on the settings.php file:
    > chmod 640 /var/www/html/sites/default/settings.php
  13. Navigate to the portal home page at http://localhost/ or to the DNS name of your portal.
  14. Log in to the portal using the administrator credentials.

4. Create an admin user

Use Drush to create an administrative user for your Developer Channel Services installation. Drupal automatically creates an admin user named 'admin' by default, so do not use 'admin' as the username.

  1. CD to your drupal_root/sites/default directory. The standard location for the Drupal root directory is /var/www/html:
    > cd <drupal_root>/sites/default
  2. Ensure that you have write permissions on the private Drupal files:
    > drush vget file_private_path

    This command returns the path to the private Drupal files, for example:
    file_private_path: 'sites/default/private'

    Corresponding to /var/www/html/sites/default/private/. Use the following command to ensure that this directory is writable by the owner and the group:
    chmod -R g+w dirPathAndName
    chmod -R o+r dirPathAndName
  3. Enter the following commands to create an admin user, replacing the commands in “< >” with your values:
    > drush user-create <username> --mail="<email-address>" --password="<password>"
    > drush user-add-role Administrator <username>
  4. Log in to the developer portal as an admin by using the username and password specified above.

5. Set the MySQL root password

If you installed MySQL as part of the portal installation, the installation script leaves the MySQL root password set to its default value, which is blank.

Use the following command to set the root password:

> mysqladmin -u root password NEWPASSWORD

If you have previously set the root password and want to change it, use the following command:

> mysqladmin -u root -p'OLDPASSWORD' password NEWPASSWORD

You must also update the password in the /var/www/html/sites/default/settings.php file.

6. Ensure that the Update manager module is enabled

To receive notifications of Drupal updates, ensure that the Drupal Update manager module is enabled. From the Drupal menu, select Modules and scroll down to the Update manager module. If it is not enabled, enable it.

Once enabled, you can see the available updates by using the Reports > Available Updates menu item. You can also use the following Drush command:

> drush pm-info update

Use the Reports > Available Updates > Settings menu item to configure the module to email you when updates are available and to set the frequency for checking for updates.

7. Optional - Deploying on a production server

If you are deploying the portal on a production server, you should perform additional security steps, including:

  1. Run the following script to secure your MySQL installation:
    > /usr/bin/mysql_secure_installation

    This script sets the root password and gives you the option to restrict root access to just the localhost and to remove the test databases and anonymous user created by default. Running this script is strongly recommended for production servers.
  2. If required by your corporate policies, enable and configure SELinux.

8. Optional - Configure the Apache Solr search engine

By default, the Drupal modules that connect to the Apache Solr search engine are disabled when you install the portal. Most portals use the internal Drupal search engine, and therefor do not require the Drupal Solr modules.

If you decide to use Solr as your search engine, you must install Solr locally on your server and then enable and configure the Drupal Solr modules on the portal.

To enable the Drupal Solr modules:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Modules in the Drupal menu.
  3. Enable the Apache Solr Framework module and the Apache Solr Search module.
  4. Save your changes.
  5. Configure Solr as described at https://drupal.org/node/1999280.

9. Optional - Install mod_ssl to support HTTPS

The mod_ssl module is used by the Apache HTTP Server to serve web pages over HTTPS. If you want to use HTTPS, use the following command to install mod_ssl:

> yum install mod_ssl

For more information on configuring the portal to use SSL, see http://apigee.com/docs/developer-services/content/using-ssl-portal.

10. Optional - Install SmartDocs

SmartDocs lets you document your APIs on the Developer Services portal in a way that makes the API documentation fully interactive. However, to use SmartDocs with the portal, you must first install SmartDocs on Edge.

  • If you are connecting the portal to an Edge Cloud installation, SmartDocs is already installed and no further configuration is necessary.
  • If you are connecting the portal to an Edge for Private Cloud installation, you must ensure that SmartDocs is installed on Edge. For more on installing Edge and SmartDocs, see Install SmartDocs.

For more information on SmartDocs, see Using SmartDocs to document APIs.

11. What next?

Your next steps after you install the Developer Services portal are to configure and customize it for your specific requirements. The documentation on the Apigee web site contains all of the information on configuring, styling, and managing a portal. Access the documentation at http://apigee.com/docs/developer-services/content/what-developer-portal.

The following table lists some of the most common tasks that you perform after installation, and includes links to the Apigee documentation where you can find more information:

Task

Description

Customizing the theme

The theme defines the appearance of the portal, including colors, styling, and other visual aspects.

Customize the appearance

The home page includes the main menu, welcome message, header, footer, and title.

Add and manage user accounts

The registration process controls how new developers register an account on the portal. For example, do new developers get immediate access to the portal, or do they have to be verified by an administrator. This process also controls how a portal administrator is notified when a new account is created.

Configuring email

The portal sends emails in response to certain events. For example, when a new developer registers on the portal and when a developer loses their password.

Add and manage user accounts

Add a Terms & Conditions page that developers must accept before being allowed to access the portal.

Add and manage user accounts

The portal implements a role-based authorization model. Before allowing developers to register, define the permissions and roles used by the portal.

Add blog and forum posts

The portal has built-in support for blogs and threaded forums. Define the permissions required to view, add, edit, and delete blog and forum posts.

Ensure you are doing database backups

Ensure that you are backing up the Drupal database. Note that because every installation is different, it is up to you to determine how best to back up the database.

Set up a hostname

If you do not set up a hostname in your DNS server, you can always access the site via the server’s IP address. If you want to use a hostname, you can configure DNS for the server, which should work correctly without any other configuration on a basic setup.

If you set up a load balancer or are getting incorrect URLs on your site for some other reason, you can set $base_url in the Dev Portal settings.php file, which by default is located in the /var/www/html/sites/default directory.