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 two-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 New 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 is restricted to either a single-node AWS NDN2 deployment or a two-node AWS NDC4 cluster.)

For this exercise, we assume that your deployment uses Solr-8.

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 summary on the Cloud Manager page by clicking the "Card View" button (upper right):

SearchStax Deployment link

This display summarizes the state of the deployment. We can easily see that the new deployment is running under almost zero load.

To view the server details, click the name of the deployment (QuickStart). This opens the deployment details page.

SearchStax Server Details

The details page shows the status of all deployment servers plus the URLs of the deployment's Solr HTTP Endpoint and Zookeeper Ensemble. This is an NDC4 cluster. It has two Solr servers and three independent Zookeeper servers. The table shows the health of all five servers.

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 (such as the NDN2) has only one Zookeeper instance. It runs on the same server as Solr. A cluster (NDC4) has three Zookeeper instances, each on its own independent server. They are collectively called "the ensemble." (For more information on this architecture see SearchStax NextGen Solr Clusters: When Less is More.)

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.

You can download the SearchStax zkcli ZIP file here: searchstax-client-master.zip. It is about 220 MB.

Unzip the file. The top-level directory is \searchstax-client-master. There are subdirectories for different versions of Solr.

Config path changed between solr-6 and solr-7

Note that the path to the \config directory in solr-5 and solr-6 is
..\configsets\basic_configs\conf
while the path under solr-7 and solr-8 is
..\configsets\_default\conf.

We assume that you are using Solr 8 in this exercise.

Navigate to the scripts subdirectory (\searchstax-client-master\solr-8\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. The first step is 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-8\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, which is ../configsets/_default/conf/ for the solr-8 zkcli); and <configuration name> will be Zookeeper's internal name for this configuration (test).

For example:

./zkcli.sh -zkhost ss790439-3rx3ga27-1-ap-northeast-1-aws.searchstax.com:2181,ss790439-3rx3ga27-2-ap-northeast-1-aws.searchstax.com:2181,ss790439-3rx3ga27-3-ap-northeast-1-aws.searchstax.com:2181 /
           -cmd upconfig -confdir ../configsets/_default/conf/ -confname test

When successful, you'll see a number of INFO messages scroll by.

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

A collection is a logical index. The next step is to create a collection so we can load data into it.

Pay attention to ReplicationFactor!

The replicationFactor must be equal to the number of Solr nodes in the cluster.

See Some of our Replicas are Missing! for a discussion of the subtle things that can go wrong because of this issue.

Solr 6.x+

For recent versions of Solr, by far the easiest way to create a collection is to open the Solr Dashboard and fill out a simple form: SearchStax Create Collection

  1. From the Deployment Details page, click on the deployment's Solr HTTP Endpoint URL.
  2. Select the Collections tab on the left.
  3. Click the Add a Collection button.
  4. Fill out the pop-up form:

    1. For this exercise, the name is testcollection.
    2. When we uploaded the configuration using zkcli, we called the config set test.
    3. The numbShards parameter should always be 1 unless a Solr expert tells you otherwise.
    4. The replicationFactor is the number of Solr servers in your deployment.
    5. Click the Add Collection button.

All Solr Versions

Solr versions prior to 6.x don't offer a way to create collections from the Solr Dashboard, so we must invoke the Solr API instead. This method works for all Solr versions.

The remaining Quick Start steps require the use of command-line tool for getting or sending files using URL syntax.

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 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'


6. Index Documents

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

In a terminal window or PowerShell window, navigate to the \searchstax-client-master\solr-8\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 command in the Linux terminal window:

Linux (Bash):

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

<datafile> is the path and file name of the file to upload (either the full file path or @sample.json if the focus is in the data directory). <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'

If you are in Windows, open a PowerShell window. Enter these lines in sequence:

Windows PowerShell:

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

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

For example:

$content = [IO.File]::ReadAllText("c:\searchstax-client-master\solr-8\data\sample.json")
$RESULTS = & Invoke-RestMethod -uri "https://ss790439-3rx3ga27-ap-northeast-1-aws.searchstax.com/solr/testcollection/update?commit=true" -Method Post -Body $content -ContentType 'application/json' 

7. Search the Collection

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

The easiest way to query your collection is to return to the Solr Dashboard and use the query page.

  1. From the Deployment Details page, click on the deployment's Solr HTTP Endpoint URL.
  2. Select the testcollection in the droplist in the left margin.
  3. Click the Query tab, also in the left margin.
  4. Scroll to the bottom of the Query page and click the Execute Query button.

Screenshot

If you have been successful, you will see our two sample documents in the response as shown 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.