Working with Pantheon

Apigee uses Pantheon, a website management service, for hosting cloud-based versions of the Developer Services portal. Pantheon is designed to work with Drupal to let you develop, test, and publish your portal in a secure environment. The following sections describe how to use Pantheon to develop and manage your portal.

Acquia is provided as an alternative to customers that need to host the Developer Portal in the EU only due to EU regulations. Apigee uses Pantheon for hosting in the US. For more information about Acquia, see Working with Acquia.

Accessing the Pantheon dashboard

When Apigee sends you the URL of your portal, you also receive the URL of the Pantheon Dashboard: https://dashboard.getpantheon.com/.

When you first log in to the Pantheon dashboard, you land on the Sites page, shown below:

From the dashboard, you can access your site, configure your account, and perform other operations.

Select the image of your site (for example apigeedocs) to open the dashboard for that site:

Managing your environments

On the Pantheon dashboard there are three environments listed across the top of the page: Dev, Test, and Live. Each are described in the following table.

Environment

Description

Dev

The Dev environment is connected to your Git repo. Any changes you push to Git show up immediately in the Dev environment.

The URL to this site is in the form below, where org_name is the name of your organization:

http://dev-{org_name}.devportal.apigee.io/

Test

The Test environment is for testing your latest code with a copy of data from the Live environment. This environment is where you test code changes before pushing it to the Live environment.

The URL to this site is in the form below, where org_name is the name of your organization:

http://test-{org_name}.devportal.apigee.io/

Live

The Live environment is your production environment that you make accessible to your customers.

The URL to this site is in the form below, where org_name is the name of your organization:

http://live-{org_name}.devportal.apigee.io/

Developing your portal content

The following sections describe how to develop your portal content.

In addition, refer to the following sections for more details about customizing your portal.

If you want to...

You can

More Information

Change the site’s look and feel

Basic - Use the Appearance menu entry on the portal site to make changes, such as modify the logo and site colors.

See Customize the appearance:

Advanced - To make modifications to the complete look and feel of the site, extend the Apigee Responsive theme.

See Customizing the theme

Change the behavior of site functionality

Basic - Use the admin settings on the portal to change/configure the way the site behaves.

See the Apigee documentation starting here

Advanced - Create a custom module to change any behavior of the site.

See Creating custom modules in the Drupal documentation

Overview of the Git repository

The Git repository for your Drupal code contains all of your portal code and is organized using the following structure.

Note: Only modify content within the /sites/all directory. If you modify content that is outside of the /sites/all directory, you will have issues when upgrading to new versions and may experience merge conflicts when checking in changes to Git.

Folder in Git repo

Description

/profiles/apigee

Apigee maintained modules and themes, including:

  • /profiles/apigee/modules/contrib: Drupal contrib modules maintained by Apigee
  • /profiles/apigee/themes/contrib: Drupal contrib themes maintained by Apigee
  • /profiles/apigee/modules/custom: Custom modules created by Apigee
  • /profiles/apigee/themes/custom: Custom themes created by Apigee

Note: Do not modify content in the /profiles/apigee directory or you will have issues when upgrading to new versions and may experience merge conflicts when checking in changes to Git. For Drupal best practices, see Never hack core.

/sites/all

Your custom Drupal modules and themes. For information about managing the content in this folder, see Adding custom modules and themes and Overriding Drupal profile modules and themes.

Note: Only modify content within the /sites/all directory.

Accessing your code

In order to access your code repository in Git, you need to perform the tasks described in the following sections:

See also How do I access the Drupal 7 developer portal source code?

Enabling SSH access to your server

Before you can use Git to manage your Drupal code, you must enable SSH to access your server by uploading an SSH key to Pantheon.

To enable SSH access to your server:

  1. Log in to Pantheon at https://dashboard.getpantheon.com/.
  2. On the dashboard, select Account.
  3. Select SSH Keys in the menu on the left.
  4. Add your key and select Add key.
    If you need help, select the Learn how to generate an SSH Key link.

Accessing your code repository in Git

Note: See Overview of the Git repository for an overview of the Git repository structure.

