Apache Solr open-source search software
Clean up docker-faq.adoc (#2277)
Jan Høydahl9cdc81514197
diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/docker-faq.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/docker-faq.adocindex 2bb81b49465..e2eb09d1726 100644--- a/solr/solr-ref-guide/modules/deployment-guide/pages/docker-faq.adoc+++ b/solr/solr-ref-guide/modules/deployment-guide/pages/docker-faq.adoc@@ -18,141 +18,35 @@== How do I persist Solr data and config?-Your data is persisted already, in your container's filesystem.-If you `docker run`, add data to Solr, then `docker stop` and later `docker start`, then your data is still there.-The same is true for changes to configuration files.--Equally, if you `docker commit` your container, you can later create a new-container from that image, and that will have your data in it.--For some use-cases it is convenient to provide a modified `solr.in.sh` file to Solr.-For example to point Solr to a ZooKeeper host:--[source,bash]------docker create --name my_solr -P solr-docker cp my_solr:/opt/solr/bin/solr.in.sh .-sed -i -e 's/#ZK_HOST=.*/ZK_HOST=cylon.lan:2181/' solr.in.sh-docker cp solr.in.sh my_solr:/opt/solr/bin/solr.in.sh-docker start my_solr-# With a browser go to http://cylon.lan:32873/solr/#/ and confirm "-DzkHost=cylon.lan:2181" in the JVM Args section.-------But usually when people ask this question, what they are after is a way-to store Solr data and config in a separate https://docs.docker.com/userguide/dockervolumes/[Docker Volume].-That is explained in the next two questions.+Solr's Docker image is pre-configured with container path `/var/solr/` as a https://docs.docker.com/storage/volumes/[volume].+What this means is that all index data, log files and other variable data will be+persisted on the Docker host, even if you remove the container instance.== How can I mount a host directory as a data volume?-This is useful if you want to inspect or modify the data in the Docker host-when the container is not running, and later easily run new containers against that data.-This is indeed possible, but there are a few gotchas.--Solr stores its core data in the `server/solr` directory, in sub-directories for each core.-The `server/solr` directory also contains configuration files that are part of the Solr distribution.-Now, if we mounted volumes for each core individually, then that would interfere with Solr trying to create those directories.-If instead we make the whole directory a volume, then we need to provide those configuration files in our volume, which we can do by copying them from a temporary container.-For example:+By default Solr's volume is persisted in Docker's default storage location on the host.+On Linux systems this is `/var/lib/docker/volumes`. This is the recommended way to+store Solr's data. You have flexibility to use a bind mount host folder as well:[source,bash]-----# create a directory to store the server/solr directory-mkdir /home/docker-volumes/mysolr1--# make sure its host owner matches the container's solr user-sudo chown 8983:8983 /home/docker-volumes/mysolr1--# copy the solr directory from a temporary container to the volume-docker run -it --rm -v /home/docker-volumes/mysolr1:/target solr cp -r server/solr /target/--# pass the solr directory to a new container running solr-SOLR_CONTAINER=$(docker run -d -P -v /home/docker-volumes/mysolr1/solr:/opt/solr/server/solr solr)--# create a new core-docker exec -it --user=solr $SOLR_CONTAINER solr create -c gettingstarted--# check the volume on the host:-ls /home/docker-volumes/mysolr1/solr/-# configsets gettingstarted README.txt solr.xml zoo.cfg+docker run --rm -p 8983:8983 -v $(pwd)/myData:/var/solr/ solr:9-slim-----Note that if you add or modify files in that directory from the host, you must `chown 8983:8983` them.--== How can I use a Data Volume Container?--You can avoid the concerns about UID mismatches above, by using data volumes only from containers.-You can create a container with a volume, then point future containers at that same volume.-This can be handy if you want to modify the solr image, for example if you want to add a program.-By separating the data and the code, you can change the code and re-use the data.--But there are pitfalls:--* if you remove the container that owns the volume, then you lose your data.-Docker does not even warn you that a running container is dependent on it.-* if you point multiple solr containers at the same volume, you will have multiple instances-write to the same files, which will undoubtedly lead to corruption-* if you do want to remove that volume, you must do `docker rm -v containername`;-if you forget the `-v` there will be a dangling volume which you can not easily clean up.--Here is an example:--[source,bash]------# create a container with a volume on the path that solr uses to store data.-docker create -v /opt/solr/server/solr --name mysolr1data solr /bin/true--# pass the volume to a new container running solr-SOLR_CONTAINER=$(docker run -d -P --volumes-from=mysolr1data solr)--# create a new core-docker exec -it --user=solr $SOLR_CONTAINER solr create -c gettingstarted--# make a change to the config, using the config API-docker exec -it --user=solr $SOLR_CONTAINER curl http://localhost:8983/solr/gettingstarted/config -H 'Content-type:application/json' -d '{- "set-property" : {"query.filterCache.autowarmCount":1000},- "unset-property" :"query.filterCache.size"}'--# verify the change took effect-docker exec -it --user=solr $SOLR_CONTAINER curl http://localhost:8983/solr/gettingstarted/config/overlay?omitHeader=true--# stop the solr container-docker exec -it --user=solr $SOLR_CONTAINER bash -c 'cd server; java -DSTOP.PORT=7983 -DSTOP.KEY=solrrocks -jar start.jar --stop'--# create a new container-SOLR_CONTAINER=$(docker run -d -P --volumes-from=mysolr1data solr)--# check our core is still there:-docker exec -it --user=solr $SOLR_CONTAINER ls server/solr/gettingstarted--# check the config modification is still there:-docker exec -it --user=solr $SOLR_CONTAINER curl http://localhost:8983/solr/gettingstarted/config/overlay?omitHeader=true-----+But this is both dependent on the host operating system and may run into different kind+of file system permission issues.== Can I use volumes with SOLR_HOME?-Solr supports a SOLR_HOME environment variable to point to a non-standard location of the Solr home directory.-You can use this in Solr docker, in combination with volumes:--[source,bash]------docker run -it -v $PWD/mysolrhome:/mysolrhome -e SOLR_HOME=/mysolrhome solr-------This does need a pre-configured directory at that location.--To make this easier, Solr docker supports a INIT_SOLR_HOME setting, which copies the contents-from the default directory in the image to the SOLR_HOME (if it is empty).+While you could re-define `SOLR_HOME` inside the container, we instead recommend you+to use the existing `SOLR_HOME` defined at `/var/solr/`, see above. You can give the+volume a meaningful name instead of the auto generated hash, example name `solrData`:[source,bash]-----mkdir mysolrhome-sudo chown 8983:8983 mysolrhome-docker run -it -v $PWD/mysolrhome:/mysolrhome -e SOLR_HOME=/mysolrhome -e INIT_SOLR_HOME=yes solr+docker run --rm -p 8983:8983 -v solrData:/mysolrhome solr:9-slim-----NOTE: If SOLR_HOME is set, the "solr-precreate" command will put the created core in the SOLR_HOME directory-rather than the "mycores" directory.-== Can I run ZooKeeper and Solr clusters under Docker?At the network level the ZooKeeper nodes need to be able to talk to each other,@@ -180,47 +74,6 @@ It also has a `--ip-range` option that allows you to specify the range that otheUsed together, you can implement static addresses.See the xref:docker-networking.adoc[] for more information.-== Can I run ZooKeeper and Solr with Docker Links?--Docker's https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/[Legacy container links] provide a way to-pass connection configuration between containers.-It only works on a single machine, on the default bridge.-It provides no facilities for static IPs.-Note: this feature is expected to be deprecated and removed in a future release.-So really, see the "Can I run ZooKeeper and Solr clusters under Docker?" option above instead.--But for some use-cases, such as quick demos or one-shot automated testing, it can be convenient.--Run ZooKeeper, and define a name so we can link to it:--[source,bash]------docker run --name zookeeper -d -p 2181:2181 -p 2888:2888 -p 3888:3888 jplock/zookeeper-------Run two Solr nodes, linked to the zookeeper container:--[source,bash]------docker run --name solr1 --link zookeeper:ZK -d -p 8983:8983 \- solr \- bash -c 'solr start -f -z $ZK_PORT_2181_TCP_ADDR:$ZK_PORT_2181_TCP_PORT'--docker run --name solr2 --link zookeeper:ZK -d -p 8984:8983 \- solr \- bash -c 'solr start -f -z $ZK_PORT_2181_TCP_ADDR:$ZK_PORT_2181_TCP_PORT'-------Create a collection:--[source,bash]------docker exec -i -t solr1 solr create \- -c gettingstarted -shards 2 -p 8983-------Then go to `+http://localhost:8983/solr/#/~cloud+` (adjust the hostname for your docker host) to see the two shards and Solr nodes.-== How can I run ZooKeeper and Solr with Docker Compose?See the xref:solr-in-docker.adoc#docker-compose[docker compose example].