How to integrate Solr with DDEV and TYPO3 v10 for your local development

Many of our enterprise customers require high-performant search functionality on their websites. TYPO3 meets this challenge by easily integrating with Solr search, and we rely on dkd’s Solr extension to set up powerful search features. 

At b13, our developers practice continuous integration and continuous delivery (CI/CD) and test changes locally before any code is published to the production systems. To be able to implement changes, our local and production environments must have identical configurations—for Solr and other systems. As a result, developers who want to implement Solr in production without major obstacles will also need to implement it locally. 

This step-by-step guide will show you how to set up Solr locally, via Docker, in a matter of minutes.

Prerequisites

One of the tools we use in local development is DDEV, a powerful platform built around Docker and Docker-Compose for PHP projects. DDEV has great support for TYPO3. Before you begin, make sure you’ve already installed DDEV and dkd’s Solr extension in your existing TYPO3 project. This guide assumes you’re using Git version control and have updated to TYPO3 v10 LTS. As a short checklist, we’d expect your project to meet the following prerequisites: 

• TYPO3 v10 LTS is running with Composer, and your public web root is configured as “htdocs/” (where your fileadmin folder resides).
• Solr Extension v11.0.x is installed.
• Connected Solr server 8.11.1 is already configured in TYPO3’s site configuration (see the Solr extension’s version matrix for more information)
• A distinct Solr Core is set up for each language on your website, all using the TYPO3-Solr config set “ext_solr_11_1_0”. (For example, a website with four languages would have four Solr Cores: “corporate_en”, “corporate_de”, “corporate_it” and “corporate_cn”.)
• DDEV is already running and configured in .ddev of your project root

Step 1: Set up Solr as a DDEV container

DDEV already ships with basic support for Solr, and you can use any docker-compose file to set up additional Docker containers quickly. (It’s brilliant!)

In your existing project, create a new file named .ddev/docker-compose.solr.yaml with the following contents:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

version: '3.6'

services:
 solr:
   container_name: ddev-${DDEV_SITENAME}-solr
   image: solr:8.11.1
   restart: "no"
   expose:
     - 8983
     - 8984
   labels:
     com.ddev.site-name: ${DDEV_SITENAME}
     com.ddev.approot: $DDEV_APPROOT
   environment:
     - VIRTUAL_HOST=$DDEV_HOSTNAME
     - HTTP_EXPOSE=8983
     - HTTPS_EXPOSE=8984:8983
   volumes:
     - ./solr:/var/solr/data
 web:
   links:
     - solr

Note the following three items: 

1. The name of the docker image is “solr:8.11.1”. We use the official “solr” image with the tag “8.11.1” since it’s running in production, and we want to stick as close to the production system as possible. See https://hub.docker.com/_/solr?tab=tags for available versions of this image. Solr 8.11.1 is also safe from any Log4J vulnerabilities.
2. The container_name is ddev-${DDEV_SITENAME}-solr and we’ll later use it to connect to the Solr service in TYPO3.
3. The exposed ports for HTTP and HTTPS, which we use the default ones solr uses. 8983 for the non-encrypted HTTP port and 8984 for the encrypted HTTPS port.

Step 2: Configure your Solr cores

Configure the Solr cores in DDEVs main .ddev/config.yaml file. Add the following lines at the end of the file, adjusting for your language settings:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

environment:
 - SOLR_HOST=${DDEV_SITENAME}.ddev.site
typo3_solr_cores:
 - { name: corporate_en, schema: "english/schema.xml" }
 - { name: corporate_de, schema: "german/schema.xml" }
 - { name: corporate_zh, schema: "chinese/schema.xml" }
 - { name: corporate_it, schema: "italian/schema.xml" }
typo3_solr_ext_path: 'htdocs/typo3conf/ext/solr/Resources/Private/Solr/'
typo3_solr_configset: 'ext_solr_11_0_0'
hooks:
 post-start:
   - exec-host: "composer install --no-scripts"
   - exec: |
       SOLR_EXT_PATH=(`yq e '.typo3_solr_ext_path' .ddev/config.yaml`)
       cp -r ${SOLR_EXT_PATH}solr.xml .ddev/solr/
       cp -r ${SOLR_EXT_PATH}configsets .ddev/solr/

       CONFIGSET=(`yq e '.typo3_solr_configset' .ddev/config.yaml`)
       NAME=(`yq e '.typo3_solr_cores.[].name' .ddev/config.yaml`)
       SCHEMA=(`yq e '.typo3_solr_cores.[].schema' .ddev/config.yaml`)

       length=${#NAME[@]}
       for (( i = 0; i < length; i++ )); do
         curl -s -o /dev/null "http://solr:8983/solr/admin/cores?action=CREATE&name=${NAME[$i]}&configSet=${CONFIGSET}&schema=${SCHEMA[$i]}&dataDir=data/"
       done

This step implements the main logic for the TYPO3 integration. Again, three points are key: 

• Define the cores you want to create (typo3_solr_ext_cores), the path to the Solr extension’s asset folder (typo3_solr_ext_path), which already ships the configsets, and the solr configuration, which is ready-to-use for TYPO3.
• The post-start hook copies over the configuration from the extension and creates the cores via a curl request to the solr host, if they don’t exist yet. The hook uses a composer install to ensure that the solr extension has been installed at that time.
• The additional environment variable for the main web container SOLR_HOST is used later on in TYPO3 to reference the internal Docker service directly in TYPO3’s site configuration.

If you’re using git, now is the time to edit the .ddev/.gitignore file and ensure that the created solr core data and configsets are not committed. To add .gitignore to your Git repository and exclude the .ddev/solr/ folder and its contents from versioning control, you need to remove the first three lines in .ddev/.gitignore and add /solr/ to the very end of the file. 

Run ddev restart and—voila—your Solr cores are created automatically.

Step 3: Connect your Solr cores in TYPO3

In our example, we assume you work with environment variables in your production environment (see https://12factor.net/config for more details). We use the same Solr host for read and write, and we use the SOLR_HOST environment variable in production. Assuming your setup is similar, follow TYPO3 Solr’s documentation and match the environment variable we named SOLR_HOST in your site configuration—either through the GUI or by editing the file config/sites/main/config.yaml.

As a final check, make sure to use environment variables in production and use the SOLR_HOST variable for production in your site configuration. In addition, match the names of your local Solr cores to those used in production. Once you’ve done so, your setup is done! You can index and test your Solr search locally in DDEV.

This is a quick excerpt of the example project’s site configuration file located in config/sites/main/config.yaml.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

-
 title: English
 languageId: 0
 base: /en/
 typo3Language: default
 ...
 solr_core_read: corporate_en
-
 title: Deutsch
 languageId: 1
 base: /
 typo3Language: de
 ...
 solr_core_read: corporate_de
solr_enabled_read: true
solr_host_read: '%env(SOLR_HOST)'
solr_path_read: /solr/
solr_port_read: '8983'
solr_scheme_read: http

Last but not least: Commit and push your code, so your team members can enjoy the setup you’ve created for the project.

We hope this will save you and your team members time!