Skip to content

Archipelago-deployment-live: upgrading Archipelago 1.4.0 to 1.5.0 (Drupal 10.2.x to 10.4.x)

What is this documentation for?

If you already have a well-set-up and well-loved Archipelago (1.4.0) running Drupal 10.2 or more recent (D10), this documentation will allow you to update to 1.5.0 on latest Drupal 10.4.x without any major issues. Even if Archipelago is Drupal 11.1 (as the time of the writing of this guide) compatible (with some patches) we do not recommend upgrading until version 11 is more stable. Archipelago 1.6.0 will be Drupal 11 tested and proven in production.

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.4.0 (working, tested) deployed using provided instructions via Docker and running Drupal 10.
  • Attention span/focus to read/follow each instruction (even if they feel redundant and maybe even a drag). Don't do an update if you are tired/in a rush. Ok?
  • Basic knowledge, patience and instincts (+ courage) on how to run Terminal Commands, composer and drush.
  • 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.
  • Your current git tree (the branch you are running) has no uncommitted/untracked changes. This is important. Make sure your git status and git log are clean.

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:

Export/backup all of your live Archipelago 1.4.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

Step 2:

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 3:

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 4:

Now let's tar.gz the whole ensemble with data and configs. We will exclude here the local source caches generated by Cantaloupe and also the minio data folder. If these or not exist will depend on how custom your deployment is setup.

As an example we will save the gzipped tar into your $HOME folder. As a good practice we append the current date (YEAR-MONTH-DAY) to the filename. Here we assume today is June 18th of 2025. Please make sure you have enough space for this operation. If not use a different partition/mount. Databases and Solr might use a lot of space. As noted before, we are, on purpose, ignoring archipelago-deployment-live/data_storage/minio-data (in case you are not running S3 on the cloud) but you could include it if you have plenty of space left on your backup destination path/mount/drive.

