Solr-as-a-Service Quick Start - SearchStax

This page contains everything you need to know to take SearchStax®, the leading Solr-as-a-Service platform, for a test drive. We even supply the Solr configuration and sample documents for you to load. The instructions apply to both Linux and Windows.

Contents of this page:

  1. Set Up an Account
  2. Create a Solr Deployment
  3. Install the Zookeeper Script
  4. Upload a Solr Configuration
  5. Create a Collection
  6. Index Documents
  7. Search the Collection

Next Steps


1. Set Up an Account

To sign up as a SearchStax user, go to the SearchStax Free-Trial page. You may create a single-node deployment or a three-node cluster and experiment with it for 14 days, free of charge. No credit card number is required.

For detailed information concerning accounts, see the Account Setup page.

2. Create a Solr Deployment

Deployments are created from the SearchStax Dashboard. Navigate to the Cloud Manager and look for the Create Deployment button.

SearchStax Create New Deployment button

You will need to choose the appropriate Cloud Provider and the Plan that works for you. (The Free Trial program offers only two of the AWS deployments.)

SearchStax Create New Deployment

It usually takes five minutes to set up a single-node deployment, and up to fifteen minutes to set up a cluster, using AWS or GCP. Azure setup times range from twenty minutes to an hour. Feel free to explore our documentation and Help Center until the process is completed.

When the deployment is ready, view the deployment details by clicking the deployment's name:

SearchStax Deployment link

The details page shows the status of all deployment servers plus the URLs of the deployment's Solr HTTP Endpoint and Zookeeper Ensemble. You will need these URLs in subsequent steps on this page.

SearchStax Server Details

The API Termination Protection button shields this deployment from unintended deletion by someone using the SearchStax Provisioning API. It is a peace-of-mind feature that does not enter into the current exercise.

To learn more about Cloud Providers and Plans, see Plans.

3. Install the Zookeeper Script

Apache ZooKeeper is a service for maintaining configuration information. In a SearchStax Cloud deployment, Zookeeper is the central repository for your Solr configuration files.

A single-node deployment (DN1) has only one Zookeeper instance. A cluster (NDC4) has three Zookeeper instances, collectively called "the ensemble."

Zookeeper includes a standard command-line script, zkcli.sh, for managing your Zookeeper ensemble. Solr provides a modified version of zkcli that includes Solr-specific features. We have further modified the Solr zkcli by adding some data for this QuickStart exercise. We provide both Linux and Windows versions of the script.

Note: Sample Data Included

The zkcli script's ZIP file includes a small amount of sample data so you can deploy a Solr configuration right away.

You can download the SearchStax zkcli ZIP file here: searchstax-client-master.zip.

Unzip the file. The top-level directory is \searchstax-client-master. There are subdirectories for different versions of Solr. The directory structure under Solr-6 is slightly different from that under Solr-7. We assume that you are using Solr-7 in this exercise, with Solr-6 differences noted below.

Navigate to the scripts subdirectory (\searchstax-client-master\solr-7\scripts). Locate zkcli.sh and zkcli.bat in that directory. These are the Linux and Windows versions of the script, respectively.

zkcli Help

If you run the zkcli script using the "help" keyword, it displays a lengthy list of options and examples. See What else can I do with the zkcli script? for examples.


4. Upload a Solr Configuration

It is easy to deploy your Solr project to the cloud. This involves uploading your Solr configuration files to the Zookeeper ensemble of your SearchStax deployment. Zookeeper, in turn, distributes the configuration files to the server(s) that need them.

We have provided example configuration files and data for the purposes of this exercise.

In a terminal window, navigate to the \searchstax-client-master\solr-7\scripts directory and then run the appropriate script:

Linux (Bash):

$ ./zkcli.sh -zkhost <zookeeper URL> -cmd upconfig -confdir <Solr configuration> -confname <configuration name>

Windows Command Prompt (DOS):

$ zkcli.bat -zkhost <zookeeper URL> -cmd upconfig -confdir <Solr configuration> -confname <configuration name>

Windows PowerShell:

> .\zkcli.bat -zkhost <zookeeper URL> -cmd upconfig -confdir <Solr configuration> -confname <configuration name>

where <zookeeper URL> is the Zookeeper Ensemble URL from your deployment details page. SearchStax Zookeeper Ensemble
If you are running a cluster, the <zookeeper URL> is a comma-separated list. Use the entire list as the <zookeeper URL>. SearchStax Zookeeper Ensemble

<Solr configuration> is the path to your Solr configuration directory (../configsets/basic_configs/conf/ for the solr-6 zkcli, or ../configsets/_default/conf/ for the solr-7 zkcli); and <configuration name> will be Zookeeper's internal name for this configuration (test1).

For example:

./zkcli.sh -zkhost ss100141-4iwrieg8-1-us-west-1-aws.searchstax.com:2181 /
           -cmd upconfig -confdir ../configsets/_default/conf/ -confname test1

When successful, you'll see a number of INFO messages scroll by. The last few lines list the configuration files that have been uploaded to Zookeeper. The final message says "EventThread shut down."

ZkCLI Connection Error

If zkcli fails to connect, check our page of zkcli error messages to see if the problem is a common one.


5. Create a Collection

The remaining Quick Start steps require the use of cURL, a common command-line tool for getting or sending files using URL syntax. cURL is freely available for many operating systems, including Linux and Windows.

We have also provided examples using Windows PowerShell's Invoke-RestMethod, which is very similar to cURL. PowerShell is available by default on most Windows computers.

Once you have uploaded your configuration, you can create a Solr collection by specifying its name and number of replicas.

Pay attention to ReplicationFactor!

The examples here use replicationFactor=1 (the default value). This is appropriate for a single-node deployment, but multi-node clusters should use a replicationFactor equal to the number of nodes in the cluster.

In a terminal window, run the following command. (You can run this command from any directory.)

Linux (Bash):

$ curl '<Solr HTTP Endpoint>admin/collections?action=CREATE&name=<collectionName>&collection.configName=<configName>&replicationFactor=1'

Windows Command Prompt (DOS):

> curl.exe "<Solr HTTP Endpoint>admin/collections?action=CREATE&name=<collectionName>&collection.configName=<configName>&replicationFactor=1" -k

Note the use of double-quotes in cURL for Windows. Also, the "-k" switch will turn off aggressive certificate checking.

Windows PowerShell:

$ Invoke-RestMethod -uri "<Solr HTTP Endpoint>admin/collections?action=CREATE&name=<collectionName>&collection.configName=<configName>&replicationFactor=1"

<Solr HTTP Endpoint> is the URL from the deployment details page for your deployment. Screenshot

<collectionName> is the name of the new Solr collection (testcollection), and <configName> is the name of the configuration you uploaded to Zookeeper (test1).

For example:

$ curl 'https://ss100141-4iwrieg8-us-west-1-aws.searchstax.com/solr/admin/collections?action=CREATE&name=testcollection&collection.configName=test1&replicationFactor=1'

When successful, cURL will display an XML return document similar to the following one. Look for the word "success."

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <lst name="responseHeader">
        <int name="status">0</int>
        <int name="QTime">4438</int>
    </lst>
    <lst name="success">
        <lst name="10.0.0.5:8983_solr">
            <lst name="responseHeader">
                <int name="status">0</int>
                <int name="QTime">3019</int>
            </lst>
            <str name="core">
                testcollection_shard1_replica1
            </str>
        </lst>
    </lst>
</response>

If you are in any doubt about whether a collection exists, display the server's details page and click the Solr HTTP Endpoint link.

Solr HTTP Endpoint Link

This takes you to the Solr dashboard for that server. Click Collection in the navigation panel on the left. You'll see a list of all existing collections on that server. SearchStax Solr Collections In this image we see that the testcollection has been successfully created.


6. Index Documents

Once the Solr index has been initialized by creating a collection, you can load your documents.

In a terminal window, navigate to the \searchstax-client-master\solr-7\data directory. This is where our example data file, sample.json resides. This file contains two extremely brief documents:

