You're viewing Apigee Edge documentation.
Go to the
Apigee X documentation. info
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. Pantheon's website management service is available to customers with hosting and development operation needs across the globe.
The following sections describe how to use Pantheon to develop and manage your portal.
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.
- Overview of the Git repository
- Accessing your code
- Deploying code to your portal environments
- Adding custom modules and themes
- Overriding Drupal profile modules and themes
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. |
|
|
Advanced - To make modifications to the complete look and feel of the site, extend the Apigee Responsive 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:
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:
- Log in to Pantheon at https://dashboard.getpantheon.com/.
- On the dashboard, select Account.
- Select SSH Keys in the menu on the left.
- 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:
- Log into the Pantheon dashboard.
- From the main Sites page, select the icon for your portal.
- 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 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:
- Push your code updates to Git, which immediately updates the Dev environment.
- Log in to Pantheon and select your site.
- Select the Dev environment.
- 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.
Learn more:
- Pantheon supplies a set of Going Live Articles on this process that you can view. One of the most important is the Using the Pantheon Workflow article which provides an overview of how to develop, test, and push your site.
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 |
Note: Modules stored anywhere under |
Contributed modules
Note: Drupal contributed modules in this directory override equivalent modules
maintained and distributed by Apigee in |
| Drupal Contributed themes | sites/all/themes |
Contributed themes
Note: Drupal contributed themes in this directory override equivalent modules
maintained and distributed by Apigee
in |
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:
- Log in to Pantheon at https://dashboard.getpantheon.com/ and select your site.
- Select the Dev environment.
- Select the </>Code menu entry on the left. If any Apigee updates are available, they are listed.
- Apply the update:
-
Select the Run update.php after pulling code checkbox.
-
If available, select the Clear caches after pulling code checkbox.
-
Select the Deploy Code button.
-
- After the update completes, select the Status menu item on the left of the dashboard.
- 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:
- Log in to your portal as a user with admin or content creation privileges.
- Select the Home icon > Run updates in the upper-left corner of the portal.
- Follow the instructions to update your database.
- 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:
|
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:
- 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.
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.