Technology Services

Developer’s Guide

Welcome to academic and enterprise-level Drupal development for the Trinity College of Arts and Sciences at Duke University. We are focused on providing secure and reliable Drupal site development and toward that end we have developed this vendor guidance.

We greatly value and will make time for coordination efforts or answering questions related to our hosting and maintenance of your finished site. To that end, we strongly encourage frequent communication with us throughout the development lifecycle.

Scope for projects

When identifying your specifications and requirements for your project, please include all the items we identify in this document as requirements for delivery to Trinity Technology Services. (TTS) We can discuss exceptions as needed on a project-level basis.

Drupal core and module versions

We are using Drupal 7 and we strive to keep all core and non-core modules current with the latest stable release. We will perform site testing against Drupal core and module updates to ensure that functionality and presentation is what we expect.

Modules

We maintain a list of carefully reviewed modules. We have reviewed these modules extensively for security, reliability, stability and mainstream usage within the Drupal community. You should limit your site development to this list of modules.

If you wish to use a module not on this list, contact us with the module you wish to include. The module MUST meet the following criteria:

  • The module must be a Drupal-hosted module project
  • The module must have the maintenance status of "Actively Maintained" and a development status of "Under active development"
  • The reported installs must be greater than 1000 sites

We must review any module that doesn't meet any of the above criteria for security, reliability, performance, and other various aspects to determine if we can accept the module for inclusion. This is best done as early in the site development as possible to allow for contingencies should a module fail to meet approval.

Security practices

  • Ensure your Drupal core and modules are up-to-date during your development process. There should be no outdated modules at the time of site hand-off.
  • Uniquely name the user/1 account. "Admin" is an easy guess.
  • Disable allowing PHP code in any user-facing content fields.
  • Ensure that only administrators can register new user accounts.
  • Stick with the above list for modules. Use as few as possible.
  • Review your watchdog and apache error output logs. Address theme warnings.

Theming

We have standardized our theming using Omega. You must obtain our permissions before selecting another theme. Use a subtheme, and do not edit the base theme. There's more information at the Drupal.org site on subtheming. We have our own TTS and TTS subtheme that we use for our departments. You may use this theme for your site if you wish. The TTS theme is a subtheme of the Omega 4.x theme. The TTS subtheme is a subtheme of TTS and is responsive.

  • Allow for easy content editing via the Drupal user interface by never placing content in your template files.
  • Please use Drupal's conventions for including JavaScript into your theme. Avoid making manual edits to html.tpl.php when you can use drupal's APIs or modifications to the theme info file.
  • Do not specify your JavaScript or cascading stylesheets in the tpl files. Use your theme's template.php file, or use the theme.info file for specifying style sheet inclusion.

Features

We recognize that 'Features' can be an effective way of replicating functionality from one environment to another. We developed the following guidelines and best practices for creating and managing features with the goal of helping to reduce the risk of creating features that result in conflicts:

  1. Keep your features as small and compartamentalized as possible; that is, do not encapsulate all your functionality in one feature, but break it out into smaller units, each bundling a single function.
  2. Use a unique naming convention for the following data types or entities that make up a feature. In this way, each name is unique to each defined feature set:
    1. Image styles
    2. Flexslider options
    3. Date and time format
    4. Taxonomy terms
    5. Content type and associated field names
    6. Feeds
    7. Views
    8. Pages
    9. Panels
  3. Develop your feature(s) in a local/development environment
  4. Commit your feature(s) to the site repository (<site-name>.duke.edu/modules/<feature-name>)
  5. Deploy to staging, enable and test
  6. Deploy to production, enable and test

Moving forward, should a feature need to be updated:

  1. Download the latest version of the feature from the site repository to a local/development environment
  2. Make the configuration changes in the local/development environment
  3. Recreate the feature in the local/development environment
  4. Commit the changes to the site repository
  5. Deploy the modified code to staging, revert the feature (drush fr <feature-name>) and test
  6. Deploy the modified code to production, revert the feature and test

Multi-site

We use the standard Drupal multi-site configuration for all of our sites. We understand that setting up multi-site on a local environment isn't trivial but doing so will better allow you to match the environment you'll be deploying to.

Multi-site uses a naming convention where the sites/local-site directory mirrors the actual domain for the site. For example, the history.duke.edu site is found at sites/history_duke_edu. Inside this directory are the modules, libraries, files and themes that are unique for this site. The theme name mirrors the lowest-level of the domain, i.e., "history" for history.duke.edu. Please be sure to name the custom theme accordingly:

history_duke_edu ├── libraries ├── modules │   ├── redirect └── themes     └── history

Accessing the Duke University network

  • Every member of your team that will be updating site content on the Duke network will need a "Guest Account." Note that will log all activity on our network. You "own" all activity our system associates with your Guest Account, so be sure that everyone on your team procures a Guest Account.
  • To learn more you can read about our guest policy here, guest access to Duke resources here, and when you're ready, your Duke contact may request your guest account here
  • The default lifetime for guest accounts is one year; however, we strongly encourage your Duke contact to request that the duration of your account to be limited to the time you expect to complete your project.
  • Our security procedures limits who may directly access site files. We have available a git repo so that you may commit your code changes there and we may then push your changes as needed.

Development workflows

Ideally, you may wish to develop locally before bringing your site to our servers. When you're ready to send us your files, you may find that drush archive-dump is helpful for this.

Server information

We maintain a "staging" and "production" server pair for all of our sites. Generally, you'll be working on the "staging" server. We place IP restrictions on our staging servers, limiting access to those who are on the Duke internal network. If you are off-campus, this will require that you use your Guest NET ID Account in conjunction with out VPN software to access our network. Visit portal.duke.edu for more on accessing the Duke network remotely.

Also note that we generally do not synchronize the staging site's database with production. You must recreate any changes you make the the staging site's configuration to the production's database. We have started to support Drupal 7's Features module for this. See the section on features for more information.

Uploading and maintaining your code

We have a GitLab server where we maintain all of our code for our sites. You must use your Guest Net ID to access this server. We use git to push code update

To access our GitLab server, we'll need to add your Guest Net ID to the releveant project repository. If this is your first time accessing the server, you must access the server before we grant you access, due to how we manage accounts with shibboleth. Once you access the site, you'll need to add your public key. You can read more about the key creation process here.

After we install your exported site on our servers, you'll be able to push your code changes using git. We use a "staging" branch for the staging server, and "master" for production. Once we confirmed that the "staging" branch code is correct, you'll merge these into the master branch and "git push" your changes to our server. Please notify us via email after doing so and we'll push your changes to the production server.

Note: gitlab.org has bought gitorious.org. Duke is in the process of migrating their services to git services to our new GitLab server. We'll update these instructions when that time passes.

Maintenance page

We strongly encourage the creation of a maintenance page for when we take sites off-line for maintenance tasks. The design need not be the same standard as the rest of the site, but be certain to be clear that the page is legible. Drupal covers this process here.

Site Delivery Review

We use the Site Audit module to review received sites and find potential issues, such as unused or improperly disabled modules. We also will crawl the major pages at the site and check Drupal watchdog log and the apache logs for warnings and errors.

Site Launch

We will run our quality assurance checklist prior to launching your site. Also note that we only launch a new or redesigned web site on Monday through Thursday. If Friday is a holiday for the target launch week, then Monday through Wednesday are the available weekdays.