Archipelago-deployment-live: upgrading Archipelago 1.3.0 to 1.4.0 (Drupal 10.1 to 10.2.x)
What is this documentation for?
If you already have a well-set-up and well-loved Archipelago (1.3.0) running Drupal 10.1 or 10.2 (D10), this documentation will allow you to update to 1.4.0 on latest Drupal 10.2 without any major issues. Even if Archipelago is 10.3.1 (as the time of writing this guide) compatible we do not recommend upgrading still until some of the Drupal core and contributed module issues are solved and that minor release is more stable.
This documentation is meant to be a guide/helper, not a single-click-magic solution. Why? Because your Drupal environment and your local github branches for this whole project might have diverged really a lot from a vanilla Archipelago base deployment. You might have new templates, custom composer.json, new modules, changed webforms and Views. That is not an Archipelago issue, more like a 'How do I keep any Drupal instance, YAML files, custom configurations and modules in version control and in sync as I upgrade other parts' issue.
Requirements
- An archipelago-deployment-live instance 1.3.0 (working, tested) deployed using provided instructions via Docker and running Drupal 10.
- Basic knowledge, patience and instincts (+ courage) on how to run Terminal Commands,
composeranddrush. - Patience(again). You can't skip steps here.
- For shell Commands documented here please copy line by line--not the whole block.
- You are running already version control and know how to git pull/push/merge.
Backing up and preparing for the upgrade
Backups are always going to be your best friends. Archipelago's code, database, and settings are mostly self-contained in your current archipelago-deployment-live repo folder, and backing up is simple because of that.
Step 1:
On a terminal, cd into your running archipelago-deployment-live folder, then cd inside the deploy/ec2-docker subfolders and shut down your docker-compose ensemble by running the following:
docker-compose down
Step 2:
Verify that all containers are actually down. The following command should return an empty listing:
docker ps
If anything is still running, wait a little longer and run the command again.
Step 3:
Now let's tar.gz the whole ensemble with data and configs. We will exclude here the local source caches generated by Cantaloupe. If these or not exist will depend on how custom your
deployment is.
As an example we will save this into your $HOME folder. As a good practice we append the current date (YEAR-MONTH-DAY) to the filename. Here we assume today is July 7th of 2024.
We will cd back to the parent folder of your running archipelago-deployment-live folder, so three levels down, assuming you are right now inside archipelago-deployment-live/deploy/ec2-docker
cd ../../..
sudo tar --exclude=archipelago-deployment-live/data_storage/iiifcache --exclude=archipelago-deployment-live/data_storage/iiiftmp -czvpf $HOME/archipelago-deployment-D10-20240707.tar.gz archipelago-deployment-live
The process may take a few minutes. Now let's verify that all is there and that the tar.gz is not corrupt.
tar -tvvf $HOME/archipelago-deployment-D10-20240707.tar.gz
You will see a listing of files, and at the end you will see something like this: Archive Format: POSIX pax interchange format, Compression: gzip. If corrupt (Do you have enough space? Did your ssh connection drop?) you will see the following:
tar: Unrecognized archive format
Step 4:
cd again into your running archipelago-deployment-live folder, then cd inside the deploy/ec2-docker
Restart your docker-compose ensemble, and wait a little while for all to start.
docker-compose up -d
Step 5:
Export/backup all of your live Archipelago 1.3.0, Drupal 10 configurations (this allows you to compare/come back in case you lose something custom during the upgrade).
docker exec esmero-php mkdir config/backup
docker exec esmero-php drush cex --destination=/var/www/html/config/backup
Good. Now it's safe to begin the upgrade process.
Upgrading to 1.4.0
Step 0: Get familiar with what changed.
We mean this. This is a new step. Running a Production Server requires some informed decision making and thus, we believe, a good pre-step is reviewing what changed between releases.
Step 1: Edit docker-composer.yml (optional)
For this release there are no larger updates on the Docker backend level (good!). Solr 9 was updated from 9.1 to 9.2 and Database (MYSQL and MariaDB) also got a version bump. Esmero NLP with Machine Learning Model Endpoints is not meant for production/public access and right now is for community evaluation only. Reasons are many: some technical (CPU/GPU and memory consumption not suited for a medium server) but mostly about usefulness, use cases, real needs driving the use of the tools we developed and the very much needed Community Discussion and Consensus on our Field's (GLAM) ethical concerns about this.
If you decide to upgrade your services please review one of these (based on your running Platform): - https://github.com/esmero/archipelago-deployment-live/blob/1.4.0/deploy/ec2-docker/docker-compose-aws-s3-arm64.yml - https://github.com/esmero/archipelago-deployment-live/blob/1.4.0/deploy/ec2-docker/docker-compose-aws-s3.yml
And selectively copy images/enviromentals into your production docker-compose.yml file.
For this, if you have not already, run:
docker-compose down
Then open your docker-compose.yml file and with one of the previous links open, edit the corresponding service definitions:
nano docker-compose.yml
Save your changes.
Step 2: docker pull and check
Time to fetch the latest branch and update our docker compose and composer dependencies. To pull the images and bring up the ensemble, run:
docker compose pull
docker compose up -d
Give all a little time to start. Please be patient. To ensure all is well, run (more than once if necessary) the following:
docker ps
You should see something like this if you synced all containers to the latest (your versions and databse might vary depending on your server's platform):
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
5b06ee366f58 jonasal/nginx-certbot "/docker-entrypoint.…" 10 minutes ago Up 10 minutes 0.0.0.0:8001->80/tcp esmero-web
86b685008158 solr:9.2.1 "docker-entrypoint.s…" 10 minutes ago Up 10 minutes 0.0.0.0:8983->8983/tcp esmero-solr
a4872b237e17 esmero/cantaloupe-s3:6.0.1-multiarch "sh -c 'java -Dcanta…" 10 minutes ago Up 10 minutes 0.0.0.0:8183->8182/tcp esmero-cantaloupe
bec0b31f3421 mariadb:10.6.18-focal "docker-entrypoint.s…" 10 minutes ago Up 10 minutes 3306/tcp esmero-db
85bedadf9732 redis:6.2-alpine "docker-entrypoint.s…" 10 minutes ago 10 minutes ago esmero-redis
6a9e9d8647a9 minio/minio:RELEASE.2022-06-11T19-55-32Z "/usr/bin/docker-ent…" 10 minutes ago Up 10 minutes 0.0.0.0:9000-9001->9000-9001/tcp esmero-minio
bc5327680ca7 esmero/php-8.1-fpm:1.2.0-multiarch "docker-php-entrypoi…" 10 minutes ago Up 10 minutes 9000/tcp esmero-php
d53729be1211 esmero/esmero-nlp:fasttext-multiarch "/usr/local/bin/entr…" 10 minutes ago Up 10 minutes 0.0.0.0:6400->6400/tcp esmero-nlp
Important here is the STATUS column. It needs to be a number that goes up in time every time you run docker ps again (and again).
Step 3. Updates for key Drupal and Archipelago modules
Now we are going to tell composer to update the key Drupal and Archipelago modules.
We don't need to disable any modules this time (great) but we will need to lose up some dependencies to target a stable Drupal 10.2.7.
Notice how we will run composer commands using the --no-update argument which means composer won't have to resolve (nor fetch) library dependencies on every execution.
First, update the versions used for these Drupal modules:
docker exec -ti esmero-php bash -c "composer require 'drupal/color:1.x-dev@dev' 'drupal/config_inspector:dev-2.1.x' 'drupal/search_api_solr:4.3.4' 'drupal/search_api:^1.3' 'solarium/solarium:^6' 'egulias/email-validator:^4' 'drupal/upgrade_status:^4.3' --no-update --with-all-dependencies"
And now update the main Archipelago modules:
docker exec -ti esmero-php bash -c "composer require cebe/php-openapi:^1 'league/openapi-psr7-validator:0.22' 'devizzent/cebe-php-openapi:1.0.3' 'strawberryfield/strawberryfield:1.4.0.x-dev' 'strawberryfield/webform_strawberryfield:1.4.0.x-dev' 'strawberryfield/format_strawberryfield:1.4.0.x-dev' 'strawberryfield/strawberry_runners:0.8.0.x-dev' 'archipelago/ami:0.8.0.x-dev' 'archipelago/archipelago_subtheme:1.4.0.x-dev' --no-update --with-all-dependencies"
From inside your archipelago-deployment-live repo folder, and inside the drupal subfolder, we are now going to open up file permissions for some of your most protected Drupal files.
sudo chmod 777 web/sites/default
sudo chmod 666 web/sites/default/*settings.php
sudo chmod 666 web/sites/default/*services.yml
Step 4: Update Drupal Core to stable 10.2.7
We are going to remove additional select Drupal modules that are not 1.3.0 or D10 compliant.
Please run each of the following commands separately, in order, and do not skip any commands.
docker exec -ti esmero-php bash -c "composer require 'drupal/core:10.2.7' 'drupal/core-recommended:10.2.7' 'drupal/core-composer-scaffold:10.2.7' 'drupal/core-project-message:10.2.7' --update-with-dependencies --no-update"
docker exec -ti esmero-php bash -c "composer require 'drupal/core-dev:^10' --dev --update-with-dependencies --no-update"
Well done! If you see no issues and all ends in Green colored messages, all is good! Jump to Step 5
What if all is not OK, and I see red and a lot of dependency explanations?
If you have manually installed packages via composer in the past that are NO longer Drupal 10.2 compatible you may see errors. In that case you need to check each package website's (normally https://www.drupal.org/project/the_module_name) and check if there is a Drupal 10 compatible version.
If so run:
docker exec -ti esmero-php bash -c "composer require 'drupal/the_module_name:^VERSION_NUMBER_THAT_WORKS_ON_DRUPAL10_' --update-with-dependencies --no-update" and run **Step 3 ** again (and again until all is cleared)
If not, try to find a replacement module that does something similar, but in any case you may end up having to remove before proceeding. Give us a ping/slack/google group/open a github ISSUE if you find yourself uncertain about this.
docker exec -ti esmero-php bash -c "drush pm-uninstall the_module_name"
docker exec -ti esmero-php bash -c "composer remove drupal/the_module_name --no-update"
Step 5: Update composer.json
Now you need to update your composer.json file to include an important patch. Starting in your Archipelago deployment directory location, run the following commands:
nano composer.json
Inside your composer.json file, page down to the "patches" section and change the section to match exactly as follows:
"patches": {
"drupal/core": {
"https://www.drupal.org/project/drupal/issues/3364109": "https://git.drupalcode.org/project/drupal/-/merge_requests/4092.diff"
}
}
Save your changes and then run:
docker exec -ti esmero-php bash -c "composer update -W"
Note: again. If you see error messages of missing dependencies, invalid (stuck/old versions) libraries or conflicts, review each message and check what modules/libraries are not allowing you to upgrade. One way of understanding the chained dependency errors is to run:
docker exec -ti esmero-php bash -c "composer why some_namespace/some_library"
Example given:
docker exec -ti esmero-php bash -c "composer why solarium/solarium"
Will output:
drupal-composer/drupal-project 1.4.0.x-dev requires solarium/solarium (^6)
drupal/search_api_solr 4.3.4 requires solarium/solarium (^6.3.5)
If a given library/module/dependency is only required by drupal-composer/drupal-project you have space to loosen it up to a higher/more permissive version. If it dependends on other library/modules, those might be the culprits of not being able to upgrade it and normally the solution is to upgrade that library first (always using the --no-update argument) and then run docker exec -ti esmero-php bash -c "composer update -W" again.
Step 6: Update your Database (and run hook updates)
Now run one final database update command:
docker exec -ti esmero-php bash -c "drush updatedb"
Step 7: Optional Syncs
Optionally, you can sync your new Archipelago 1.4.0 and bring in all the latest configs and settings. This requires you do fetch, either via git or manually via wget or curl newer configs from https://github.com/esmero/archipelago-deployment-live/tree/1.4.0/drupal/config/sync into the same folder structure/location of your deployment.
For this you have two options (no worries, actually do worry, just remember you made a backup! Did you? Double check!):
Option 1. A Partial Sync, which will bring new configs and update existing ones but will not remove ones that only exist in your custom setup, e.g. new Webforms or View Modes.
docker exec esmero-php drush cim -y --partial
Option 2. A Complete Sync, which will bring new things and update existing but will also remove all the ones that are not part of 1.3.0. It's a like clean factory reset.
docker exec esmero-php drush cim -y
If all goes well here and you see no errors it's time to reindex Solr because there are new Fields. Run the following:
docker exec esmero-php drush search-api-reindex
docker exec esmero-php drush search-api-index
You might see some warnings related to modules dealing with previously non-existent data—-no worries, just ignore those.
If you made it this far you are done with code/devops (are we ever really?), and that means you should be able to (hopefully) stay in the Drupal 10 realm for a few years!
Step 8: Update (or not) your Metadata Display Entities and menu items
Recommended: If you want to add new templates and menu items 1.4.0 provides, you need to fetch everything from this remote https://github.com/esmero/archipelago-deployment-live/tree/1.4.0/drupal/d8content to your local installation into the same folder structure/location and then run:
docker exec -ti esmero-php bash -c 'scripts/archipelago/deploy.sh'
Important: If you don't download/sync/git merge (or your prefered method) then the command will add nothing, since you will be running this command against 1.3.0 content.
Once that is done, you can choose to update all Metadata Displays (twig templates) we ship with new 1.4.0 versions (e.g heavily adjusted IIIF manifests with Content Search API service definitions). Before you do this, we strongly recommend that you first make sure to manually (copy/paste) backup any Twig templates you have modified. If unsure, do not run the command that comes after this warning! You can always manually copy the new templates from the d8content/metadatadisplays folder which contains text versions (again, copy/paste) of each shipped template you can pick and use when you feel ready.
If you are sure (like really?) you really want to overwrite the ones you modified (sure, just checking?), then you can run this (make sure you edit that file):
docker exec -ti esmero-php bash -c 'scripts/archipelago/update_deployed.sh'
Done! (For realz now)
Step 9
Please login to your Archipelago and test/check all is working! Enjoy 1.4.0 under Drupal 10. Thanks! Also please keep all your new changes under version control. Check what has changed. git add and git commit -m "What i changed" as needed.
Step 10
If all looks good and you are not missing any functionality (please be thorough about testing), it is time to Jump to Upgrading to Solr 9.x
Need help? Blue Screen? Missed a step? Need a hug or someone that listens to you in silence?
If you see any issues or errors or need help with a step, please let us know (ASAP!). You can either open an issue in this repository or use the Google Group. We are here to help.