What CKAN upgrade and support work involves
CKAN targets about two minor releases a year, and the tech team supports only the latest patch of the current minor version and the previous minor version for security and bug fixes. Once a newer patch is out, the older patch loses support. A portal that stays on an unsupported patch or an older minor line stops receiving fixes, so the upgrade schedule is a standing operational duty rather than a one-time project.
Several triggers start an upgrade. A new minor release, such as CKAN 2.12.0 released on August 26, 2026, moves the supported window forward. A patch release can retire the patch your portal runs. An extension may stop supporting your installed CKAN version, which forces a choice between upgrading CKAN and replacing or forking the extension. A change to the required Solr or Python version can arrive with a release, and a published security advisory may require action outside the normal cycle. Confirm which of these applies to each extension and dependency in your portal.
Patch releases do not break backwards compatibility and exclude schema changes and new features, so they are the lowest-risk upgrades. Minor releases may include backwards-incompatible changes, so each minor upgrade needs a test run against a copy of production data, with custom extensions, theme code, DataStore jobs and harvesters exercised before cutover. Read the release notes for each minor version before scheduling the work.
The short answer: a small team with a stable portal and in-house Python and Linux skills often applies patch upgrades itself. Minor upgrades that touch custom extensions, and portals that need a defined response time, are commonly handled under a support contract with a partner. Ask any partner to state in writing which releases and extensions the contract covers and how security advisories are handled.
What the work includes and what you receive
An upgrade is a set of discrete work packages with named outputs, and a support contract is a set of recurring duties. Ask for both to be written into the fixed-scope agreement or retainer before work starts.
Upgrade assessment
We record the installed CKAN version and patch level, then check each extension against the CKAN versions it supports. The assessment also confirms Python 3.10 or newer, PostgreSQL 12 or newer, Solr 9 or 8, Redis, uWSGI and Nginx. Ask for a written list of blockers and the target version before any build work begins.
Staging upgrade with rollback
The upgrade runs first on a staging copy of the portal, built from a recent production backup. The rollback plan states the database backup point, the code revision to restore and the order of service restarts. Ask to see the rollback steps rehearsed on staging, not only written.
Extension compatibility updates
Each custom or third-party extension is either updated to work with the target CKAN minor version or replaced with a maintained alternative. Minor releases may include backwards-incompatible changes, so extension code is reviewed rather than assumed to work. Ask for a list of each extension with its disposition and owner.
Solr and Python dependency changes
The upgrade may require a Solr version change, a schema or configuration update for the search index, and new Python package pins. Each change is tested against search results and reindexing time on staging. Ask whether a full reindex is needed and how long production search will be affected.
Regression tests on core workflows
Testing covers publishing, harvesting, DataStore loading through XLoader, DCAT endpoints and SSO if it is in use. XLoader is the officially supported loader, so uploads and linked files are tested end to end. Ask for written test results that name each workflow, the test data used and any open defects.
Production cutover and handover
Cutover follows the staging sequence, with a recorded go or no-go check and a post-cutover verification pass. Handover includes an updated runbook covering configuration, backups, patch steps and the rollback procedure. Ask for a change log, the test results and the runbook as named deliverables in the agreement.
Release monitoring and patch cadence
Support staff track CKAN release notices and apply patch releases on a cadence stated in the contract. Patch releases do not break backwards compatibility, but outdated patches lose support once a newer one is out. Ask which cadence is committed, who approves each patch and how emergency patches are handled.
Incident response and minor upgrade plans
Incident response covers portal outages, failed harvests and DataStore errors, with a defined severity scale and response times written into the contract. Each new minor release also gets its own upgrade plan, so the portal stays on a supported version. Ask for the response times, the severity definitions and the escalation path in writing.
What drives upgrade cost and duration
This table lists the factors that most change the effort of a CKAN upgrade, why each one matters and how to reduce it before you request a quote.
| Driver | Why it matters | How to keep it down |
|---|---|---|
| Custom and third-party extensions | Each extension must load and work on the target CKAN version, and some may need code changes or replacement. Confirm release support for the target version first, including ckanext-dcat, which is listed as supported on CKAN 2.10 and 2.11 only. | Inventory every extension and its version, drop unused ones, and prefer maintained extensions with a release for the target version. |
| Gap between installed and target version | Skipping one or more minor releases stacks backwards-incompatible changes from each step, while patch releases do not break compatibility. | Stay on the latest patch of your current minor version so each jump is smaller and the changes are easier to review. |
| Customized theming and templates | Overridden templates and CSS often break when core templates change between minor versions, and they need visual and functional review. | Keep overrides minimal, use the template inheritance and extension points CKAN provides, and document each override. |
| Solr major version change | Moving between Solr major versions changes the search backend setup and requires a full reindex, and search behavior needs checking against your facets and queries. | Confirm the Solr version the target release supports, schedule reindexing time, and keep schema customizations documented. |
| Python version change | A newer Python runtime can require updated dependencies for CKAN and each extension, and some packages may need rebuilding. | Check the Python version the target release requires (CKAN source installs need Python 3.10 or newer) and pin extension dependencies early. |
| Number of environments and test data | Every environment, including development, test and production, needs its own upgrade run, and realistic test data is needed to catch regressions. | Keep environments built from the same configuration, and maintain a representative dataset with datasets, organizations and users for testing. |
| DataStore size and resources to re-verify | Large DataStore tables and many resources may need reloading or re-checking through XLoader, which is the officially supported loader, and this can take significant processing time. | Count resources that use DataStore, record which were loaded by XLoader, and decide with the partner which need re-verification versus a full reload. |
| SAML2 or other SSO setup | Authentication changes between CKAN versions and extension updates can affect the ckanext-saml2auth configuration, role mapping and sysadmin lists, which need login testing with the identity provider. | Document the current SSO configuration, keep identity provider test accounts available, and include login and role checks in the test plan. |
| Number of harvest sources | Each harvester and its source definitions must keep working, and changes in metadata handling can alter harvested records. | List all harvest sources, run them in the test environment, and compare resulting dataset counts and metadata with the current portal. |
Project phases and outputs
The sequence moves a CKAN portal from an inventory of what runs today to a tested, documented target version that your team or ours can support.
Inventory the current portal and versions
We list the running CKAN core version, every installed extension and theme, Python and PostgreSQL versions, Solr and Redis versions, and the custom code that sits on top. The output is a component list with versions and an extension compatibility view. It is done when your team has reviewed and confirmed the list against what is actually deployed.
Select the target and run gap analysis
We compare your current minor version with the supported minor releases and recommend a target version. Gap analysis identifies backwards-incompatible changes, extensions without a matching release, and Solr or Python changes that affect the build. The output is a written target version and a list of blocking changes that must be resolved before cutover.
Build the staging environment on the target stack
We build a staging environment on the chosen install method, from source or the packaged method you approve, using the target Python, PostgreSQL, Solr and Redis versions. Build steps are scripted so the environment can be rebuilt. It is done when the staging portal starts cleanly, the DataStore connects with its read and write users, and the search index rebuilds.
Update extensions and themes
We bring each extension and theme to a version that works on the target release, patching custom code where needed and replacing abandoned packages with a documented alternative. Changes are committed to version control with tests. The output is tested code that passes the unit and integration tests and loads in staging without errors.
Run the test and acceptance pass
Your publishers and site owners test the staging portal against a written checklist covering dataset publishing, harvesting, DataStore views, search, APIs and access roles. Defects are logged, fixed and retested. The output is signed-off test results that name who approved the target for production.
Cut over to production with a rollback path
We schedule the production change with your operations team, take verified backups of the database, file storage and Solr configuration, and document the rollback steps before starting. After cutover we check the portal, APIs and scheduled jobs. The output is a dated change record that shows what changed, when, and how to reverse it.
Hand over and start support
We deliver a runbook covering installation, patch steps, backup and restore, Solr and DataStore operations, and escalation contacts, then walk your operators through it. If a support retainer is agreed, it starts with a support calendar listing patch windows and review dates. Ask for the timeline and support terms in the written scope before work begins.
What to keep in-house and what to outsource
This table shows who usually owns each area of a CKAN upgrade and support arrangement and the skills each area needs, so you can check the split against your own team.
| Work area | Usual owner | Skills needed |
|---|---|---|
| Patch application on a staging copy | Partner, with portal owner sign-off | Linux administration, CKAN source installs, Git and deployment tooling |
| Subscribing to CKAN release notices and triaging them | Partner, with portal owner review of impact | Familiarity with CKAN release policy, reading changelogs, judging impact on your extensions |
| Extension maintenance | Partner, for ports and fixes | Python developers familiar with CKAN plugin interfaces and the extensions you run |
| Solr and Redis operations | Shared, with partner handling version changes | Solr schema and index management, Redis monitoring, search troubleshooting |
| PostgreSQL and DataStore operations | Shared, with partner handling migrations | PostgreSQL administration, backups, DataStore read-only user configuration |
| Linux, Nginx and uWSGI operations | Your infrastructure team, with partner support during upgrades | Linux server administration, web server and process manager configuration, certificate handling |
| Publisher communication and acceptance testing | Portal owner's team | Knowledge of publishers and datasets, functional testing, business sign-off |
| Incident response | Shared, under the support calendar agreed in the contract | On-call rota, runbooks, CKAN log analysis, escalation with your own security team |
What usually goes wrong on CKAN upgrades
Most CKAN upgrade problems are predictable and show up in the same few places: version gaps, extensions, search index, Python dependencies, DataStore, custom templates, staging drift and vague support terms. Each card names one failure and the check that prevents it.
Skipping minor versions
Minor releases may include backwards-incompatible changes, so jumping several minor versions at once hides breaking changes until cutover. Map every minor release between your current version and the target, read each release's notes, and run the upgrade path in staging one step at a time. Confirm the current supported minor versions against CKAN's release policy before you plan.
Extensions behind the target release
An extension that is abandoned or not yet compatible with the target CKAN release can block the whole upgrade. Check each extension's repository for a release tagged for the target version, and record which ones you must fork, replace or retire. Decide these before the upgrade window, not during it.
Solr schema and version mismatch
After an upgrade, the search index may expect a different Solr schema or version than the one running. Confirm the Solr version your target CKAN release supports, deploy the matching schema, and rebuild the search index in staging. Search results that look empty after cutover often point to this step being skipped.
Python changes breaking dependencies
A newer Python runtime can break extension dependencies that pinned older libraries or relied on removed behavior. Keep a pinned dependency list for every extension and rebuild the virtual environment from it in staging. Test the full extension set on the exact Python version you will run in production.
DataStore not reloaded after cutover
DataStore resources can be left unloaded or unindexed after a database cutover, so the Data API returns incomplete results. Plan a reload or re-index step for affected resources, using XLoader as the supported loader, and verify row counts for sample resources. Include the DataStore read and write database users in the cutover checklist.
Custom templates overriding core markup
Custom templates that copy and modify core CKAN markup can break silently when a release changes the underlying template. Keep overrides as small as possible, record each one against the core file it replaces, and review them in staging against the release notes. Visual regressions are often the first sign of this failure.
Staging that does not match production
A staging environment with different extension versions, Solr settings, data volume or web server configuration gives false confidence. Build staging from the same configuration management as production, copy a recent database snapshot, and compare versions of every component before the test run. Document every known difference.
No rollback point
Without a tested rollback path, a failed upgrade turns into an extended outage. Take a database snapshot and a copy of configuration and extension code before each window, and rehearse restoring them in staging. Confirm who decides to roll back and how long the decision window lasts.
Support contract without a patch cadence
A support contract that does not state how often patch releases are applied leaves security fixes waiting on informal scheduling. Write the patch cadence, the minor versions covered, the testing responsibilities and the change window into the contract. Ask the provider how each of these is handled before signing.
How the work differs by starting point
A portal on the latest supported minor with no custom extensions is usually the simplest case. Most of the work is applying the latest patch release for that minor, which CKAN patch releases are designed not to break backwards compatibility.
- Confirm which minor and patch version is running and whether it is the latest patch of a supported minor.
- Review the release notes for each patch between the current version and the target for security fixes and dependency changes.
- Check that the Python, PostgreSQL, Solr and Redis versions still meet the install requirements for the target patch.
- Plan a staging rebuild and a smoke test of search, DataStore queries and user login before production.
- Confirm whether the portal depends on any Solr or Redis image tag that must be changed alongside the CKAN version.
A portal several minor versions behind needs a staged path through intermediate minor releases. Minor releases may include backwards-incompatible changes, so each step needs its own review and regression testing rather than one direct jump.
- Confirm the current minor, the target minor and the list of minor releases in between.
- Plan one upgrade stage per minor, with a database backup and a staging test before each stage.
- Review each minor's changes to configuration options, templates, action functions and database migrations.
- Expect more regression testing of search, harvesting, DataStore loads and API clients at each stage.
- Ask whether any step requires a Solr, Python or PostgreSQL change that must be scheduled separately.
A portal with custom extensions or heavy theming makes extension porting the main effort. Each extension must be checked against the target minor, and theme templates often change between minors, so this work usually outweighs the core upgrade.
- Inventory every custom and third-party extension, including its source, license and maintainer status.
- Confirm which extensions have a release for the target minor and which need porting or replacement.
- Review template overrides and CSS for changes in the core templates the theme depends on.
- Plan tests for each extension's plugin hooks, actions and API endpoints before and after the port.
- Ask who owns each extension after handover, since unmaintained code will need a support decision.
A portal on an older Ubuntu release or a distribution outside the package install guide needs a source install on the chosen operating system. The package install guide covers Ubuntu 20.04 and 22.04 64-bit, so the build, dependency and service configuration must be planned by hand.
- Confirm the operating system version, its support window and whether Python 3.10 or newer is available from its packages.
- Confirm the PostgreSQL, Solr and Redis versions available on that operating system or as supported images.
- Plan the source install steps, uWSGI and Nginx configuration and systemd service layout for that distribution.
- Decide whether an OS upgrade should come before or with the CKAN upgrade, since the two changes interact.
- Confirm who will patch the operating system and the CKAN dependencies after go-live.
A Docker-based deployment ties Solr and Redis image tags to the CKAN version, so the image set changes as a unit. The plan must treat the CKAN image, Solr image and Redis image as one versioned release.
- Confirm which CKAN, Solr and Redis image tags are currently running and which tags the target minor is tested with.
- Plan the upgrade as a change to the image set, not to individual containers, and keep the previous tags available for rollback.
- Check volume and data directory compatibility for Solr and PostgreSQL before replacing containers.
- Plan a Solr reindex and search verification after the Solr image changes.
- Confirm who maintains the image build pipeline and how image updates are tested before deployment.
An air-gapped or restricted network changes the delivery path. Release packages, container images and Python dependencies must be transferred in, verified and staged before the install or upgrade can start.
- Confirm which CKAN release packages, extension packages, Python dependencies and container images must be transferred.
- Plan a verification step for each transferred artifact, such as checksum comparison and a record of its source, before it enters the network.
- Confirm whether an internal package mirror or image registry exists or must be built.
- Schedule the transfer window so the staged artifacts are available before the maintenance window opens.
- Ask whether patch releases can be delivered on a regular cycle, since each patch needs the same transfer and verification steps.
What you need to provide
Before planning starts, DeployOpen needs administrator access to the portal server, the PostgreSQL host, the Solr host and the Redis host, or a named engineer from your team who can run the commands we specify. We also need the current CKAN configuration file, the installed CKAN version, the deployment method (source install, package or Docker), and a complete list of installed extensions with their exact versions. Without the extension list, the compatibility review that decides which extensions can move to a supported minor release cannot start.
Ask for a staging environment that matches production in CKAN version, extensions, Solr version and web server layout, or agree that we can create one in your infrastructure. Testing also needs a copy of production data. Confirm how personal data in that copy is masked, removed or kept under your policies, and get written approval for where the copy is stored. Name an owner for acceptance testing and another for publisher communication, since publishers will see changes to forms, harvesters and DataStore behavior first.
Agree a maintenance window with the people who approve downtime, and confirm the date of your last verified backup of the database, the filestore and the Solr index. Decide who approves go-live, and who can stop it if acceptance testing fails. Also confirm whether you have a current rollback plan that has been tested, because a minor upgrade may need one.
Decide the support scope before a contract is drafted. Choose business hours or extended coverage, the patch cadence you want (for example, applying each new patch release within a set period or quarterly batches), and the escalation path from your service desk to DeployOpen and then to the named owner in your team. Record these decisions in the written scope so that response expectations and fees can be quoted against them.
Frequently asked questions
How much and how long does a CKAN upgrade take?
Cost and duration both follow from the scope agreed in writing, and DeployOpen does not publish prices. A quote should split the work into an assessment of your current version and extensions, a rebuilt staging environment, the upgrade and data steps, regression testing, and cutover with a rollback plan. Effort rises with the number of minor versions you skip, the number of custom extensions, Solr and Python changes, and the size of your DataStore tables. Duration also depends on the test and change windows your organization can accept, so confirm the timeline in the quote.
Can our own team upgrade CKAN without a partner?
Yes, for patch releases, provided your team has Linux administration and Python skills. Patch releases do not break backwards compatibility and exclude schema changes and new features, so they are the lowest-risk upgrades to run in-house. Minor releases can include backwards-incompatible changes, and extensions may need code changes, tests and configuration updates. Read the release notes and check extension compatibility before you start, and decide in advance which minor upgrades you will handle internally.
How often does CKAN need to be upgraded?
CKAN targets about two minor releases a year. The project supports the latest patch of the current minor version and the previous minor version for security and bug fixes, and an outdated patch loses support once a newer patch is out. To stay supported, apply patch releases promptly and move to a newer minor version before the one you run falls outside that two-version window. Check the CKAN release policy for current dates and plan change windows around them.
What does a CKAN support contract cover compared with a one-off upgrade?
A one-off upgrade has a fixed scope and an end date, while a support contract is ongoing work delivered as a retainer. Most DeployOpen engagements are fixed-scope, with scope and deliverables agreed in writing before work starts. Ask whether a retainer includes patch application, minor upgrades, extension compatibility checks, Solr and Redis changes, backup verification and incident handling, and what it excludes. Confirm the response expectations in the written agreement.
What happens to custom CKAN extensions during an upgrade?
Custom extensions are often the largest source of upgrade effort. Each one needs a compatibility check against the target CKAN version, and may need code changes, updated tests and new configuration. Review third-party extensions for maintenance status before you upgrade, because an unmaintained extension can block a move to a newer minor version. After the upgrade, confirm your loader: XLoader is the officially supported tool for loading files into the DataStore, while DataPusher is legacy, so plan to move DataPusher jobs to XLoader and test them.
What must we provide before a CKAN upgrade starts?
Start with an inventory of the running CKAN version, installed extensions and their versions, custom code, and the hosting layout, including PostgreSQL, Solr, Redis and the web server. Provide database and file backups that your team has tested, a staging environment that closely matches production, and named owners who can approve changes. Confirm the change windows you can accept and who decides go-live. Access to the infrastructure you control should be settled in the written scope before work begins.
How DeployOpen delivers CKAN upgrades and support
DeployOpen plans, implements, upgrades, documents and supports CKAN inside your own infrastructure, including your cloud accounts, data centers or air-gapped networks. Work follows a written, fixed scope, with ongoing support available as a retainer.
How we scope
- The written scope names the current CKAN version, target minor release and the patch level you intend to run.
- It lists every custom and third-party extension, with the compatibility check or change planned for each one.
- It records the Solr, Python, PostgreSQL and Redis versions in use and which of them the upgrade will change.
How we build
- We rehearse the upgrade on a staging copy of your portal, including DataStore tables and a restored database backup.
- We test extensions, theme templates, harvesters and the Data API against the target version before any production change.
- We adjust configuration, dependencies and service versions in version-controlled code so each change can be reviewed and reversed.
How we hand over
- You receive upgrade runbooks, rollback steps, a test log and an updated record of installed component versions.
- Documentation covers patch cadence, the minor release calendar and which extension changes need owner sign-off.
- Your operators are walked through the procedure, so the next patch or minor upgrade can be run by your own team.
How we support
- Ongoing support under a retainer covers patch application, dependency monitoring and agreed reviews of new CKAN releases.
- Each support period ends with a short report on applied patches, open extension risks and recommended next steps.
- Before you sign, confirm response expectations, the included services and the exact deliverables in writing.
