Wiki source code of Run XWiki with an External Solr Container
Last modified by Vincent Massol on 2026/07/27 15:33
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | This page adds a Solr container to an XWiki installation, so that XWiki uses it instead of the Solr instance embedded in XWiki. See [[External Solr for XWiki in Docker>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.run-xwiki-external-solr.external-solr.WebHome]] for what a remote Solr requires and how the image configures it. {{version since="17.10.11, 18.4.3, 18.6.0"}}This procedure configures the remote Solr through the ##SOLR_BASE_URL## environment variable, which earlier images do not have.{{/version}} The examples use MySQL, but the Solr part is identical with MariaDB and with PostgreSQL. | ||
| 2 | |||
| 3 | == Using Docker Run == | ||
| 4 | |||
| 5 | 1. Create a dedicated [[Docker network>>https://docs.docker.com/engine/network/]] and start your database container, as described in [[Run XWiki (MySQL on Tomcat) Using Docker Run>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.docker-run.run-xwiki-mysql-tomcat.WebHome]]. | ||
| 6 | 1. Download the {{scm project="xwiki-docker" path="contrib/solr"}}##contrib/solr## directory{{/scm}} of the ##xwiki-docker## repository, which holds the ##Dockerfile## and the ##solr-init.sh## script. | ||
| 7 | 1. Build the Solr image, passing the version of XWiki you run so that the matching cores are downloaded.((( | ||
| 8 | {{code language="bash"}} | ||
| 9 | docker build -t xwiki-solr --build-arg XWIKI_VERSION=18.5.0 /my/path/contrib/solr | ||
| 10 | {{/code}} | ||
| 11 | ))) | ||
| 12 | 1. Create a local directory for the Solr index and give it to the Solr user and group of the image.((( | ||
| 13 | {{code language="bash"}} | ||
| 14 | mkdir -p /my/path/solr | ||
| 15 | chown 8983:8983 /my/path/solr | ||
| 16 | {{/code}} | ||
| 17 | ))) | ||
| 18 | 1. Start the Solr container.((( | ||
| 19 | {{code language="bash"}} | ||
| 20 | docker run --net=xwiki-nw --name solr-xwiki \ | ||
| 21 | -v /my/path/solr:/var/solr \ | ||
| 22 | -d xwiki-solr | ||
| 23 | {{/code}} | ||
| 24 | ))) | ||
| 25 | 1. Create a local directory for the XWiki permanent directory.((( | ||
| 26 | {{code language="bash"}} | ||
| 27 | mkdir -p /my/path/xwiki | ||
| 28 | {{/code}} | ||
| 29 | ))) | ||
| 30 | 1. Start the XWiki container, adding the ##SOLR_BASE_URL## environment variable that points to the Solr container.((( | ||
| 31 | {{code language="bash"}} | ||
| 32 | docker run --init --net=xwiki-nw --name xwiki -p 8080:8080 \ | ||
| 33 | -v /my/path/xwiki:/usr/local/xwiki \ | ||
| 34 | -e DB_USER=xwiki \ | ||
| 35 | -e DB_PASSWORD=xwiki \ | ||
| 36 | -e DB_DATABASE=xwiki \ | ||
| 37 | -e DB_HOST=mysql-xwiki \ | ||
| 38 | -e SOLR_BASE_URL=http://solr-xwiki:8983/solr \ | ||
| 39 | xwiki:stable-mysql-tomcat | ||
| 40 | {{/code}} | ||
| 41 | ))) | ||
| 42 | 1. Open XWiki in your browser at {{code language="none"}}http://localhost:8080{{/code}}. | ||
| 43 | 1. Follow the [[Distribution Wizard>>doc:Documentation.UserGuide.Features.DistributionWizard]] to finish the installation. | ||
| 44 | |||
| 45 | Don't forget to replace ##xwiki-nw## with the name of your Docker network, the ##/my/path/...## directories and the values of the [[environment variables>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.configuration.environment-variables.WebHome]] with your own, and ##18.5.0## with the XWiki version behind the ##xwiki:stable-mysql-tomcat## tag you use. | ||
| 46 | |||
| 47 | == Using Docker Compose == | ||
| 48 | |||
| 49 | 1. Set up the working directory and the configuration files for your database, as described in [[Run XWiki (MySQL on Tomcat) Using Docker Compose>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.docker-compose.run-xwiki-mysql-tomcat.WebHome]]. | ||
| 50 | 1. Copy the {{scm project="xwiki-docker" path="contrib/solr"}}##contrib/solr## directory{{/scm}} of the ##xwiki-docker## repository next to ##docker-compose.yml##, under the name ##solr##. | ||
| 51 | 1. Add an ##index## service to ##docker-compose.yml##, which builds that directory.((( | ||
| 52 | {{code language="yaml"}} | ||
| 53 | index: | ||
| 54 | build: | ||
| 55 | context: ./solr | ||
| 56 | args: | ||
| 57 | XWIKI_VERSION: ${XWIKI_VERSION} | ||
| 58 | container_name: xwiki-solr | ||
| 59 | volumes: | ||
| 60 | - solr-data:/var/solr | ||
| 61 | networks: | ||
| 62 | - bridge | ||
| 63 | {{/code}} | ||
| 64 | ))) | ||
| 65 | 1. Add ##index## to the ##depends_on## list of the ##web## service, and the base URL of the Solr container to its ##environment## list.((( | ||
| 66 | {{code language="yaml"}} | ||
| 67 | - SOLR_BASE_URL=http://xwiki-solr:8983/solr | ||
| 68 | {{/code}} | ||
| 69 | ))) | ||
| 70 | 1. Declare the ##solr-data## volume next to the volumes already listed at the end of the file.((( | ||
| 71 | {{code language="yaml"}} | ||
| 72 | solr-data: {} | ||
| 73 | {{/code}} | ||
| 74 | ))) | ||
| 75 | 1. Start the containers with ##docker compose up -d##. | ||
| 76 | |||
| 77 | The ##XWIKI_VERSION## build argument reuses the variable that the ##.env## file already defines for the XWiki image tag, so the Solr cores stay in sync with the version of XWiki that Docker Compose starts. |
