Working with Acquia

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation.
info

Apigee uses Acquia, a website management service, for hosting cloud-based versions of the Developer Services portal. Acquia 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 Acquia to develop and manage your portal.

Accessing the Acquia Cloud interface

After your Acquia Cloud account is set up, you can access your portal via the Acquia Cloud interface at at https://cloud.acquia.com/.

When you first log in, the Applications page is displayed, as shown in the following figure.

The Applications page displays all of the applications that you have access to that are hosted on Acquia Cloud. An application is the software entity that you are managing in the Acquia Cloud, such as your Drupal-based portal site.

The following sections describe how to use the Acquia Cloud interface to manage your portal content.

For more information about the Acquia Cloud interface, see Signing in to the Acquia Cloud interface and Managing applications with Acquia Cloud in the Acquia Cloud documentation.

Managing your environments

Access the Acquia Cloud interface and on the Applications page click Manage associated with your portal site to access its dashboard.

To manage your workflow, three environments are provided for developing, testing, and publishing your portal, as outlined in the following table. Your portal is deployed to each environment, but might be in a different state with a unique code branch or tag, database, and so on. See Deploying code to your portal environments.

Environment Description Default URL
Dev Develop new features and customize your portal. http://{application-name}xxxxxx.devcloud.acquia-sites.com/

Where application-name is the name of your application and xxxxxx is a unique string of characters used to differentiate Dev and Stage.

Stage Test the latest code before pushing it to the production environment. http://{application-name}yyyyyy.devcloud.acquia-sites.com/

Where application-name is the name of your application and yyyyyy is a unique string of characters used to differentiate Dev and Stage.

Prod Publish your portal to production (live). http://{application-name}.devcloud.acquia-sites.com/

Where application-name is the name of your application.

Note: See also Configuring a custom domain.

For more information, see Working with environments in the Acquia Cloud documentation.

Developing your portal

The following sections describe how to develop your portal.

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. For more information, see Enabling SSH access in the Acquia Cloud documentation.

To enable SSH access:

  1. Log in to the Acquia Accounts interface at https://accounts.acquia.com.
  2. Click Credentials.
  3. If prompted, re-enter your password to confirm your identity.
  4. Under SSH keys, click Add SSH key.
  5. Enter the following information:
    Field Description
    Nickname Nickname for the SSH key. The nickname can contain alphanumeric characters and underscores.
    Public key Public key.

    For information about generating an SSH public key, see Generating an SSH public key in the Acquia Cloud documentation.

  6. Click Add key.

Accessing your code repository in Git

The Git repository contains all of your portal site's code. You can add new code or customize existing code to configure your portal. For more information, see Using your code repository in the Acquia Cloud documentation.

To access your code repository in the Git repo:

  1. Log in to the Acquia Cloud interface at https://cloud.acquia.com/.
  2. On the Applications page, click Manage to view the details of the portal.
  3. Click Application Info in the navigation bar.

  4. Copy the clone command in the Application Information dialog.
  5. Clone the Git repository to your local environment by executing one of the following Git commands:

    To clone the Git repository and create a new branch:

    > git clone --branch [branch] myportal@abcdef.devcloud.hosting.acquia.com:myportal.git [destination]

    To clone the Git repository from the master branch:

    > git clone myportal@abcdef.devcloud.hosting.acquia.com:myportal.git [destination]

  6. Repeat these steps when you are ready to stage, commit, and push your changes to the Git repository using the relevant commands shown in the Application window.

    When you commit a branch to your repository, Acquia Cloud updates the environment running that code branch. You can deploy code to your portal environments, as described in the next section.

Deploying code to your portal environments

To deploy, switch, or revert code in a portal environment, move your code between environments, or learn more about the repository structure and recommended workflow, see Working with sites on Aquia Cloud in the Acquia Cloud documentation. When you deploy new code to an environment, you will need to run update.php to make the required database updates.

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.

Enabling SSL

To enable secure access to your site using HTTPS, you must enable SSL.

To enable SSL:

  1. Obtain an SSL certificate from a Certificate Authority (CA) or SSL certificate vendor. See Enabling SSL.
  2. Upload the SSL certificate on the SSL page in the Acquia Cloud interface. See Managing SSL certificates.

Securing your production environment

When you first create an application, you can freely manage the production environment and propagate changes from the development and staging environments. After you publish your content you may want to lock the production environment to prevent unauthorized or accidental updates to the content. For more information, see Using Production mode to protect your live application in the Acquia Cloud documentation.

