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.

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.

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.

The URL of the Git repo appears on the page to the right of Connection
Mode, as shown in the previous figure.

Copy the URL of your Git repo and clone it to your local development environment by using
the command:> git
clone gitURLsitename
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

Select </>Code in the left-hand menu to see a message about your
code change in the Commit Log:

Select the Test environment at the top of the page.

If you have not yet uploaded Dev to Test, you are
prompted to do it now.

If you already have a Test environment, a message appears indicating
that there is a commit from Dev ready to deploy:

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.

Select the Deploy Code from Development button.

Test the portal in the Test environment.

Make any code fixes to the Dev environment and push files again to
Test for testing.

When testing completes, select the Live environment at the top of the
page.

If you have not yet uploaded Test to Live, you are
prompted to do it now.

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.

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.

Note: 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.

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.

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.

Applying an Apigee update to your portal

Caution: It is the responsibility of the customer to
apply Drupal security patches, and software and configuration updates in a timely manner
to ensure that the Drupal site remains secure. Google is not responsible in the event that
data is compromised or lost.

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

Note: 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.

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.

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.

Note: When applying updates, you may receive the following error: We were not able to perform the merge safely. See the Applying Upstream Updates doc for further debugging tips.

It may be difficult to fix merge conflicts from the Apigee Drupal Developer Portal upstream Git repository because it is not publicly accessible. Contact Apigee support for help fixing merge conflicts.

To minimize Git merge conflicts, make sure not to modify files outside of the sites directory. In addition, 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.

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.

Caution: 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:

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.

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.

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.

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.

Caution: It is strongly recommended that you back up each portal
environment (Dev, Test, and Live) separately on a regular schedule.

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.