We will cd back to the parent folder of your running archipelago-deployment-live folder (and we assume archipelago-deployment-live is how you named your git cloned 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/minio-data --exclude=archipelago-deployment-live/data_storage/iiiftmp -czvpf $HOME/archipelago-deployment-D10-20250618.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-20250618.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

If something went wrong, fix your command, make sure you have plenty of space (delete the wrong tar.gz too!) and try again. Don't move to a next step UNTIL your backup is safe and verified.

Step 5:

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

Good. Now it's safe to begin the Software upgrade process. This guide is separated into two upgrade process. First code base (Archipelago/Drupal). Once that is done and tested and you are all good and happy, you can optionally (but ideally) move into Services/Docker Container and services upgrades, which can be more challenging and (WUH!) might require deleting your Solr core clean and re-indexing (means no search results will appear while that is ongoing; time consuming, depending on the size of your server could be even a few days!, and will also mean temporarily diminished discoverability for your end users; No simple way around it other than running 2 Solr Servers and swapping them afterwards and that, my friends, is out of scope for this guide).

Upgrading to Archipelago 1.5.0 (Software/Code)

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.

In previous releases we shared with you all a list of step by step commands (which we do here too) but, given that we know (someone told us!) you are running your own extra modules, extre themes, probably already updated some libraries or even patches we want to share a (or a DYI future proof) new way of "understanding" an upgrade that will apply, from now on, to every release (and is version independent).

Note: you don't need to run the following commands, we already condensend all needed command derived from this explanation on STEP 1 for you, but: learning how to diff a JSON file (as is composer.json) or even a YAML file (e.g when comparing Drupal configurations) is a good goal if you are in charge of supporting/maintinging a live instance of Archipelago.

This approach entails: - Understand what changed between Archipelago releases in composer.json - Understand what is different between the current (vanilla) Archipelago releaseand your own/live (custom) composer.json. - And use this superpower/new knowledge in the future to approach the update in a simpler/consistent way.

To be able to explain this, we will introduce a new tool named jd.

In concrete, to exemplify the approach, the following command diffs two composer.json files (downloaded from https://raw.githubusercontent.com/esmero/archipelago-deployment-live/refs/heads/1.4.0/drupal/composer.default.json and https://raw.githubusercontent.com/esmero/archipelago-deployment-live/refs/heads/1.5.0/drupal/composer.default.json respectively) 

myself@my-server ~ % jd -set composer.default-1.4.0.json composer.default-1.5.0.json
@ ["config","allow-plugins","tbachert/spi"]
+ true
@ ["description"]
- "Project template for Drupal 10/Archipelago projects with composer"
+ "Project template for Drupal 10 /Archipelago projects with composer"
@ ["extra","patches","drupal/core"]
- {"https://www.drupal.org/project/drupal/issues/3364109":"https://git.drupalcode.org/project/drupal/-/merge_requests/4092.diff"}
@ ["extra","patches","ankitpokhrel/tus-php"]
+ {"Less Cache writes during upload fix":"patches/tus-file-cache.patch"}
@ ["extra","patches","drupal/better_exposed_filters"]
+ {"D10.3 Reset Fix":"https://www.drupal.org/files/issues/2024-07-08/3459811-6.patch"}
@ ["extra","patches","drupal/facets"]
+ {"D10.3 Facet Ajax fix":"https://www.drupal.org/files/issues/2024-08-10/3052574-session-not-set-warning-251.patch"}
@ ["extra","patches","league/openapi-psr7-validator"]
+ {"Fixes OpenAPI 1.8 compat":"https://github.com/DiegoPino/openapi-psr7-validator/commit/94e9df4c152d0db46cfa475fa8bb319ff5ac551a.patch"}
@ ["require","archipelago/ami"]
- "0.8.0.x-dev"
+ "0.9.0.x-dev"
@ ["require","archipelago/archipelago_subtheme"]
- "1.4.0.x-dev"
+ "1.5.0.x-dev"
@ ["require","cebe/php-openapi"]
- "^1"
+ "1.8"
@ ["require","cweagans/composer-patches"]
- "^1.6"
+ "^1"
@ ["require","devizzent/cebe-php-openapi"]
- "1.0.3"
@ ["require","drupal/aggregator"]
- "^2.1"
+ "^2.2"
@ ["require","drupal/better_exposed_filters"]
- "^6.0.3"
+ "^7"
@ ["require","drupal/core"]
- "10.2.10"
+ "^10.4"
@ ["require","drupal/core-composer-scaffold"]
- "^10.2.10"
+ "^10.4"
@ ["require","drupal/core-project-message"]
- "^10.2.10"
+ "^10.4"
@ ["require","drupal/core-recommended"]
- "^10.2.10"
+ "^10.4"
@ ["require","drupal/ds"]
- "dev-3.x"
+ "^3.23"
@ ["require","drupal/facets"]
- "2.0.x-dev@dev"
+ "2.0.x-dev"
@ ["require","drupal/search_api"]
- "^1.2"
+ "1.x-dev@dev"
@ ["require","drupal/search_api_solr"]
- "4.3.4"
+ "^4.3"
@ ["require","drupal/twig_field"]
- "^1.0"
+ "^2"
@ ["require","drupal/webform"]
- "6.2.0-RC3"
+ "^6.2"
@ ["require","php"]
- "\u003e=8.0"
+ "\u003e=8.1"
@ ["require","react/child-process"]
- "^0.6.1"
+ "^0.6"
@ ["require","react/event-loop"]
- "^1.1"
+ "^1.5"
@ ["require","react/promise"]
- "^2.7"
+ "^3.2"
@ ["require","strawberryfield/format_strawberryfield"]
- "1.4.0.x-dev"
+ "1.5.0.x-dev"
@ ["require","strawberryfield/strawberry_runners"]
- "0.8.0.x-dev"
+ "0.9.0.x-dev"
@ ["require","strawberryfield/strawberryfield"]
- "1.4.0.x-dev"
+ "1.5.0.x-dev"
@ ["require","strawberryfield/webform_strawberryfield"]
- "1.4.0.x-dev"
+ "1.5.0.x-dev"
@ ["require","vlucas/phpdotenv"]
- "^5.1"
+ "^5.6"
@ ["require","webmozart/path-util"]
- "^2.3"
@ ["require","ankitpokhrel/tus-php"]
+ "^2.4"
@ ["require","archipelago/archipelago_subtheme_chiloe"]
+ "dev-main"
@ ["require","drupal/codemirror_editor"]
+ "^2.0"
@ ["require-dev","drupal/core-dev"]
- "^10"
+ "^10.4"

The @ symbolizes the JSON key(s) that is/are affected. A + means new to 1.5.0, a - means removed from 1.5.0, all this compared against our previous release, 1.4.0.

If you are still with us (sorry this might be a lot, but DevOps is hard labor and is important to understand the "why" as much as getting it right), you might notice that this is actually "cleaner" than comparing two JSON files just line by line and trying to figure out what changed/what needs to be added. Moreover, jd has a very nice feature: it allows you to generate this visual output as "patch" (not covered in this guide). Does that trigger some ideas?

Note 2: Important to know/learn. Even if all packages are managed by composer, blindly uninstalling (not upgrading...we mean actually removing) any package that starts with drupal/ without first drush pm-uninstall it from Drupal will lead to errors and constant notifications from there on that you have an installed module that has missing source files. Don't do it. Always cleanly uninstall components/modules first from Drupal if you are removing them. Then composer delete them. You have been warned! (:

So. With this information at hand our goal is to Patch your current running composer.json (which as said before will/might have Packages/patches and other things Archipelago does not provide and we can't nor want to touch) by just affecting what Archipelago provides/changed between the vanilla versions of the previous and the current release.

The gist: For Step 1, We converted each + followed into a composer require and each - that is not preceded or followed by a + into a composer delete command followed also by a few JSON merges. Anything that is a nested set of keys, e.g for:

@ ["config","allow-plugins","tbachert/spi"]
+ true
--> is to be converted into a composer JSON merge command, as documented here

Step 1. Updates for key Drupal and Archipelago modules

Now that you know (if you read all we tried to explain in step 0) how commands for an updated are generated, you can actually start upgrading.

Start the actual upgrade process by running the following commands (line by line):

docker exec -ti esmero-php bash -c "composer config --json --merge allow-plugins.tbachert/spi true" 
docker exec -ti esmero-php bash -c "composer config --json --merge description 'Project template for Drupal 10 /Archipelago projects with composer'"

Do you have custom Patches (not provided by Archipelago) that are not provided by the following snippet (see the extra section of your composer.json)?

"patches": {
             "drupal/facets": {
                "D10.3 Facet Ajax fix": "https://www.drupal.org/files/issues/2024-08-10/3052574-session-not-set-warning-251.patch"
             },
             "drupal/better_exposed_filters": {
                "D10.3 Reset Fix": "https://www.drupal.org/files/issues/2024-07-08/3459811-6.patch"
             },
             "ankitpokhrel/tus-php": {
                "Less Cache writes during upload fix": "patches/tus-file-cache.patch"
             },
             "league/openapi-psr7-validator": {
                "Fixes OpenAPI 1.8 compat": "https://github.com/DiegoPino/openapi-psr7-validator/commit/94e9df4c152d0db46cfa475fa8bb319ff5ac551a.patch"
             }
          }

If the answer is "YES", then please edit (nano/pico/vi/vim) your composer.json and only remove (if present) the following entry. If there is a "drupal/core" entry, and the only one present is the following you can delete the whole "drupal/core" key. If you have other "drupal/core" entries, only delete the one with key "https://www.drupal.org/project/drupal/issues/3364109". Make sure your composer.json IS STILL VALID JSON after your change and save it.

"patches": {
     "drupal/core" : {
       "https://www.drupal.org/project/drupal/issues/3364109":"https://git.drupalcode.org/project/drupal/-/merge_requests/4092.diff"}
    }
}

Now run this command:

docker exec -ti esmero-php bash -c "composer config --json --merge extra.patches '{
             \"drupal/facets\": {
                \"D10.3 Facet Ajax fix\": \"https://www.drupal.org/files/issues/2024-08-10/3052574-session-not-set-warning-251.patch\"
             },
             \"drupal/better_exposed_filters\": {
                \"D10.3 Reset Fix\": \"https://www.drupal.org/files/issues/2024-07-08/3459811-6.patch\"
             },
             \"ankitpokhrel/tus-php\": {
                \"Less Cache writes during upload fix\": \"https://raw.githubusercontent.com/esmero/archipelago-deployment-live/refs/heads/1.5.0/drupal/patches/tus-file-cache.patch\"
             },
             \"league/openapi-psr7-validator\": {
                \"Fixes OpenAPI 1.8 compat\": \"https://github.com/DiegoPino/openapi-psr7-validator/commit/94e9df4c152d0db46cfa475fa8bb319ff5ac551a.patch\"
             }
          }'"

