From b913f82fed7abd1366cad6f155e7fbf2dcd34055 Mon Sep 17 00:00:00 2001 From: Josh d'Entremont Date: Tue, 21 May 2024 13:51:43 -0300 Subject: [PATCH 1/4] updated layout of docker installion pages --- .../{ => docker}/docker-introduction.md | 2 +- .../{ => docker}/docker-prereq.md | 11 +------ .../isle-dc}/docker-available-commands.md | 0 .../docker-available-configuration.md | 0 .../isle-dc}/docker-basic-usage.md | 0 .../{ => docker/isle-dc}/docker-custom.md | 0 .../{ => docker/isle-dc}/docker-local.md | 8 +++++ .../isle-dc}/docker-maintain-drupal.md | 0 .../isle-dc}/docker-maintain-isle.md | 0 .../isle-dc}/docker-troubleshooting.md | 0 .../site-template}/site-template.md | 0 mkdocs.yml | 30 ++++++++++--------- 12 files changed, 26 insertions(+), 25 deletions(-) rename docs/installation/{ => docker}/docker-introduction.md (94%) rename docs/installation/{ => docker}/docker-prereq.md (94%) rename docs/installation/{ => docker/isle-dc}/docker-available-commands.md (100%) rename docs/installation/{ => docker/isle-dc}/docker-available-configuration.md (100%) rename docs/installation/{ => docker/isle-dc}/docker-basic-usage.md (100%) rename docs/installation/{ => docker/isle-dc}/docker-custom.md (100%) rename docs/installation/{ => docker/isle-dc}/docker-local.md (89%) rename docs/installation/{ => docker/isle-dc}/docker-maintain-drupal.md (100%) rename docs/installation/{ => docker/isle-dc}/docker-maintain-isle.md (100%) rename docs/installation/{ => docker/isle-dc}/docker-troubleshooting.md (100%) rename docs/installation/{ => docker/site-template}/site-template.md (100%) diff --git a/docs/installation/docker-introduction.md b/docs/installation/docker/docker-introduction.md similarity index 94% rename from docs/installation/docker-introduction.md rename to docs/installation/docker/docker-introduction.md index 3724cef0b..7105948c8 100644 --- a/docs/installation/docker-introduction.md +++ b/docs/installation/docker/docker-introduction.md @@ -12,4 +12,4 @@ ISLE's architecture using [Docker](https://www.docker.com/) separates out the "s ISLE is a suite of Docker containers that run the various components of Islandora: drupal, fedora, solr, alpaca, crayfish, matomo, etc. The individual containers are created (and automatically pushed to [Docker Hub](https://hub.docker.com/u/islandora)) by [ISLE BuildKit](https://github.com/Islandora-Devops/isle-buildkit). -In order to deploy the containers, however, you need to use a container orchestration tool. The ISLE project provides tools for running and maintaining the containers using docker-compose with [ISLE Docker Compose](https://github.com/Islandora-Devops/isle-dc). +In order to deploy the containers, however, you need to use a container orchestration tool. The ISLE project provides tools for running and maintaining the containers using docker-compose with [ISLE Docker Compose](https://github.com/Islandora-Devops/isle-dc) or [ISLE Site Template](https://github.com/Islandora-Devops/isle-site-template). \ No newline at end of file diff --git a/docs/installation/docker-prereq.md b/docs/installation/docker/docker-prereq.md similarity index 94% rename from docs/installation/docker-prereq.md rename to docs/installation/docker/docker-prereq.md index 252a969ec..6e3f6d3aa 100644 --- a/docs/installation/docker-prereq.md +++ b/docs/installation/docker/docker-prereq.md @@ -38,7 +38,7 @@ Docker Compose is a tool to simplify the process of running multiple Docker cont ### GNU Make -Make allows us to define commands that simplify installing and maintaining our Islandora site. For a complete list of available commands see the Makefile included with ISLE. +Make allows us to define commands that simplify installing and maintaining our Islandora site. For a complete list of available commands see the Makefile included with ISLE-DC. ### Composer @@ -58,7 +58,6 @@ Drush is a command line tool for managing your Drupal site. It comes installed i - Docker Compose version 2.x+ - GNU Make 4.0+ - Git 2.0+ -- [ISLE Docker Compose](https://github.com/islandora-devops/isle-dc) - At least 8GB of RAM (ideally 16GB) - An administrator account your machine (a.k.a. the host machine) - (Mac OS) Apple Developer Tools @@ -89,11 +88,3 @@ If you need to install Docker, we recommend using the application [Docker Deskto - Production or production-like development: 16GB **Swap**: Swap space is space borrowed from your hard disk drive to serve as makeshift RAM as needed. If you cannot provide as much RAM as you would like, increase this as is reasonable given your free disk space. - -## Installing ISLE Docker Compose - -Use Git to install the ISLE Docker Compose tool: - -`git clone https://github.com/islandora-devops/isle-dc` - -Tagged versions are available [here](https://github.com/Islandora-Devops/isle-dc/tags). diff --git a/docs/installation/docker-available-commands.md b/docs/installation/docker/isle-dc/docker-available-commands.md similarity index 100% rename from docs/installation/docker-available-commands.md rename to docs/installation/docker/isle-dc/docker-available-commands.md diff --git a/docs/installation/docker-available-configuration.md b/docs/installation/docker/isle-dc/docker-available-configuration.md similarity index 100% rename from docs/installation/docker-available-configuration.md rename to docs/installation/docker/isle-dc/docker-available-configuration.md diff --git a/docs/installation/docker-basic-usage.md b/docs/installation/docker/isle-dc/docker-basic-usage.md similarity index 100% rename from docs/installation/docker-basic-usage.md rename to docs/installation/docker/isle-dc/docker-basic-usage.md diff --git a/docs/installation/docker-custom.md b/docs/installation/docker/isle-dc/docker-custom.md similarity index 100% rename from docs/installation/docker-custom.md rename to docs/installation/docker/isle-dc/docker-custom.md diff --git a/docs/installation/docker-local.md b/docs/installation/docker/isle-dc/docker-local.md similarity index 89% rename from docs/installation/docker-local.md rename to docs/installation/docker/isle-dc/docker-local.md index 746270c57..2e94e59e3 100644 --- a/docs/installation/docker-local.md +++ b/docs/installation/docker/isle-dc/docker-local.md @@ -4,6 +4,14 @@ When developing locally, your Drupal site resides in your `isle-dc/codebase` fol Drupal container. This lets you update code using the IDE of your choice on your host machine, and the changes are automatically reflected on the Drupal container. +## Installing ISLE Docker Compose + +Use Git to install the ISLE Docker Compose tool: + +`git clone https://github.com/islandora-devops/isle-dc` + +Tagged versions are available [here](https://github.com/Islandora-Devops/isle-dc/tags). + ## Getting Started If you don't already have a Drupal site, you'll be given a basic setup using Drupal 9 and the diff --git a/docs/installation/docker-maintain-drupal.md b/docs/installation/docker/isle-dc/docker-maintain-drupal.md similarity index 100% rename from docs/installation/docker-maintain-drupal.md rename to docs/installation/docker/isle-dc/docker-maintain-drupal.md diff --git a/docs/installation/docker-maintain-isle.md b/docs/installation/docker/isle-dc/docker-maintain-isle.md similarity index 100% rename from docs/installation/docker-maintain-isle.md rename to docs/installation/docker/isle-dc/docker-maintain-isle.md diff --git a/docs/installation/docker-troubleshooting.md b/docs/installation/docker/isle-dc/docker-troubleshooting.md similarity index 100% rename from docs/installation/docker-troubleshooting.md rename to docs/installation/docker/isle-dc/docker-troubleshooting.md diff --git a/docs/installation/site-template.md b/docs/installation/docker/site-template/site-template.md similarity index 100% rename from docs/installation/site-template.md rename to docs/installation/docker/site-template/site-template.md diff --git a/mkdocs.yml b/mkdocs.yml index 3d0badc5a..1e5b06535 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -111,20 +111,22 @@ nav: - '8.x-2.0 Release Notes': 'release-notes/8.x-2.0.md' - 'Older Release Notes': 'https://github.com/Islandora/documentation/tree/main/docs/release_notes' - 'Install a Demo': 'installation/install-a-demo.md' - - 'ISLE-DC': - - 'Introduction to ISLE': 'installation/docker-introduction.md' - - 'Prerequisites': 'installation/docker-prereq.md' - - Install Islandora: - - 'Installing a Development Server': 'installation/docker-local.md' - - 'Installing a Staging/Production Server': 'installation/docker-custom.md' - - Maintaining Islandora: - - 'Basic Usage': 'installation/docker-basic-usage.md' - - 'Maintaining Drupal': 'installation/docker-maintain-drupal.md' - - 'Maintaining ISLE': 'installation/docker-maintain-isle.md' - - 'Available Commands': 'installation/docker-available-commands.md' - - 'Available Configuration': 'installation/docker-available-configuration.md' - - 'Troubleshooting' : 'installation/docker-troubleshooting.md' - - 'ISLE Site Template': 'installation/site-template.md' + - 'Docker': + - 'Introduction to ISLE': 'installation/docker/docker-introduction.md' + - 'Prerequisites': 'installation/docker/docker-prereq.md' + - 'ISLE-DC': + - Installing: + - 'Installing a Development Server': 'installation/docker/isle-dc/docker-local.md' + - 'Installing a Staging/Production Server': 'installation/docker/isle-dc/docker-custom.md' + - Maintaining: + - 'Basic Usage': 'installation/docker/isle-dc/docker-basic-usage.md' + - 'Maintaining Drupal': 'installation/docker/isle-dc/docker-maintain-drupal.md' + - 'Maintaining ISLE': 'installation/docker/isle-dc/docker-maintain-isle.md' + - 'Available Commands': 'installation/docker/isle-dc/docker-available-commands.md' + - 'Available Configuration': 'installation/docker/isle-dc/docker-available-configuration.md' + - 'Troubleshooting' : 'installation/docker/isle-dc/docker-troubleshooting.md' + - 'ISLE Site Template': + - 'Introduction to Site Template': 'installation/docker/site-template/site-template.md' - 'Ansible Playbook': 'installation/playbook.md' - Manual Installation: - 'Introduction': 'installation/manual/introduction.md' From 3ddab804f2b57668c7845575ae1d82995766ef9d Mon Sep 17 00:00:00 2001 From: Rosie Le Faive Date: Wed, 29 May 2024 15:14:37 -0300 Subject: [PATCH 2/4] Redirects and update a link. --- docs/user-documentation/users.md | 2 +- mkdocs.yml | 12 ++++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/user-documentation/users.md b/docs/user-documentation/users.md index 1aaa87024..049166f5c 100644 --- a/docs/user-documentation/users.md +++ b/docs/user-documentation/users.md @@ -18,7 +18,7 @@ Additional user roles can be created and assigned customized permissions, as des ## Before you start - This How-To assumes a very basic familiarity with Drupal. -- This How-To is generally applicable for any Islandora site, but the examples given are taken from an Islandora demo using the (optional) **[Islandora Starter Site](https://github.com/Islandora/islandora-starter-site)** configuration. This configuration is deployed automatically if you build your Islandora site with the appropriate options, using the [Ansible Playbook](../installation/playbook.md), [ISLE with Docker-Compose](../installation/docker-introduction.md). +- This How-To is generally applicable for any Islandora site, but the examples given are taken from an Islandora demo using the (optional) **[Islandora Starter Site](https://github.com/Islandora/islandora-starter-site)** configuration. This configuration is deployed automatically if you build your Islandora site with the appropriate options, using the [Ansible Playbook](../installation/playbook.md), [ISLE with Docker-Compose](../installation/docker/docker-introduction.md). !!! islandora "Warning" If you are writing to Fedora, your username must not contain spaces. diff --git a/mkdocs.yml b/mkdocs.yml index 1e5b06535..27213aa33 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,6 +45,16 @@ plugins: 'contributing/docs_style_guide.md': 'contributing/docs-style-guide.md' 'contributing/readme_template.md': 'contributing/readme-template.md' 'installation/component_overview.md': 'installation/component-overview.md' + 'installation/docker-available-commands.md': 'installation/docker/isle-dc/docker-available-commands.md' + 'installation/docker-available-configuration.md': 'installation/docker/isle-dc/docker-available-configuration.md' + 'installation/docker-basic-usage.md': 'installation/docker/isle-dc/docker-basic-usage.md' + 'installation/docker-custom.md': 'installation/docker/isle-dc/docker-custom.md' + 'installation/docker-introduction.md': 'installation/docker/docker-introduction.md' + 'installation/docker-local.md': 'installation/docker/isle-dc/docker-local.md' + 'installation/docker-maintain-drupal.md': 'installation/docker/isle-dc/docker-maintain-drupal.md' + 'installation/docker-maintain-isle.md': 'installation/docker/isle-dc/docker-maintain-isle.md' + 'installation/docker-prereq.md': 'installation/docker/docker-prereq.md' + 'installation/docker-troubleshooting.md': 'installation/docker/isle-dc/docker-troubleshooting.md' 'installation/manual/configuring_drupal.md': 'installation/manual/configuring-drupal.md' 'installation/manual/installing_composer_drush_and_drupal.md': 'installation/manual/installing-composer-drush-and-drupal.md' 'installation/manual/installing_crayfish.md': 'installation/manual/installing-crayfish.md' @@ -54,6 +64,7 @@ plugins: 'installation/manual/installing_solr.md': 'installation/manual/installing-solr.md' 'installation/manual/installing_tomcat_and_cantaloupe.md': 'installation/manual/installing-tomcat-and-cantaloupe.md' 'installation/manual/preparing_a_webserver.md': 'installation/manual/preparing-a-webserver.md' + 'installation/site-template.md': 'installation/docker/site-template/site-template.md' 'technical-documentation/adding_format_jsonld.md': 'technical-documentation/adding-format-jsonld.md' 'technical-documentation/alpaca_tips.md': 'technical-documentation/alpaca-tips.md' 'technical-documentation/resizing_vm.md': 'technical-documentation/resizing-vm.md' @@ -66,6 +77,7 @@ plugins: 'user-documentation/linked_data.md': 'user-documentation/linked-data.md' 'user-documentation/metadata_harvesting.md': 'user-documentation/metadata-harvesting.md' 'user-documentation/recipes/alexa_search.md': 'user-documentation/recipes/alexa-search.md' + extra: font: From 2722f791d6ac69ed88c5cac31c38993c7c0b01fe Mon Sep 17 00:00:00 2001 From: Josh d'Entremont Date: Tue, 4 Jun 2024 15:44:13 -0300 Subject: [PATCH 3/4] added instructions to convert from isle-dc to site template --- docs/installation/docker/converting.md | 87 ++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 88 insertions(+) create mode 100644 docs/installation/docker/converting.md diff --git a/docs/installation/docker/converting.md b/docs/installation/docker/converting.md new file mode 100644 index 000000000..deab35971 --- /dev/null +++ b/docs/installation/docker/converting.md @@ -0,0 +1,87 @@ +# Converting ISLE-DC to Site Template + +ISLE-DC is being deprecated in favour of using the Isle Site Template for Docker installs of Islandora. The following instructions explain how to convert your ISLE-DC site into the Site Template style of docker-compose.yml. + +## Development Instructions + +ISLE-DC and the Site Template both use [isle-builkit](https://github.com/Islandora-Devops/isle-buildkit) images to spin up an Islandora site. Since the images are the same, you can transfer an ISLE-DC site to a Site Template setup by doing the following: + +1. Follow the instructions in the [Site Template README](https://github.com/Islandora-Devops/isle-site-template) to create a new site from the Islandora Starter Site + + !!! note + Use the same TAG in your Site Template .env that you used in ISLE-DC, so you have the same set of containers. + +2. Replace the Starter Site's composer.json and composer.lock files with yours, and install the correct Drupal modules using Composer + + !!! note + You may need to make some modifications to your composer.json file. Specifically, the `scripts` and `drupal-scaffold` sections may have changed. + + You can look at the [most recent starter site composer.json](https://github.com/Islandora-Devops/islandora-starter-site/blob/main/composer.json) for comparison. + + If you have custom modules and/or themes that are not installed via Composer you will need to install those as well. + +3. Compare your old Dockerfile with [the one in the Site Template repository](https://github.com/Islandora-Devops/isle-site-template/blob/main/drupal/Dockerfile). If you have made customizations, you may want to replicate them in the new Dockerfile. + +4. Backup your ISLE-DC site's Fedora, Drupal database, and public/private files. + +5. Import your backups to the new Site Template site. + +6. Delete your Solr core, and regenerate new configs. + + !!! note + Site Template uses a different core name than ISLE-DC did + +7. Commit and push your git repository so it is ready for production. + + +## Production Instructions + +Once you have converted the development instance of your site, moving it to production requires the following: + +1. Clone the git repository that you set up in the development instructions above + +2. Prepare your images/containers as described in the Site Template README + + 1. Run the generate secrets script included with the site template, or copy your secrets from your existing site if you want them to be the same + 2. Add custom modules or themes, if you have some that are not included in your composer.json + 3. Build your Drupal container with `docker compose --profile prod build` + 4. Pull in the remaining containers with `docker compose --profile prod pull --ignore-buildable --ignore-pull-failures` + 5. Start the containers with `docker compose --profile prod up -d` + +3. Import the backups from your ISLE-DC site that you made in the development instructions above + +4. Delete your Solr core, and regenerate new configs. + +## Converting Your docker-compose.yml + +The main difference between ISLE-DC and the Site Template is the way the docker-compose.yml file is generated. In ISLE-DC we generate it based on your .env variables and a make command, but in Site Template it is ready to go out of the box. + +This means that in ISLE-DC you had separate docker-compose.yml files for development and production, but in site template there is one file for both, which contains instructions for a “dev” and “prod” profile. The end result is the same set of containers, but instead of running `docker compose up` you would run `docker compose --profile dev up` + +### Environment Variables + +You should compare the `environment` sections of your docker-compose.yml files. You may have some variables set in your ISLE-DC docker-compose.yml that will need to be added to the docker-compose.yml in the new Site Template site. + +For example, the [ISLE Buildkit Nginx README](https://github.com/Islandora-Devops/isle-buildkit/blob/main/nginx/README.md) lists the available variables for Nginx that you may have changed on your Drupal containers to do things like increase the timeout time for PHP or the max POST size PHP will accept. + +### URLs + +The Site Template also handles the URLs for microservices differently. You will need to follow the instructions in the Site Template README to allow access to your microservices as a subdomain. For example, `solr.mydomain.com`. + +!!! Note "Subdomains" + If you are already using a subdomain and can’t use URLs like `solr.mysubdomain.mydomain.com`, you can change this in the Traefik section of the docker-compose.yml file, by changing the aliases from `solr.{DOMAIN}` to something else, like `solr-{DOMAIN}`. You will also need to change this in a few other spots in your docker-compose.yml. You can find them by searching for `.{DOMAIN}` + +## Converting the Makefile + +Because ISLE-DC and Site Template use the same containers, much of what is in an ISLE-DC Makefile will work within the site template environment. The main differences that need to be addressed are with the way new sites are built, and the name of the containers. + +Commands to build a site, like `make starter` and `make production` are not necessary with the Site Template, so they can be removed from your Makefile. + +Many of the other commands specify which containers to run commands in, for example `docker compose exec drupal`, but in the Site Template environment you need to specify -dev or -prod, so that would be changed to `docker compose exec drupal-dev` or `docker compose exec drupal-prod`. + +## Other Customizations + +If you have modified your ISLE-DC repository, those modifications will need to be evaluated on a case-by-case basis. This includes editing the Dockerfile and environment variables mentioned above, as well as any other customizations you may have made, such as to settings.php, robots.txt, nginx configs, etc. + + + diff --git a/mkdocs.yml b/mkdocs.yml index 5fdad150d..72294ddd0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -141,6 +141,7 @@ nav: - 'Introduction to Site Template': 'installation/docker/site-template/site-template.md' - 'Docker Modifications': 'installation/docker/site-template/docker-modifications.md' - 'Updating': 'installation/docker/site-template/updating.md' + - 'Converting ISLE-DC to Site Template': 'installation/docker/converting.md' - 'Ansible Playbook': 'installation/playbook.md' - Manual Installation: - 'Introduction': 'installation/manual/introduction.md' From 360d3134b4c11d1c3ded04caac246497c89313a1 Mon Sep 17 00:00:00 2001 From: joshdentremont Date: Mon, 26 Aug 2024 13:41:22 -0300 Subject: [PATCH 4/4] Update converting.md removed line about deprecating isle-dc --- docs/installation/docker/converting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation/docker/converting.md b/docs/installation/docker/converting.md index deab35971..5f8583766 100644 --- a/docs/installation/docker/converting.md +++ b/docs/installation/docker/converting.md @@ -1,6 +1,6 @@ # Converting ISLE-DC to Site Template -ISLE-DC is being deprecated in favour of using the Isle Site Template for Docker installs of Islandora. The following instructions explain how to convert your ISLE-DC site into the Site Template style of docker-compose.yml. +The following instructions explain how to convert your ISLE-DC site into the Site Template style of docker-compose.yml. ## Development Instructions