SOLR: Improve docs and docker-compose.solr.yaml

cmd/ddev/cmd/ssh.go

@@ -39,7 +39,7 @@ var DdevSSHCmd = &cobra.Command{
 		// Use bash for our containers, sh for 3rd-party containers
 		// that may not have bash.
 		shell := "bash"
-		if !nodeps.ArrayContainsString([]string{"web", "db", "dba"}, serviceType) {
+		if !nodeps.ArrayContainsString([]string{"web", "db", "dba", "solr"}, serviceType) {
 			shell = "sh"
 		}
 		_ = app.ExecWithTty(&ddevapp.ExecOpts{

docs/users/extend/additional-services.md

@@ -5,37 +5,48 @@ ddev projects can be extended to provide additional services. This is achieved b
 If you need a service not provided here, see [Defining an additional service with Docker Compose](custom-compose-files.md)
 
 ## Apache Solr
-This recipe adds an Apache Solr container to a project. It will set up a solr core with the solr configuration you define.
+This recipe adds an Apache Solr container to a project. It will set up a solr core named "dev" with the solr configuration you define.
 
 **Installation:**
 
 - Copy [docker-compose.solr.yaml](https://github.com/drud/ddev/tree/master/pkg/servicetest/testdata/services/docker-compose.solr.yaml) to the .ddev folder for your project.
-- You can change the Solr version by changing the `image` value in docker-compose.solr.yaml, for example: `image: solr:6.6`. The most obvious official solr image tags are at [hub.docker.com](https://hub.docker.com/_/solr/).
+- The recommended Solr version is: `image: solr:8`, from [hub.docker.com](https://hub.docker.com/_/solr/).
 - Create the folder path .ddev/solr/conf.
-- Copy the Solr configuration files for your project to `.ddev/solr/conf`. e.g. if using [Drupal Search API Solr](https://www.drupal.org/project/search_api_solr), you would copy the `web/modules/contrib/search_api_solr/solr-conf-templates/6.x/ `contents from the module code base into `.ddev/solr/conf`.
+- Copy/extract the Solr configuration files for your project into `.ddev/solr/conf`. 
 - Ensure that the configuration files are present before running `ddev start`.
-- Add the following post-start hook to your config.yaml; this turns on ping for the "dev" core. The curl command can also be done as a one-time configuration from within the web container.
-```
-hooks:
-  post-start:
-  - exec: curl --fail -s 'http://solr:8983/solr/dev/admin/ping?action=enable'
-```
 
 **Drupal8-specific extra steps:** 
-- Enable the Search API Solr Search Defaults module and edit the server settings at `/admin/config/search/search-api/server/default_solr_server/edit`.
-- Change the "Solr core" field from the default "d8" to "dev" and under **Advanced Server Configuration** change the _solr.install.dir_ setting to `/opt/solr`.
-- Go to the view tab and download the updated config.zip file.
-- Stop the project with `ddev stop`.
-- Remove the original configuration files from `.ddev/solr/conf` and copy in the updated files extracted from config.zip.
-- In order for changes to take effect you must remove the Solr volume by running `docker volume rm ddev-PROJECT-NAME_solrdata` e.g. if your project is called "myproject" then you would run `docker volume rm ddev-myproject_solrdata`.
-- Now you can start the project `ddev start`.
-
-**Updating Apache Solr configuration**
-
-- Run `ddev stop` to remove your application's containers (note: if you do not use the [destructive option](cli-usage#removing-projects-from-your-collection-known-to-ddev), the index will be untouched).
-- copy the new solr configuration files for your project to .ddev/solr/conf as described in **Installation**, above.
-- Run `ddev start` to rebuild and restart the containers.
-- An excellent way to automate the updating of the solr config uses a [solr-init.sh](https://github.com/drud/ddev/pull/1645#issuecomment-503722974) script mounted into the solr container's `/docker-entrypoint-initdb.d/solr-init.sh`.
+- `ddev start`
+- Enable the Search API Solr Search Defaults module 
+- Add a solr server at `https://<projectname>>.ddev.site/en/admin/config/search/search-api/add-server`.
+  - Use the "standard" Solr connector
+  - Use the "http" protocol
+  - The "solr host" should be "solr" **NOT the default "localhost"**
+  - The "solr core" should be named "dev" unless you customize the docker-compose.solr.yaml
+  - Under "Advanced server configuration" set the "solr.install.dir" to `/opt/solr`
+- Download the config.zip provided on /admin/config/search/search-api/server/dev
+- Unzip the config.zip into .ddev/solr/conf. For example, `cd .ddev/solr/conf && unzip ~/Downloads/solr_8.x-config.zip`
+- In order for changes to take effect you must stop the project, remove the Solr volume, and start it again.  So run `docker volume rm ddev-<projectname>_solrdata` if your project is called "myproject" then you would run `ddev stop && docker volume rm ddev-myproject_solrdata && ddev restart`. (If you have installed solr-configupdate.sh as described below, then you need only `ddev restart`)
+
+**Updating Apache Solr configuration on an existing Solr core**
+
+The default [solr-precreate script](https://github.com/docker-solr/docker-solr/blob/master/scripts/solr-precreate) provided in [docker-solr](https://github.com/docker-solr/docker-solr) and used in the `entrypoint` in docker-compose.solr.yaml does not have the capability to update core configuration after the core has been created. It just copies mounted config into the core, where it would otherwise live forever. However, a simple optional script executed on startup can re-copy config into place. Here's the technique:
+
+- Provide a config update script to the container. Call it solr-configupdate.sh and put it in .ddev/solr/solr-configupdate.sh, with these contents:
+    ```
+    #!/usr/bin/env bash
+    set -e
+
+    # Ensure "dev" core config is always up to date even after the 
+    # core has been created. This does not execute the first time,
+    # when solr-precreate has not yet run.
+    CORENAME=dev
+    if [ -d /var/solr/data/${CORENAME}/conf ]; then
+        cp /solr-conf/conf/* /var/solr/data/${CORENAME}/conf
+    fi  
+    ```
+- Make sure solr-configupdate.sh is executable: `chmod +x .ddev/solr/configupdate.sh`
+- Now you can copy/edit/update the solr configuration files for your project in .ddev/solr/conf and when you `ddev restart` the solr configuration will be live.
 
 **Interacting with Apache Solr**
 

pkg/servicetest/testdata/services/docker-compose.solr.yaml

@@ -4,36 +4,34 @@
 # 1. Copy this file to your project's ".ddev" directory.
 # 2. Create the folder path ".ddev/solr/conf".
 # 3. Copy the Solr configuration files for the appropriate plugin/module to
-#    ".ddev/solr/conf". For example, using Drupal 7's Search API Solr module,
-#    copy the files from its "solr-conf/6.x" directory into ".ddev/solr/conf"
+#    ".ddev/solr/conf". For example, using Drupal 8's Search API Solr module,
+#    you'll get the config files as a file config.zip from
+#    /admin/config/search/search-api/server/solr and unzip it into .ddev/solr/conf
 #    so that a file exists with the path ".ddev/solr/conf/solrconfig.xml".
 #
-# Notes:
-# - The configuration files must be present before running "ddev start".
-# - Changes to the configuration files will not be automatically applied.
-#
 # To access Solr after it is installed:
 # - The Solr admin interface will be accessible at:
 #   http://<projectname>.ddev.site:8983/solr/
 #   For example, if the project is named "myproject" the hostname will be:
 #   http://myproject.ddev.site:8983/solr/
 # - To access the Solr container from the web container use:
 #   http://solr:8983/solr/
-# - A Solr core is automatically created with the name "dev", i.e. it can be
-#   accessed at the URL: http://solr:8983/solr/dev
-
+# - A Solr core is automatically created with the name "dev" unless you
+#   change that usage throughout. It can be
+#   accessed at the URL: http://solr:8983/solr/dev (inside web container)
+#   or at http://myproject.ddev.site:8983/solr/dev (on the host)
 
 version: '3.6'
 
 services:
-  # This is the service name used when running ddev commands accepting the
-  # --service flag.
   solr:
-    # This is the name of the container. It is recommended to follow the same
-    # name convention used in the main docker-compose.yml file.
+    # Name of container using standard ddev convention
     container_name: ddev-${DDEV_SITENAME}-solr
-    # Controls the version of Solr which is installed.
-    image: solr:6.6
+    # The solr docker image is at https://hub.docker.com/_/solr/
+    # and code at https://github.com/docker-solr/docker-solr
+    # README: https://github.com/docker-solr/docker-solr/blob/master/README.md
+    # It's almost impossible to work with it if you don't read the docs there
+    image: solr:8
     restart: "no"
     # Solr is served from this port inside the container.
     ports:
@@ -50,23 +48,37 @@ services:
       # sitename.ddev.site.
       - HTTP_EXPOSE=8983
     volumes:
-      # This exposes a mount to the host system `.ddev/solr-conf` directory.
-      - "./solr:/solr-conf" 
-      # solr cores are stored on the 'solrdata' volume
-      - solrdata:/opt/solr/server/solr/mycores
+      # solr core *data* is stored on the 'solrdata' docker volume
+      # This mount is optional; without it your search index disappears
+      # each time ddev project is stopped and started.
+      - solrdata:/var/solr
+
+      # This mounts the conf in .ddev/solr into the container where
+      # the solr-precreate command in the entrypoint uses it as a one-time
+      # configuration to copy config into the newly-created core. It is not
+      # used if the core has previously been created.
+      - ./solr:/solr-conf
+
       - ".:/mnt/ddev_config"
-    entrypoint:
-      - docker-entrypoint.sh
-      - solr-precreate
-      - dev
-      - /solr-conf
+
+      # solr-configupdate.sh copies fresh configuration files into the
+      # solr container on each
+      # startup, so if you change the config in .ddev/solr/conf
+      # it will be refreshed on `ddev start`. The file must be
+      # executable (`chmod +x .ddev/solr/solr-init.sh
+      - "./solr/solr-configupdate.sh:/docker-entrypoint-initdb.d/solr-configupdate.sh"
+
+    entrypoint: [ "sh", "-c", "docker-entrypoint.sh solr-precreate dev /solr-conf" ]
+
+    external_links:
+      - "ddev-router:${DDEV_SITENAME}.ddev.site"
+
   # This links the Solr service to the web service defined in the main
-  # docker-compose.yml, allowing applications running in the web service to
-  # access the Solr service at sitename.ddev.site:8983.
+  # docker-compose.yml, allowing applications running inside the web container to
+  # access the Solr service at http://solr:8983
   web:
     links:
       - solr:solr
 volumes:
-  # This creates a Docker volume that sticks around even if you remove or
-  # rebuild the container
-  solrdata: 
+  # solrdata is a persistent Docker volume for solr data
+  solrdata: