Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

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.

Required reading: Pantheon documentation

This document contains an overview of how you use Pantheon with your portal. However, use the Pantheon documentation for much of the detailed information on working with Pantheon.

Included in the Pantheon documentation is the Required Reading page with links to many important documents.

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/

For portals created prior to June 15, 2017 that have not been migrated, the URLs to your portal environments will be in the following form:

http://{environment}-{your-org-name}.devportal.apigee.com/

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:

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.

If you wish to use the Drupal profile modules and themes maintained by Apigee in the /profiles/apigee folder, then you will need to remove any duplicate modules and themes that you added to this folder.

Module/Theme Folder in Git repository More information (Drupal documentation)
Drupal Contributed modules sites/all/modules/contrib 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.

 

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 SSL 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 should check for updates on a regular basis and apply them as necessary. You can subscribe to Apigee release and Pantheon status updates, as described in Subscribing to status updates.

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.

In the Status area of an environment, accessed from the Status menu item on the left of the dashboard, you might see that there are updates available for Drupal modules. Ignore these updates. Apigee automatically incorporates updates to Drupal modules into the next release of the portal for you.

By allowing Apigee to update Drupal modules for you, Apigee ensures that these updates have been tested against the latest portal code. If you update a Drupal module outside of the normal Apigee portal release cycle, you might run into unforeseen issues.

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.

The instructions on the Pantheon dashboard specify to use CNAME edge.live.getpantheon.com, but this is incorrect. Make sure you use 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, contact Apigee Customer Support

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 on the Subscribe to Updates link so sign up.

Help or comments?