To secure your production environment:

  1. Log in to the Acquia Cloud interface at https://cloud.acquia.com/.
  2. On the Applications page, click Manage to view the details of your portal site.
  3. Click Prod to view the production environment details.
  4. Click Production Mode in the navigation bar.
  5. Click Enable to enable production mode.

Applying module and theme updates to the portal

Periodically, Apigee updates the modules and themes in your portal to the latest version automatically. Updates are made to the Dev environment only and are tagged to indicate that they need to be migrated to other portal environments.

If your site is not part of the Apigee Acquia billing organization (a new site migrated from another hosting provider to your own organization, for example) you must allow Apigee access to your Git repository in order to receive automated Devportal update pushes. Contact Apigee support for more information.

If you added any custom modules or themes, you will need to update them manually.

The following table summarizes the steps required to apply module and theme updates to the portal.

Modules/Themes Description
Apigee Edge modules

Apigee applies updates automatically to the Dev environment only.

After you test the updates, migrate them from Dev to Stage to Prod environments, as described in Deploying code to your portal environments.

Apigee Responsive theme

Apigee applies updates automatically to the Dev environment only.

After you test the updates, migrate them from Dev to Stage to Prod environments, as described in Deploying code to your portal environments.

Drupal core and contributed modules

Apigee applies updates automatically to the Dev environment only.

After you test the updates, migrate them from Dev to Stage to Prod environments, as described in Deploying code to your portal environments.

Custom modules and themes

If you have added custom modules and themes to your portal, as described in Adding custom modules and themes, you must install updates manually.

Download the latest version to your local directory manually or using Drush. Then stage, commit, and push the updates to the Git repository. After you test the updates, migrate them from Dev to Stage to Prod environments, as described in Deploying code to your portal environments.

Migrating your custom features

If you add custom code or configurations to the portal, you need to maintain and migrate them from Dev to Stage to Prod environments.

For code in the Git repository, you can use the process described in Deploying code to your portal environments to migrate the code from Dev to Stage to Prod.

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.

Configuring a custom domain

As noted in Managing your environments, the default domain names for the portal environments all end in acquia-sites.com. It is recommended that you provide your own custom domain name that personalizes and better conveys the purpose of your site. For example, a popular alternative is:

https://developers.mycompany.com

To configure a custom domain:

  1. Add your domain to your portal site environment. See Managing domains in the Acquia Cloud documentation.
  2. Set up your custom domain with your DNS provider by pointing your domain name's DNS record entry to the public IP address (not to an acquia-sites.com domain). See Pointing DNS records to your public IP addresses in the Acquia Cloud documentation.

    Note: Do not set the domain name's CNAME entry to an acquia-sites.com domain. Doing so may cause latency issues or down time with your portal site.

Monitoring your portal using Acquia Insight

Acquia Insight is a set of tools that enables you to optimize your portal site by monitoring its performance, security, and search engine optimization. For more information, see Acquia Insight.

Backing up your portal

The following tables summarize the options available for backing up your portal components.

Component Backup details More info in Acquia Cloud Docs
Code
  • Code is maintained by a version control system and tagged each time you commit.
  • Sync or revert to a specific tag at any time.
Database
  • Daily backups are performed and maintained for three days.
  • Schedule automatic and on-demand backups.
  • Internal disaster snapshots of all data are taken every hour.
Files Perform manual backups or schedule a cron job.
Full application Perform manual backup using Drush.
.
Drupal file system Perform manual backups using one of the following options:
  • Copy your files using an FTP client or command-line tools (rsync and scp).
  • Create a compressed archive using Drush.

Note: The Backup and Migrate module is not supported on Acquia Cloud. For more information, see Backup and Migrate module not supported on Acquia Cloud.

Viewing activity notifications

You can view activity notifications to keep track of significant actions that occur with your portal site, such as code being installed or copied between environments, database updates and backups, server changes, and more. For more information, see Viewing activity notifications in the Acquia Cloud documentation.

To view the list of notifications:

  1. Log in to the Acquia Cloud interface at https://cloud.acquia.com/.
  2. On the Applications page, click Manage to view the details of your portal site.
  3. Click the bell icon in the upper right corner of the navigation bar to view your most recent notifications.

  4. Click the arrow next to a notification to view more information about the activity.

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 Acquia status updates to receive notifications about any service interruptions, emergency maintenance, or security updates that are made to the platform. To subscribe to Acquia Cloud updates:

  1. Navigate to the Acquia Status page.
  2. Click Subscribe to Updates.
  3. Select the method you want to use to receive updates (email, SMS, and so on).
  4. On the Notifications page, select the products for which you want to receive status updates. For example, Acquia Cloud Enterprise.
  5. Click Update Preferences.