A practical path from CollectiveAccess 1.7.11 to 2.0.11
I wanted to return to this thread and close the loop.
We now have a functioning Providence and Pawtucket 2.0.11 staging installation. Our production 1.7.11 installation remains unchanged while the new system is evaluated.
The short answer to my original question is: yes, create a clean installation and clone your existing database, configuration, and media into a separate staging environment.
That advice is basically correct. It also compresses an entire upgrade project into one sentence.
The database is only one part of the job. You also need to bring forward the correct configuration, isolate the staging media from production, migrate the database, install and configure the required PHP version and modules, reconstruct an older Pawtucket theme around the maintained 2.0 theme, and test the complete application.
This is not an official upgrade guide, and every installation will be different. It is the approach that ultimately worked for us.
The most important recommendation
If you are not already an experienced Linux, web-server, database, PHP, and CollectiveAccess administrator, use a capable paid AI assistant with support for long conversations, file and source-code review, and preferably controlled terminal access.
Give it this post, the official CollectiveAccess documentation, and access to inspect your installation.
Do not simply say, “Upgrade CollectiveAccess,” point it at production, and hope everyone has a nice afternoon.
For me, there was no realistic way to complete this safely without AI. An experienced server and CollectiveAccess administrator could certainly do it manually. I am not one, and the available documentation was not sufficient for me to identify and resolve everything we encountered.
AI did not make the process automatic. It made it possible for me to inspect the code, understand errors, build a controlled staging process, test the results, and distinguish our configuration problems from reproducible software defects.
What worked for us
1. Leave production alone
We did not upgrade production in place.
We created a completely separate staging installation with:
- A separate database.
- A separate copy of all media.
- A separate URL.
- Clean Providence and Pawtucket 2.0 source code.
- Staging-specific configuration, paths, caches, and logs.
Production remained available throughout the work.
This is the single most important safety decision we made. Staging should be disposable. Production should be boring.
2. Clone more than the database
The database alone does not recreate a working CollectiveAccess installation.
We also had to account for:
- The Providence and Pawtucket
setup.php configuration.
- Providence configuration overrides under
app/conf/local.
- Custom print templates under
app/printTemplates.
- The Pawtucket custom theme and its configuration.
- The complete media directory.
- Server links between the Providence and Pawtucket media directories.
- Application URLs, database credentials, cache settings, and file paths.
Check __CA_DB_DATABASE__, __CA_DB_USER__, and __CA_DB_PASSWORD__ in every active setup.php. A staging application configured with production database credentials can modify production data.
Every staging path and server link must be checked after cloning. A staging Pawtucket installation must not quietly point back to production media.
Do not copy old app/tmp contents into the new installation. Begin with empty, writable temporary directories so staging does not inherit compiled configuration, cache files, locks, or other temporary state from the old application.
Do not copy the entire old application over the new 2.0 installation. Start with clean 2.0 code and deliberately bring forward only the local configuration and custom files that are still required.
I would also avoid copying an old full app.conf over the maintained 2.0 configuration. Preserve local overrides, not obsolete defaults.
3. Verify PHP from the actual package
Do not assume that “PHP 8 compatible” tells you which PHP 8 release your installed package requires.
Inspect the requirements of the exact Providence release you downloaded and verify both:
- The PHP version used by the web server.
- The PHP version used from the command line.
Those can be different.
Also compare the required PHP modules before running the migration. In our case, the bundled dependencies in the official Providence 2.0.11 package required PHP 8.4 on the command line. Verify the requirements of your own downloaded package rather than assuming they are identical.
4. Migrate the staging database
Once the staging database, media, configuration, PHP environment, and paths were isolated, we ran the official migration utility:
caUtils update-from-1-7
The migration should be treated as a controlled database operation, not as an ordinary application update.
Preserve a fresh database copy before each serious attempt. If a migration stops partway through, preserve the evidence and start again from a clean database copy rather than improvising repairs inside a partially migrated database.
A completed migration also needs validation. A final message on the screen is not enough. Confirm the database revision, expected tables, record counts, search behavior, and application configuration.
5. Expect to reconstruct an older Pawtucket theme
Our old Pawtucket theme could not simply be dropped into Pawtucket 2.0 and considered upgraded.
Pawtucket themes replace files from the maintained default theme. An old custom template can therefore replace a working 2.0 template with code written for an older version.
We rebuilt our theme around the maintained 2.0 structure and restored our custom behavior selectively. That included navigation, browse displays, detail pages, search behavior, archives, maps, galleries, login behavior, and other presentation elements.
The goal was to preserve the useful behavior and appearance of the old site without carrying the obsolete application structure forward.
This was a substantial portion of the project.
6. Test the whole system
A working homepage does not mean the upgrade is finished.
We tested, among other things:
- Providence login and administration.
- Pawtucket login and public access.
- Basic and advanced search.
- Browse facets and results.
- Object, entity, collection, place, and storage-location details.
- Images, PDFs, audio, video, and generated media versions.
- Maps and timelines.
- Archives and collection hierarchies.
- Custom pages and galleries.
- User roles and permissions.
- Background task queues.
- Configuration checks.
- Media checksum and fixity checks.
- Outgoing email.
- Custom theme behavior on desktop and mobile.
- The actual destinations of media-directory links.
We also checked that staging had no route back into production data or media.
7. Separate local problems from upstream defects
Not every failure was a CollectiveAccess bug. Some problems were caused by missing configuration, old theme files, cache behavior, or server setup.
Other problems were reproducible in the unmodified 2.0.11 source.
We documented those separately and submitted focused GitHub issues with reproduction steps and links to the relevant source code.
That distinction matters. A local workaround may get your site running, but it does not necessarily identify or correct the underlying software problem.
Instructions for your AI assistant
If you use AI to assist with the upgrade, I suggest beginning with instructions similar to these:
Help me upgrade CollectiveAccess from 1.x to 2.0.
Production must remain unchanged until a completely separate staging installation has been migrated, tested, and accepted.
Begin by inspecting and documenting the exact Providence, Pawtucket, PHP, web-server, and database versions.
Identify the current database, media, configuration, theme, print-template, cache, log, and temporary-file locations. Resolve and verify every media-directory link.
Build a staging-only upgrade plan before changing anything.
Staging must use a separate database, separate media, staging-specific credentials and URLs, clean CollectiveAccess 2.0 source code, and only the local configuration and custom files that are still required.
Never allow a staging path or media link to point to production.
Before each material change, explain what will change, the exact target, how the change will be validated, and how it can be reversed.
Then either execute the change through a shared terminal with my approval or give me the exact command to run. Use a shared browser for live validation when available.
Inspect the installed CollectiveAccess code and the command-specific caUtils help before recommending a command. Do not infer that a command is safe from its name.
Test Providence, Pawtucket, media, search, browse, authentication, permissions, background processing, configuration, fixity, and the custom theme before proposing production cutover.
Preserve a written record of completed work, unresolved issues, workarounds, and final regression tests.
Do not modify production or perform the final cutover without my explicit approval.
AI should be treated as a technical collaborator, not an unattended upgrade script.
It is exceptionally useful for reading source code, comparing versions, interpreting errors, generating controlled commands, maintaining documentation, and remembering what has already been tested. It still needs boundaries, verification, and a human making the consequential decisions.
Where we are now
The difficult part of our upgrade is complete. We have a working 2.0.11 evaluation environment, clean media-fixity results, documented maintenance procedures, reconstructed theme behavior, and a defined set of final regression tests.
Production remains unchanged until the evaluation is accepted and the final migration and rollback procedure are ready.
I am posting this because the original answers were helpful as a starting direction, but I do not want the next nontechnical administrator to interpret “copy the database, configuration, and media” as the complete procedure. There is considerably more hiding inside that sentence.
I hope this saves someone else a few days, or at least gives their AI assistant a much better place to start.
For transparency, this upgrade and this post were completed with extensive assistance from ChatGPT Work and Codex using the GPT-5.6 Sol Extra High model, at a total cost of roughly $200 in AI credits. There is no reasonable way I could have completed this project without that assistance.
