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/5] 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 82e995531ccbeb365c2aace32816d61500aea863 Mon Sep 17 00:00:00 2001 From: Josh d'Entremont Date: Wed, 22 May 2024 13:52:16 -0300 Subject: [PATCH 2/5] added page for running commands inside containers --- .../docker/site-template/containers.md | 41 +++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 42 insertions(+) create mode 100644 docs/installation/docker/site-template/containers.md diff --git a/docs/installation/docker/site-template/containers.md b/docs/installation/docker/site-template/containers.md new file mode 100644 index 000000000..8311fd488 --- /dev/null +++ b/docs/installation/docker/site-template/containers.md @@ -0,0 +1,41 @@ +# Working in Your Containers + +## Running Commands in the Containers + +Many of the following commands require running inside of your containers. You can get a bash shell inside the container by running + +`docker compose exec drupal-dev with-contenv bash` + +Or you can run a command from the host machine by running + +`docker compose exec -T drupal-dev with-contenv bash -lc 'YOUR COMMAND'` + +For example, if you want to run a drush cache rebuild you could run + +`docker compose exec -T drupal-dev with-contenv bash -lc 'drush cr'` + +!!! Note "Container Names" + The container name drupal-dev is the ‘services’ name as set in your docker-compose.yml. To access the drupal container in production you would replace drupal-dev with drupal-prod. + + You can also access other containers in this way, by replacing drupal-dev with their service name, like mariadb-dev. + +For more information see the documentation on [docker compose exec](https://docs.docker.com/reference/cli/docker/compose/exec/) + +### Container Variables + +In some of the commands throughout the ISLE Site Template documentation you will see references to variables like `${DRUPAL_DEFAULT_SITE_URL}`. These are variables that are provided in the containers by the s6-overlay in [Islandora Buildkit](https://github.com/Islandora-Devops/isle-buildkit). + +If you want to see their values you can run + +``` +docker compose exec -T drupal-dev with-contenv bash -lc 'echo ${DRUPAL_DEFAULT_SITE_URL}' +``` + +!!! Note "with-contenv" + Adding `with-contenv` to your commands gives you access to the s6-overlay environment variables. If you don’t need to use these variables, the commands above can be simplified to + + `docker compose exec drupal-dev bash` + + and + + `docker compose exec -T drupal-dev -lc 'YOUR COMMAND'` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 1e5b06535..932f4bd59 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -127,6 +127,7 @@ nav: - 'Troubleshooting' : 'installation/docker/isle-dc/docker-troubleshooting.md' - 'ISLE Site Template': - 'Introduction to Site Template': 'installation/docker/site-template/site-template.md' + - 'Working in Your Containers': 'installation/docker/site-template/containers.md' - 'Ansible Playbook': 'installation/playbook.md' - Manual Installation: - 'Introduction': 'installation/manual/introduction.md' From bb14bf445faf618686437c48999f16f7c00a5aca Mon Sep 17 00:00:00 2001 From: Josh d'Entremont Date: Wed, 22 May 2024 16:28:59 -0300 Subject: [PATCH 3/5] updated wording --- .../docker/site-template/containers.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/installation/docker/site-template/containers.md b/docs/installation/docker/site-template/containers.md index 8311fd488..8d9741a07 100644 --- a/docs/installation/docker/site-template/containers.md +++ b/docs/installation/docker/site-template/containers.md @@ -1,31 +1,33 @@ # Working in Your Containers +When using Docker, we often have to run commands inside the Docker containers. For example, you can run the same Drush commands you would run in a non-Docker environment, but you must run those commands inside the Drupal container. + ## Running Commands in the Containers -Many of the following commands require running inside of your containers. You can get a bash shell inside the container by running +If you want to work inside a container, you can use Docker Compose to run bash from inside the container. You can get a bash shell inside the Drupal container by running `docker compose exec drupal-dev with-contenv bash` -Or you can run a command from the host machine by running +Or you can run your command from the host machine by running `docker compose exec -T drupal-dev with-contenv bash -lc 'YOUR COMMAND'` -For example, if you want to run a drush cache rebuild you could run +For example, if you want to perform a Drush cache rebuild you could run `docker compose exec -T drupal-dev with-contenv bash -lc 'drush cr'` !!! Note "Container Names" The container name drupal-dev is the ‘services’ name as set in your docker-compose.yml. To access the drupal container in production you would replace drupal-dev with drupal-prod. - You can also access other containers in this way, by replacing drupal-dev with their service name, like mariadb-dev. + You can also access other containers in this way, by replacing drupal-dev with their service name. For example, mariadb-dev or solr-prod. -For more information see the documentation on [docker compose exec](https://docs.docker.com/reference/cli/docker/compose/exec/) +For more information, see the documentation on [docker compose exec](https://docs.docker.com/reference/cli/docker/compose/exec/) ### Container Variables In some of the commands throughout the ISLE Site Template documentation you will see references to variables like `${DRUPAL_DEFAULT_SITE_URL}`. These are variables that are provided in the containers by the s6-overlay in [Islandora Buildkit](https://github.com/Islandora-Devops/isle-buildkit). -If you want to see their values you can run +If you want to see their values, you can run ``` docker compose exec -T drupal-dev with-contenv bash -lc 'echo ${DRUPAL_DEFAULT_SITE_URL}' From 5673b54d832466216079f0c9cddf1762a31f5acc Mon Sep 17 00:00:00 2001 From: Josh d'Entremont Date: Mon, 3 Jun 2024 15:21:38 -0300 Subject: [PATCH 4/5] added helpful commands --- .../docker/site-template/containers.md | 79 ++++++++++++++++++- 1 file changed, 78 insertions(+), 1 deletion(-) diff --git a/docs/installation/docker/site-template/containers.md b/docs/installation/docker/site-template/containers.md index 8d9741a07..625aa6749 100644 --- a/docs/installation/docker/site-template/containers.md +++ b/docs/installation/docker/site-template/containers.md @@ -40,4 +40,81 @@ docker compose exec -T drupal-dev with-contenv bash -lc 'echo ${DRUPAL_DEFAULT_S and - `docker compose exec -T drupal-dev -lc 'YOUR COMMAND'` \ No newline at end of file + `docker compose exec -T drupal-dev -lc 'YOUR COMMAND'` + + +## Helpful Commands + +### Checking logs + +You can read logs for a container with: + +``` +docker-compose logs service_name +``` + +For example, to read nginx logs for Drupal, use `docker-compose logs drupal-dev`. + +If you don't know what you're looking for exactly, you can turn on the fire hose and look through all logs by dropping the service name and simply using: + +``` +docker-compose logs +``` + +### Reindex Solr + +You can reindex Solr through the Drupal admin page, or via drush commands by queuing for reindex: + +``` +docker compose exec -T drupal-dev with-contenv bash -lc 'drush --root /var/www/drupal/web -l ${DRUPAL_DEFAULT_SITE_URL} search-api-reindex' +``` + +then triggering the reindex: + +``` +docker compose exec -T drupal-dev with-contenv bash -lc 'drush --root /var/www/drupal/web -l ${DRUPAL_DEFAULT_SITE_URL} search-api-index' +``` + +### Reindex Fedora + +!!! note + This requires the [Views Bulk Operations module](https://www.drupal.org/project/views_bulk_operations) + + +You can reindex all of your Drupal data into Fedora, by running the following commands: + +``` +docker compose exec -T drupal-dev with-contenv bash -lc 'drush --root /var/www/drupal/web -l ${DRUPAL_DEFAULT_SITE_URL} vbo-exec non_fedora_files emit_file_event --configuration="queue=islandora-indexing-fcrepo-file-external&event=Update"' +``` + +``` +docker compose exec -T drupal-dev with-contenv bash -lc 'drush --root /var/www/drupal/web -l ${DRUPAL_DEFAULT_SITE_URL} vbo-exec all_taxonomy_terms emit_term_event --configuration="queue=islandora-indexing-fcrepo-content&event=Update"' +``` + +``` +docker compose exec -T drupal-dev with-contenv bash -lc 'drush --root /var/www/drupal/web -l ${DRUPAL_DEFAULT_SITE_URL} vbo-exec content emit_node_event --configuration="queue=islandora-indexing-fcrepo-content&event=Update"' +``` + +``` +docker compose exec -T drupal-dev with-contenv bash -lc 'drush --root /var/www/drupal/web -l ${DRUPAL_DEFAULT_SITE_URL} vbo-exec media emit_media_event --configuration="queue=islandora-indexing-fcrepo-media&event=Update"' +``` + +### Reindex Blazegraph + +!!! note + This requires the [Views Bulk Operations module](https://www.drupal.org/project/views_bulk_operations) + + +You can reindex all of your Drupal data into Blazegraph, by running the following commands: + +``` +docker compose exec -T drupal-dev with-contenv bash -lc 'drush --root /var/www/drupal/web -l ${DRUPAL_DEFAULT_SITE_URL} vbo-exec all_taxonomy_terms emit_term_event --configuration="queue=islandora-indexing-triplestore-index&event=Update"' +``` + +``` +docker compose exec -T drupal-dev with-contenv bash -lc 'drush --root /var/www/drupal/web -l ${DRUPAL_DEFAULT_SITE_URL} vbo-exec content emit_node_event --configuration="queue=islandora-indexing-triplestore-index&event=Update"' +``` + +``` +docker compose exec -T drupal-dev with-contenv bash -lc 'drush --root /var/www/drupal/web -l ${DRUPAL_DEFAULT_SITE_URL} vbo-exec media emit_media_event --configuration="queue=islandora-indexing-triplestore-index&event=Update"' +``` From a9061785f8ffaed8e86ccba16de5dec933cdf0ae Mon Sep 17 00:00:00 2001 From: Josh d'Entremont Date: Tue, 4 Jun 2024 14:04:08 -0300 Subject: [PATCH 5/5] updated docker-compose to remove dash --- docs/installation/docker/site-template/containers.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/installation/docker/site-template/containers.md b/docs/installation/docker/site-template/containers.md index 625aa6749..b449dad69 100644 --- a/docs/installation/docker/site-template/containers.md +++ b/docs/installation/docker/site-template/containers.md @@ -50,15 +50,15 @@ docker compose exec -T drupal-dev with-contenv bash -lc 'echo ${DRUPAL_DEFAULT_S You can read logs for a container with: ``` -docker-compose logs service_name +docker compose logs service_name ``` -For example, to read nginx logs for Drupal, use `docker-compose logs drupal-dev`. +For example, to read nginx logs for Drupal, use `docker compose logs drupal-dev`. If you don't know what you're looking for exactly, you can turn on the fire hose and look through all logs by dropping the service name and simply using: ``` -docker-compose logs +docker compose logs ``` ### Reindex Solr