diff --git a/search-services/README.md b/search-services/README.md index f5caddb21..be8bbdd29 100644 --- a/search-services/README.md +++ b/search-services/README.md @@ -7,49 +7,168 @@ Alfresco Search Services using Alfresco and Apache Solr Git: ```bash -git clone https://github.com/Alfresco/SearchServices.git +$ git clone https://github.com/Alfresco/SearchServices.git ``` ### Use Maven -Build project: + +Build the project: ```bash -mvn clean install +$ mvn clean install -DskipTests=true ``` -All the resources needed for the docker image will be available under packaging/target/docker-resources/ +All the resources required to run Alfresco Search Services will be available under `packaging/target` folder. ### Start Alfresco Search Services from source -To run Alfresco Search Services locally first build the zip file using: + +To run Alfresco Search Services locally, building the ZIP distribution file is required. ```bash -mvn clean install +$ mvn clean install -DskipTests=true ``` -Extract the zip file and launch Alfresco Search Services using: +After the project is successfully built, ZIP can be extracted. ```bash -cd packaging/target -unzip alfresco-search-services-*.zip -cd alfresco-search-services/solr -./bin/solr start -Dcreate.alfresco.defaults=alfresco,archive +$ cd packaging/target +$ unzip alfresco-search-services-*.zip +$ cd alfresco-search-services ``` -If you also start an ACS instance then index will be populated. By default Alfresco Search Services runs on port 8983, but this can be set by supplying e.g. `-p 8083` to the "solr start" command. +From Alfresco *Search Services 1.3.0.3*, distribution ZIP is released with Mutual Auth TLS (SSL) by default. So before starting the service, generating secure keys for SSL communication is required. You can find detailed information for this step at [Alfresco documentation](https://docs.alfresco.com/search-enterprise/tasks/generate-keys-ssl.html). + +The `keystores` folder generated by the SSL Tool contains the keystores and truststores for SSL configuration. In the following steps, it's assumed that SSL Tool has been executed from `/tmp` or `C:\tmp` folder. + +```bash +$ tree /tmp/keystores/ +keystores/ +├── alfresco +│   ├── keystore +│   ├── keystore-passwords.properties +│   ├── ssl-keystore-passwords.properties +│   ├── ssl-truststore-passwords.properties +│   ├── ssl.keystore +│   └── ssl.truststore +├── client +│   └── browser.p12 +├── solr +│   ├── ssl-keystore-passwords.properties +│   ├── ssl-truststore-passwords.properties +│   ├── ssl.repo.client.keystore +│   └── ssl.repo.client.truststore +└── zeppelin + ├── ssl.repo.client.keystore + └── ssl.repo.client.truststore +``` + +SOLR SSL configuration files are available in `/tmp/keystores/solr` folder. + +These files must be copied to `rerank` configuration folder. + +``` +$ cp /tmp/keystores/solr/* solrhome/templates/rerank/conf +``` + + +If you are running from a *Linux* or *Mac OS X* machine, add following lines to `solr.in.sh` file. + +``` +SOLR_SSL_KEY_STORE=/tmp/keystores/solr/ssl.repo.client.keystore +SOLR_SSL_KEY_STORE_PASSWORD=keystore +SOLR_SSL_KEY_STORE_TYPE=JCEKS +SOLR_SSL_TRUST_STORE=/tmp/keystores/solr/ssl.repo.client.truststore +SOLR_SSL_TRUST_STORE_PASSWORD=truststore +SOLR_SSL_TRUST_STORE_TYPE=JCEKS +SOLR_SSL_NEED_CLIENT_AUTH=true +SOLR_SSL_WANT_CLIENT_AUTH=false +``` + +If you are running from a *Windows* machine, add following lines to `solr.in.cmd` file. + +``` +set SOLR_SSL_KEY_STORE=C:\tmp\keystores\solr\ssl.repo.client.keystore +SOLR_SSL_KEY_STORE_PASSWORD=keystore +SOLR_SSL_KEY_STORE_TYPE=JCEKS +SOLR_SSL_TRUST_STORE=C:\tmp\keystores\solr\ssl.repo.client.truststore +SOLR_SSL_TRUST_STORE_PASSWORD=truststore +SOLR_SSL_TRUST_STORE_TYPE=JCEKS +SOLR_SSL_NEED_CLIENT_AUTH=true +SOLR_SSL_WANT_CLIENT_AUTH=false +``` + +Once this settings are ready, start SOLR service from command line: + +``` +$ ./solr/bin/solr start "-Dcreate.alfresco.defaults=alfresco,archive \ +-Dsolr.ssl.checkPeerName=false \ +-Dsolr.allow.unsafe.resourceloading=true" -f +``` + +SOLR will create Alfresco cores (`alfresco` and `archive`) when starting, and configuration from `rerank` template will be copied to each core and if you also started an ACS instance running in [https://localhost:8443/alfresco](https://localhost:8443/alfresco) then the index will be populated. + +SOLR Web Console will be available at: + +[https://localhost:8983/solr](https://localhost:8983/solr) + +**Note** Client certificate `browser.p12`, generated by the SSL Tool, is required to be installed in your browser in order to access to this Web Console. + +By default Alfresco Search Services runs on port 8983, but this can be set by supplying e.g. `-p 8083` to the "solr start" command. To set up remote debugging (on port 5005) start Alfresco Search Services with the following command and then connect using your IDE: ```bash -./bin/solr start -a "-Dcreate.alfresco.defaults=alfresco,archive -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005" +$ ./solr/bin/solr start -a "-Dcreate.alfresco.defaults=alfresco,archive \ +-Dsolr.ssl.checkPeerName=false \ +-Dsolr.allow.unsafe.resourceloading=true \ +-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005" -f ``` To stop Alfresco Search Services: ```bash -./bin/solr stop +$ ./solr/bin/solr stop ``` -### Docker +**Using Plain HTTP** + +If you want to use Plain HTTP for SOLR instead of Mutual Auth TLS (SSL), use following steps. + +```bash +$ mvn clean install -DskipTests=true +``` + +After the project is successfully built, ZIP can be extracted. + +```bash +$ cd packaging/target +$ unzip alfresco-search-services-*.zip +$ cd alfresco-search-services +``` + +Change default Alfresco Communication protocol to `none`. + +```bash +$ sed -i 's/alfresco.secureComms=https/alfresco.secureComms=none/' solrhome/templates/rerank/conf/solrcore.properties +``` + +*Note* Above line is written in GNU sed, you can use `gsed` from Mac OS X or just edit the file with a Text Editor. + +Start SOLR service from command line: + +``` +$ ./solr/bin/solr start "-Dcreate.alfresco.defaults=alfresco,archive" -f +``` + +SOLR will create Alfresco cores (`alfresco` and `archive`) when starting, and configuration from `rerank` template will be copied to each core and if you also started an ACS instance running in [http://localhost:8080/alfresco](http://localhost:8080/alfresco) then the index will be populated. + +SOLR Web Console will be available at: + +[http://localhost:8983/solr](http://localhost:8983/solr) + + +### Use Alfresco Search Services Docker Image + To build the docker image: ```bash