If the answer is "NO", no need to edit manually, just run this command:

docker exec -ti esmero-php bash -c "composer config --json extra.patches '{
             \"drupal/facets\": {
                \"D10.3 Facet Ajax fix\": \"https://www.drupal.org/files/issues/2024-08-10/3052574-session-not-set-warning-251.patch\"
             },
             \"drupal/better_exposed_filters\": {
                \"D10.3 Reset Fix\": \"https://www.drupal.org/files/issues/2024-07-08/3459811-6.patch\"
             },
             \"ankitpokhrel/tus-php\": {
                \"Less Cache writes during upload fix\": \"https://raw.githubusercontent.com/esmero/archipelago-deployment-live/refs/heads/1.5.0/drupal/patches/tus-file-cache.patch\"
             },
             \"league/openapi-psr7-validator\": {
                \"Fixes OpenAPI 1.8 compat\": \"https://github.com/DiegoPino/openapi-psr7-validator/commit/94e9df4c152d0db46cfa475fa8bb319ff5ac551a.patch\"
             }
          }'"

Note: notice how instead of using "patches/tus-file-cache.patch", as described in the diff, we are using instead the 1.5.0 github repo URL for that file. Reason i:s we have not yet decided (or more like you need to decide) if you are already in a git diverging branch and will bring ONLY the files you need to your current branch OR, you are going to make a git merge origin/1.5.0 overwriting all the defaults (including YAML files) of your current git branch/status and bring the new release into your branch. In other words, you don't have inside your drupal/patches folder the tus-file-cache.patch at all.