[
 {"id" : "TestDoc1", "title_s" : "test1"},
 {"id" : "TestDoc2", "title_s" : "another test"}
]

Run the following cURL command in the terminal window:

Linux (Bash):

$ curl -X POST -H 'Content-type:application/json' -d <datafile>
    '<Solr HTTP Endpoint><collectionName>/update?commit=true'

Windows Command Prompt (DOS):

> curl.exe -X POST -H "Content-type:application/json" -d <datafile>
    "<Solr HTTP Endpoint><collectionName>/update?commit=true" -k

Note the use of double-quotes in Windows. Also, the "-k" switch will turn off aggressive certificate checking.

Windows PowerShell:

$content = [IO.File]::ReadAllText(<datafile>)
$loadresult = & Invoke-RestMethod -uri "<Solr HTTP Endpoint><collectionName>/update?commit=true" -Method Post -Body $content -ContentType 'application/json' | ConvertTo-Json

<datafile> is the path and file name of the file to upload (@sample.json). <Solr HTTP Endpoint> is the URL from the SearchStax dashboard for your deployment. <collectionName> is the name of the new Solr collection (testcollection).

For example:

$ curl -X POST -H 'Content-type:application/json' -d @sample.json 'https://ss100141-4iwrieg8-us-west-1-aws.searchstax.com/solr/testcollection/update?commit=true'

cURL returns a confirmation similar to this one:

{"responseHeader":{"status":0,"QTime":563}}

Failed Load?

If the QTime parameter is extremely low (under 10), the load probably failed. This can happen if you weren't in the \data directory, or if you forgot to put the "@" in front of sample.json.

7. Search the Collection

A simple query will demonstrate that all of the previous steps have been accomplished correctly.

You can query your Solr index (from any directory) using the following cURL command:

Linux (Bash):

$ curl '<Solr HTTP Endpoint><collectionName>/select?q=*:*&wt=json&indent=true'

Windows Command Prompt (DOS):

> curl.exe "<Solr HTTP Endpoint><collectionName>/select?q=*:*&wt=json&indent=true" -k

Note the use of double-quotes in Windows. Also, the "-k" switch will turn off aggressive certificate checking.

Windows PowerShell:

$queryresults = Invoke-RestMethod -uri "<Solr HTTP Endpoint><collectionName>/select?q=*:*&wt=json&indent=true"
Write-Host $queryresults.response | Out-Host

<Solr HTTP Endpoint> is the URL from the deployment details page for your deployment. <collectionName> is the name of the new Solr collection (testcollection). The query asks for every document (*:*), with the output in indented json format.

For instance:

$ curl 'https://ss100141-4iwrieg8-us-west-1-aws.searchstax.com/solr/testcollection/select?q=*:*&wt=json&indent=true'

A successful search returns a json document similar to this one. Note that Solr located both of our indexed documents.

{
  "responseHeader":{
    "zkConnected":true,
    "status":0,
    "QTime":22,
    "params":{
      "q":"*:*",
      "indent":"true",
      "wt":"json"}},
  "response":{"numFound":2,"start":0,"docs":[
      {
        "id":"TestDoc1",
        "title_s":"test1",
        "_version_":1546014212821614592},
      {
        "id":"TestDoc2",
        "title_s":"another test",
        "_version_":1546014212892917760}]
  }}

If you prefer, you can also query the collection through the Solr dashboard. Go back to the deployment details page for your deployment and click on the Solr HTTP Endpoint URL. Screenshot
This takes you directly to the Solr Dashboard. Select testcollection and navigate to the Query tab. The default query is *:*. Screenshot
Scroll down to the bottom of this page and click the Execute Query button. You'll see the same json response document as was discussed above.


Next Steps

Success! You have created your first SearchStax deployment with a Solr Collection. You have deployed a Solr project, loaded documents into the index, and have performed a successful query!

Now you can read through the rest of the documentation to learn the details of everything that SearchStax can do for you!


Contact Us!

Don't hesitate to reach out to the SearchStax Support Desk. We are happy to answer your questions.