Send Docs Feedback

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.

For paid customers only, when Apigee sends you the URL of your portal, you also receive the URL of the Pantheon Dashboard: https://dashboard.getpantheon.com/. A subset of the tasks that you can perform using the Pantheon Dashboard include:

  • Deploy software updates from Apigee
  • Clone your site’s Git repo to make custom code changes
  • Publish your portal to a development, test, and live environment
  • Locate and fix PHP errors
  • Backup and restore your portal
  • Apply security
  • Manage Domain names and TLS/SSL

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.

Paid vs. Developer accounts

All Apigee accounts types are able to apply for a Developer Services portal.

A free Developer (trial) account provides access to a non-production portal and does not enable use of all portal features. For example, using a free Developer account, you cannot:

  • Access the Pantheon Dashboard.
  • Define a custom domain for the portal. Instead, you must use the default domains provided by Apigee.
  • Define an automated backup schedule. You must instead perform manual backups.

In addition, paid customers get a highly available production environment in the cloud, where Developer accounts have “on demand” sites. These "on demand" sites spin down after a few hours and spin up again when the site is accessed.  

For more information about the features that are available to Paid and Developer accounts, see Apigee Edge pricing features.

Subscribing to Pantheon updates

To receive email notifications when Pantheon creates or updates an incident, such as when an outage occurs, subscribe to Pantheon updates at:

http://status.getpantheon.com/

Click on the Subscribe to Updates link so sign up.

When you first log in

When you first log in to Pantheon at https://dashboard.getpantheon.com/, 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, in this figure the site is apigeedocs, to open the dashboard for that site:

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

Upload an SSH Key and clone the Git repo

Upload an SSH key to Pantheon so that you can access the Git repo associated with your portal. The Git repo contains all of your site’s code. That means you can add new code or customize existing code to configure your portal.  

Even though the Git repository give you access to all of the Drupal and Apigee modules, make sure not to modify the code in them. You should only create your own custom modules and themes inside the sites/all folder.  

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 Drupal modules

To upload an SSH key:

  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.

To access the Git repo:

  1. From the main Sites page, select the icon for your portal. 
  2. The URL of the Git repo appears on the page to the right of Connection Mode,  as shown in the previous figure.
  3. 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. The next section describes the Dev environment.  

Develop your portal site

To develop your portal, you can perform the following actions: 

  • Customize the theme through admin interface or in code
  • Add custom code and modules
  • Configure backups
  • Configure a domain 
  • Configure TLS/SSL 
  • more

One of the first things that you notice on the site dashboard is that there are three environments listed across the top of the page:

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.com/

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.com/

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.com/

Configure a custom portal domain

The table above shows the default URLs that Apigee creates for a portal. Note that by default the domain names contain "apigee.com." However, a domain name containing "apigee.com" 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

Apply GIT code changes to your site

The general process for applying GIT code changes to a site is:

  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:

Add your own module

You can expand the functionality of the portal by adding your own modules. To add a module, add it to the sites/all/modules/custom folder in the Git repo. After testing the module in the Dev environment, you can push it to Test for testing, and then to the Live environment for production. 

Secure your site

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

Maintain your site

Maintaining your site involves a number of tasks, including:

  • Checking for updates
  • Updating with the latest Apigee portal releases
  • Testing updates
  • Backing up your site (files, code, and database)
  • Managing users and administrators

Apply an Apigee update to the Developer Services portal

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

There is no automated mechanism to notify you of a portal update. You should check for updates on a regular basis and apply them as necessary.

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. 

Update 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 above to migrate the code from Dev to Test to Live. If you create custom modules, then you can use one of the following ways to migrate your modules:

  • Exporting Configuration
    A growing number of common configurations are "exportable". For instance, Drupal views are easily exported to code. This is how the Features module works. If you are using systems (views, panels, image cache,
    etc.) which support an exported configuration, you can take advantage of this module.
  • Implementing hook_update_N()
    Drupal manages database and configuration changes by using the hook_update_N() function. If you have a custom module, you can add update functions to your module's .install file to process your changes. These changes can them be deployed along with your code, and then you can run update.php to make the changes in the Test and Live environments.
    For example, see the devconnect_update_7423(&$sandbox) function in profiles/apigee/modules/custom/devconnect/devconnect.install in the Git repo for your portal.

Learn more:

 

Help or comments?