To access your code repository in Git:

  1. Log into the Pantheon dashboard.
  2. From the main Sites page, select the icon for your portal.
  3. The URL of the Git repo appears on the page to the right of Connection Mode, as shown in the previous figure.
  4. Copy the URL of your Git repo and clone it to your local development environment by using the command:
    > git clone gitURL sitename
    For example:
    > git clone ssh://codeserver.dev.12@codeserver.dev.12.drush.in:2222/~/repository.git devportal

Any code changes that you push to the Git repo appear immediately in the Dev environment of your portal.

Deploying code to your portal environments

To code to your portal environments:

  1. Push your code updates to Git, which immediately updates the Dev environment.
  2. Log in to Pantheon and select your site.
  3. Select the Dev environment.
  4. Select </>Code in the left-hand menu to see a message about your code change in the Commit Log:
  5. Select the Test environment at the top of the page.
    1. If you have not yet uploaded Dev to Test, you are prompted to do it now.
    2. If you already have a Test environment, a message appears indicating that there is a commit from Dev ready to deploy:
  6. If you have already pushed a site to the Live environment, you can optionally select the third checkbox to copy the live database and any files uploaded by developers to Test from Live. This is useful if you want to test your code changes against the most recent data available on Live.
  7. Select the Deploy Code from Development button.
  8. Test the portal in the Test environment.
  9. Make any code fixes to the Dev environment and push files again to Test for testing.
  10. When testing completes, select the Live environment at the top of the page.
    1. If you have not yet uploaded Test to Live, you are prompted to do it now.
    2. If you already have a Live environment, a message appears indicating that there is a commit from Test ready to deploy. Deploy those changes in the same way you deployed them to Test from Dev. When you are done testing, push the code to the Live environment.

Learn more:

Adding custom modules and themes

You can expand the functionality of the portal by adding your own custom modules and themes to the folders listed in the following table.

Note: Only modify content within the /sites/all directory. If you modify content that is outside of the /sites/all directory, you may experience merge conflicts when checking in changes to Git.

Module/Theme Folder in Git repository More information (Drupal documentation)
Custom modules sites/all/modules/custom Creating custom modules
Custom themes sites/all/themes Customizing the theme
Theming Drupal 7

After adding the custom module or theme in the Dev environment, you can deploy it to Test for testing, and then to the Live environment for production, as described in Deploying code to your portal environments.

Overriding Drupal profile modules and themes

The modules and themes in the following directories override the Drupal profile modules and themes maintained and distributed by Apigee in /profiles/apigee. See Overview of your Git repository.

For example, you may want to override a module in the Apigee Drupal distribution in the following scenarios:

  • You want to use a different version of a particular module.
  • You want implement a security update before the next scheduled Apigee release.
Module/Theme Folder in Git repository More information (Drupal documentation)
Drupal Contributed modules

sites/all/modules/contrib

Note: Modules stored anywhere under /sites/all/modules will override the Apigee Drupal distribution modules.

Contributed modules

Note: Drupal contributed modules in this directory override equivalent modules maintained and distributed by Apigee in /profiles/apigee/modules. Remove any duplicate modules that you added to this folder if you wish to use the Apigee maintained Drupal profile modules.

Drupal Contributed themes sites/all/themes Contributed themes

Note: Drupal contributed themes in this directory override equivalent modules maintained and distributed by Apigee in /profiles/apigee/themes. Remove any duplicate modules that you added to this folder if you wish to use the Apigee maintained profile themes.

About the settings.php file

The Drupal settings.php is committed into the Apigee Drupal Developer Portal upstream Git repo. If you want to make changes to sites/default/settings.php file, do not edit the file directly. Instead, create a file named sites/default/settings.local.php and put your custom code there. The sites/default/settings.local.php is included by the settings.php file.

For example, when setting up a custom domain for a live site following instructions provided by Pantheon, instead of modifying the settings.php file directly, add the required updates in sites/default/settings.local.php.

Securing your portal

The portal sites associated with the Dev, Test, and Live environments are publicly accessible by default. That means anyone with the URL of the site can access it, though they might not be able to register an account or log in to the site. For more information on controlling user registration, see Add and manage user accounts.

