Updating and Maintaining DKAN¶
There are several strategies for maintaining your DKAN site. Maintaining a DKAN site does not differ substantially from maintaining other Drupal distributions.
Drupal distributions consist of a script that runs at the time of the
installation as well as a set of modules, themes, and libraries that
exist at profiles/MY_DISTRIBUTION
directory. These modules, themes,
and libraries work the same as any other modules, themes, or libraries
that are added to Drupal sites. They are packaged together in the
profiles
directory to make it easier to install and maintain.
Tip
DKAN Starter is project containing a prebuilt version of DKAN and the tools CivicActions uses for our own implementations and deployments. Learn more advanced workflows in that project’s documentation.
Filesystem Conventions¶
With Drupal’s inheritance model mentioned above, it should not be
necessary to place custom code or modules in the profiles/dkan
directory. Additional modules, themes, or libraries, or newer versions
of ones already present in profiles/dkan
, can be placed in
sites/all
.
If it is necessary or expedient to overwrite files in the
profiles/dkan
directory, it is recommended to keep a
patch
of the changes. A patch will make it possible to re-apply changes once a
newer version of DKAN is added to the ‘profiles/dkan’ directory.
If DKAN’s extensions and customizations of core Drupal are isolated in
profiles/DKAN
, and your site’s particular configuration, files, and
overrides and customizations of DKAN are isolated in sites/
,
maintaining your DKAN site will be much easier.
Primary Maintenance Tasks¶
By “maintenance” we mean three specific tasks
- Upgrading DKAN to receive new features and bug-fixes
- Adding additional modules or features
- Overriding current modules or functionally
Getting DKAN Updates¶
DKAN uses Drupal versioning standards, with one modification. Minor upgrades to DKAN are released approximately every 4-6 weeks. For instance, a minor release would move from DKAN 7.x-1.11 to 7.x-1.12. Starting with version 7.x-1.12, we are adding patch releases for security and bug fixes. For instance, the first patch release between 7.x-1.12 and 7.x-1.13 will be 7.x-1.12.1.
Please note you can not use drush up
with DKAN. This is because
DKAN is not packaged on Drupal.org.
Basic Upgrades¶
The least complex way to update your DKAN codebase is similar to an update of Drupal itself.
- Back up your database (just in case!)
- Copy your
sites
folder somewhere safe. - Replace your entire codebase with the latest fully built version of DKAN from DKAN DROPS-7.
- Check the new versions’ release notes to see if there are any special instructions for updating. (If you are several releases behind, you may need to follow instructions for several releases).
- Replace the
sites
folder in your new codebase with your oldsites
folder. - Now navigate to http://yoursite.com/update.php or run
drush updatedb
. - Clear caches by visiting /admin/performance or running
drush cache-clear all
. - Revert all features by visiting /admin/structure/features or
running
drush features-revert-all
(Use with caution, as this may overwrite any DKAN configuration you have overridden and not exported to code; see Features for more information.)
Note: Occasionally a DKAN component will be moved to a new directory. This should be explained in the release notes for that version. But if you get errors related to incorrect location of module files, you may want to try rebuilding the registry.
Using drush make¶
We are developing an easier workflow to update DKAN on the command line.
For the time being, the recommended method for updating using the
drush make
instructions described in the Installation Instructions
is similar to the process described above.
Assuming you have followed the instructions for drush make
and have
a webroot
folder inside a main clone of the DKAN
repo:
- Back up your database
- Copy your
sites
folder somewhere safe. - Remove your webroot folder:
rm -rf webroot
(use with caution!) - Check out the new version of DKAN you want to update to:
git checkout tags/7.x-1.12
drush make drupal-org-core.make webroot --yes
rsync -av . webroot/profiles/dkan --exclude webroot
drush make --no-core --contrib-destination=./ drupal-org.make webroot/profiles/dkan --no-recursion --yes
- Replace the
sites
folder in your new codebase with your oldsites
folder. - Check the new versions’ release notes to see if there are any special instructions for updating. (If you are several releases behind, you may need to follow instructions for several releases).
drush updatedb
.drush cache-clear all
drush features-revert-all
(use with caution).
You can also use this method to upgrade to the most recent
“bleeding-edge” development version of DKAN. Instead of checking out a
specific tag, check out the 7.x-1.x
branch in step 3.
Features Module¶
DKAN packages much of its configuration using the Features module.
After DKAN is upgraded DKAN site maintainers may wish to revert some features in order to take advantage of new functionality. We recommend using the Features Override module to capture overridden features elements to make it easier to revert Features from DKAN when desired. More documentation on this to come.
Advanced Workflows¶
Using a Custom Make file¶
DKAN is “built” using a make file and drush make
. The
drupal-org.make
file in DKAN contains a list of most of the modules installed in DKAN.
When developing a website for production, it is recommended to keep a
make file for all custom modules added to DKAN. Instead of using
drush pm-download
or other means of downloading and adding modules
to sites/all
, a make file is kept that has a list of the sites
modules. This enforces some best practices about not overwriting
contributed modules, maintaining patches, and reusability. This make
file along with DKAN’s makefiles also provide a reusable recipe for your
site.
More documentation and automation scripts regarding this process are under active development and can be viewed here: DKAN Starter Documentation.
Adding additional modules or features¶
New modules, themes, or libraries should be added to the ‘sites/all’ directory. For modules or themes it is often useful to differentiate “custom” modules from “community” modules. We often have a directory structure for modules like:
Location | Contents |
---|---|
sites/all/modules/contrib |
community or contributed modules |
sites/all/modules/custom |
custom modules |
sites/all/libraries |
Additional libraries |
Overriding current DKAN modules or functionality¶
Drupal has an inheritance model that makes it easy to override modules added to distributions as well as the functionality of other modules.
Any modules or themes added to sites/all
will override the same
named module as one that is placed in profiles/dkan/
.
If a DKAN site maintainer wishes to update a module supplied by DKAN
that module can be placed in “sites/all”. For example if one wished to
update the Date module, if
there is a security update or new release with a certain functionality,
add it to sites/all
:
Location | Version |
---|---|
profiles/dkan/modules/contrib/date |
7.x-1.4 |
sites/all/modules/contrib/date |
7.x-1.5 |
In this case, DKAN will use the version 7.x-1.5 and ignore 7.x-1.4.
If, later, you update your site to a version of DKAN that uses Date v.
7.x-1.5, the version in sites/all
should be removed. Be careful to
review your overrides in sites/all
after every DKAN update to ensure
you are not missing important module updates.
Note that moving to a different location for an existing, installed module will require a Registry Rebuild to prompt Drupal to refresh all module paths.