Continuing now with packages:

docker exec -ti esmero-php bash -c "composer require archipelago/ami:0.9.0.x-dev strawberryfield/strawberry_runners:0.9.0.x-dev archipelago/archipelago_subtheme:1.5.0.x-dev strawberryfield/strawberryfield:1.5.0.x-dev strawberryfield/webform_strawberryfield:1.5.0.x-dev strawberryfield/format_strawberryfield:1.5.0.x-dev archipelago/archipelago_subtheme_chiloe:dev-main --update-with-dependencies --no-update"

docker exec -ti esmero-php bash -c "composer remove devizzent/cebe-php-openapi webmozart/path-util --no-update"

docker exec -ti esmero-php bash -c "composer require cebe/php-openapi:^1.8 cweagans/composer-patches:^1 drupal/aggregator:^2.2 drupal/better_exposed_filters:^7 drupal/ds:^3.23 drupal/facets:2.0.x-dev drupal/search_api:1.x-dev@dev drupal/search_api_solr:^4.3 drupal/twig_field:^2 drupal/webform:^6.2 react/child-process:^0.6 react/event-loop:^1.5 react/promise:^3.2 vlucas/phpdotenv:^5.6 ankitpokhrel/tus-php:^2.4 drupal/codemirror_editor:^2.0  --update-with-dependencies --no-update"

From inside your archipelago-deployment-live repo folder we are now going to open up file permissions for some of your most protected Drupal files.