You probably want to hide your Dev and Test site from the public, and want to hide your Live site until you complete development. Pantheon lets you add username/password control to lock a site so that only people with the proper credentials can access it.

Add locking to any of the three environments by selecting Security in the left-hand menu for the environment. For more information, see Locking Your Site.

If you want to enable TLS/SSL for your site, see Using TLS on the portal.

Applying an Apigee update to your portal

When Apigee publishes a new release of the portal, a message appears on the Pantheon Dashboard.

You typically apply the update to the Dev environment, and then test those changes in the same way that you test your own code changes. For example, push the Dev environment to Test, push the live data from Live to Test, and then test the update.

To apply an update:

  1. Log in to Pantheon at https://dashboard.getpantheon.com/ and select your site.
  2. Select the Dev environment.
  3. Select the </>Code menu entry on the left. If any Apigee updates are available, they are listed.
  4. Apply the update:
    1. Select the Run update.php after pulling code checkbox.
    2. If available, select the Clear caches after pulling code checkbox.
    3. Select the Deploy Code button.
  5. After the update completes, select the Status menu item on the left of the dashboard.
  6. In the Status area of an environment, you might notice an error for a database update, as shown below:

    If you see this error in any environment, manually update the database:

    1. Log in to your portal as a user with admin or content creation privileges.
    2. Select the Home icon > Run updates in the upper-left corner of the portal.
    3. Follow the instructions to update your database.
  7. Push the code changes to the Test environment, and then push to Live, as described above.

Migrating your custom features

If you add custom code or features to the portal, you have to decide how to maintain them and how to move them from the Dev to Test to Live environments.

For code in the Git repo, you can use the process described in Deploying code to your portal environments to migrate the code from Dev to Test to Live.

If you have created any custom configurations, use one of the following methods to migrate them:

Method Description
Export your configuration to code Many common configurations are "exportable" to code using the Features module. For example, views, panels, image cache, and so on.
Implement hook_update_N() function Drupal manages database and configuration changes by using the hook_update_N() function.

If you have a custom module, you can:

  • Add hook_update_N() functions to your module's .install file to process your changes.
  • Deploy these changes along with your code.
  • Run update.php to migrate the changes in the Stage and Prod environments.

See also Using the Pantheon Workflow which provides an overview of how to develop, test, and push your site. Included in that article is the section on Configuration Management.

Configuring a custom domain

The domain names that Apigee provides for a portal default to apigee.io, as described in Managing your environments, which may not be what you want to expose to your customers.

Paid portal plans can configure a custom domain name for the portal (Developer, or free accounts, cannot create a custom domain). To use a custom domain create a CNAME in your DNS and point your domain to edge.apigee.getpantheon.com.

For example, to configure the custom domain for a company named Mytech:

  1. Configure the following the DNS setting:
    developer.mytech.com. 3600 IN CNAME edge.apigee.getpantheon.com
    It can take up to 48 hours for this DNS change to take effect for all client devices.
  2. Use the Domains / SSL menu entry on the left side of the dashboard to add this domain to your Pantheon dashboard for the Live environment only.
    In most cases, you only configure DNS for the Live environment, not for Dev and Test. You should not use the Dev or Test environments for production.

For more information, see the Pantheon documentation here.

Adding portal administrators

When you receive the email from Apigee that your portal is ready, Apigee will have already configured the list of portal administrators. You can see that list by selecting the Team link in the upper-right side of the site dashboard.

To add additional administrators, see Create admin users.

Backing up your portal

To back up your portal, use the Backups tab on the Pantheon dashboard. You can create an on-demand or automated backup. In Pantheon, a backup consists of three separate archives: database, files, and code.

For more information, see Backups Tool in the Pantheon documentation.

Subscribing to status updates

You can subscribe to Apigee release and status updates at status.apigee.com. Click Subscribe to Updates, enter your contact information, such as email address, when prompted, and click Subscribe. On the email notification management page, ensure that Developer Portal is selected, toggle other notification settings as required, and click Update Preferences.

You can subscribe to Pantheon status updates and incident reports, such as when an outage occurs, at http://status.getpantheon.com. Click Subscribe to Updates to sign up.