sudo chmod 777 drupal/web/sites/default
sudo chmod 666 drupal/web/sites/default/*settings.php
sudo chmod 666 drupal/web/sites/default/*services.yml

and also from inside your archipelago-deployment-live, fetch a new composer helper file needed since we are nolonger using webmozart/pathutil.

rm drupal/scripts/composer/ScriptHandler.php
wget https://raw.githubusercontent.com/esmero/archipelago-deployment-live/refs/heads/1.5.0/drupal/scripts/composer/ScriptHandler.php -O drupal/scripts/composer/ScriptHandler.php

Finally, Drupal itself.

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.4' 'drupal/core-recommended:^10.4' 'drupal/core-composer-scaffold:^10.4' 'drupal/core-project-message:^10.4' --update-with-dependencies --no-update"
docker exec -ti esmero-php bash -c "composer require 'drupal/core-dev:^10.4' --dev --update-with-dependencies --no-update"

Step 2. Update PHP from 8.1 to 8.3

This is a recommended upgrade. The 8.1 code is (still) compatible but Drush (13) requires PHP 8.2. Since 1.5.0 Ships with a clean-of-security-issues PHP container (with FFMPEG also!) that is LITERALLY (professional term) crazy-cakes-fast, we would strongly encourage you to do the following before finishing the composer updates.

From inside your archipelago-deployment-live folder, nano/pico/vim/vi your docker-compose.yml file. e.g.

nano deploy/ec2-docker/docker-compose.yml

Find the PHP container line (as seen here https://github.com/esmero/archipelago-deployment-live/blob/1.4.0/deploy/ec2-docker/docker-compose-aws-s3.yml#L45). Should be something like 

    image: "esmero/php-8.1-fpm:1.2.0-multiarch"

And replace with

    image: "esmero/php-8.3-fpm:1.5.0-multiarch"

Save. Now navigate to your ec2-docker folder and fetch all the updates by doing this:

cd deploy/ec2-docker
docker-compose up -d

That will download the newer image, and restart the php (esmero-php) container. Now we can fetch Drush version 13.

 docker exec -ti esmero-php bash -c "composer require drush/drush:^13  --update-with-dependencies --no-update"

Step 3. Applying Composer updates/changes.

And now we will make all have an actual effect!

docker exec -ti esmero-php bash -c "composer update -W"

Well done! If you see no issues and all ends in Green colored messages, all is good!

What if all is not OK, and I see red and a lot of dependency explanations?

Just in case try to run this again.

docker exec -ti esmero-php bash -c "composer update -W"

Sometimes the internet is a pokey place and remote servers timeout, things are strange. Sometimes people skip steps (did you?) If after trying again and also self-doubting and retracing your steps, things are still strange, you might need to do some troubleshooting.

Maybe you have custom modules that are NO longer Drupal 10.4 compatible? If so, you may see errors. You should check each package website's (normally https://www.drupal.org/project/the_module_name) to see 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"

followed by 

docker exec -ti esmero-php bash -c "composer update -W"

Repeat until no more errors pop-up.

If a Drupal 10 compatible version of a module is not available, try to find a replacement module that does something similar, but in any case you may end up having to remove it before proceeding. Give us a pin on our public slack channel/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"
docker exec -ti esmero-php bash -c "composer update -W"

If you keep seeing 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.5.0.x-dev requires solarium/solarium (^6)     
drupal/search_api_solr         4.3.10      requires solarium/solarium (^6.3.7)

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 4: Update your Database (and run hook updates)

Now run one final database update command:

docker exec -ti esmero-php bash -c "drush updatedb"

Step 5: Optional Syncs (Optional)

Optionally, you can sync your new Archipelago 1.5.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.5.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.5.0. It's a like clean (danger!) 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 6: Update (or not - Opitional) your Metadata Display Entities and menu items

Recommended: If you want to add new templates and menu items 1.5.0 provides, you need to fetch everything from this remote https://github.com/esmero/archipelago-deployment-live/tree/1.5.0/drupal/d8content to your local installation into the same folder structure/location, then replace your local deploy.sh and update_deployed.sh scripts which can be found inside your base archipelago deployment folder inside drupal/scripts/archipelago with

https://raw.githubusercontent.com/esmero/archipelago-deployment-live/refs/heads/1.5.0/drupal/scripts/archipelago/deploy.sh

and

https://raw.githubusercontent.com/esmero/archipelago-deployment-live/refs/heads/1.5.0/drupal/scripts/archipelago/update_deployed.sh

from the new release and, as described in the general (from zero) 1.5.0 Deployment Instructions replace the http://esmero-web with your real domain. On a terminal navigate to your base archipelago deployment folder and run the following command replacing your.domain.org with your actual domain.

 sed -i 's/http:\/\/esmero-web/https:\/\/your.domain.org/g' drupal/scripts/archipelago/deploy.sh
 sed -i 's/http:\/\/esmero-web/https:\/\/your.domain.org/g' drupal/scripts/archipelago/update_deployed.sh

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.4.0 content.

Once that is done, you could choose to update all Metadata Displays (twig templates) we ship with new 1.5.0 versions (including heavily adjusted IIIF manifest templates 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 7

Please login to your Archipelago and test/check all is working! Enjoy Archipelago 1.5.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.

Upgrading to Archipelago 1.5.0 new Services and Containers

Step 1: Edit docker-compose.yml

For this release there are larger updates on the Docker backend level. PHP was updated from 8.1 to 8.3 and Solr 9 was updated from 9.2 to 9.8 and Database (MYSQL and MariaDB) also got a version bump. As with 1.4.0 Esmero NLP with Machine Learning Model Endpoints is not meant for production/public access. Reasons are many (same as before): 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.5.0/deploy/ec2-docker/docker-compose-aws-s3-arm64.yml - https://github.com/esmero/archipelago-deployment-live/blob/1.5.0/deploy/ec2-docker/docker-compose-aws-s3.yml

And selectively copy images/enviromentals into your production docker-compose.yml file. Please also read and use General Installation guide for 1.5.0 to ensure you are using the right, and new, .env enviromentals. Basically have it at hand to validate all your changes.

Special NOTE: Solr 9.8 uses Modules instead of libraries and also uses a different Solr OCR Highlight version, which can be seen here. We have a separte guide (longer/more extensive) for upgrading Solr. You can either start with it or leave it to the end. Up to you

Special Note2: Anubis. Anubis is a Web Application Firewall that will aid in traffic control generated by AI/ML Bots. It uses a special NGINX configuration and special .env variables. Don't upgrade to Anubis YET during this process. We will provide another guide soon. You can also check the General Installation guide for 1.5.0 to install it, since you are actually NOT upgrading but installing from ZERO, with of course, the proper precautions that IF you have already customized your nginx.default.template file, you will need to bring those into the newer/needed https://raw.githubusercontent.com/esmero/archipelago-deployment-live/refs/heads/1.5.0/config_storage/nginxconfig/template/nginx.conf.template.anubis which needs to be used as replacement. If unsure. Don't install/upgrade to Anubis.

Special Note3:. You already updated PHP from 8.1 to 8.3 in Step 2. Update PHP from 8.1 to 8.3. So please save some time, don't do it again.

Ok. Done with the Notes.

If you have not already, navigate to deploy/ec2-docker and run:

docker-compose down

Then open your docker-compose.yml file and with one of the previous links open, edit the corresponding service definitions EXCEPT SOLR (we have a different guide, we told you so already!):

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 databsae 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
e9361ed424ab   esmero/cantaloupe-s3:6.0.5-noturbojpeg-multiarch       "sh -c 'java -Dcanta…"   10 minutes ago   Up 10 minutes   0.0.0.0:8183->8182/tcp             esmero-cantaloupe
1dc524aeb6b4   mariadb:10.6.22-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
aa82d6b42ec6   esmero/php-8.3-fpm:1.5.0-multiarch                     "docker-php-entrypoi…"   10 minutes ago   Up 10 minutes   9000/tcp                           esmero-php
458e826199bd   esmero/esmero-nlp:1.4.2-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). Notice Solr is at 9.2 here still. If you followed the Solr 9.2 to 9.8 guide it will be at 9.8

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.

Caring & Coding + Fixing + Testing

License

GPLv3