Heroku

Install the addon

There are two ways to install the Websolr addon to your Heroku app: via the command line, and via the Heroku dashboard. The index will be created in the same region as your Heroku app.

It is possible to install multiple Websolr addons to the same Heroku app. One use case for this might be having a Solr index for each language supported by the application.

The first addon will create an environment variable called WEBSOLR_URL, with the path to your Solr index. Subsequent addons will have environment variables called WEBSOLR_[COLOR]_URL, for example WEBSOLR_CHARCOAL_URL.

Option 1: Using the command line

The Heroku CLI tool can be used to attach Websolr to your Heroku app like so:

$ heroku addons:create websolr[:PLAN] [-a APP_NAME] [--config=config slug]

There are three optional parameters supported:

• :PLAN is a slug that can be appended to the app name that corresponds to the plan level the index should be created with. For example, heroku addons:create websolr:standard-small will create the resource on the Standard Small plan (see the addons page for current options). If no plan is specified, it will default to the cheapest available.
• -a This is the Heroku app slug you would like the addon attached to
• --config This is a slug of a Solr configuration that the new index should use. If nothing is specified here, it will default to Sunspot.

Option 2: Using the Heroku App Dashboard

From your Heroku app dashboard, click on the Resources tab:

Next, type 'websolr' in the search bar. This will bring up the Websolr addon:

Click on the addon. This will bring up a confirmation screen where you can select a plan level. To see the details of what is available with each plan, check out the addons page. You can upgrade or downgrade your plan at any time.

Once you have selected a plan, click on "Provision". This will create your new Solr index.

About Your New Solr Index

Regardless of the method used to add Websolr to your application, an environment variable called WEBSOLR_URL will be created. This variable contains a special URL to your index. This URL is your application's sole means of communicating with Solr.

Some applications expect Solr to be running locally, which is not the case with Websolr on Heroku. If your application has settings that point to locations like localhost:8983 then these will need to be updated. Consult the documentation for your Solr client for details.

Additionally, Rails users with the Sunspot Solr client may see rake tasks like bundle exec rake sunspot:solr:start available. These will have no effect within Heroku because Solr can not be run on your dynos. However, bundle exec rake sunspot:reindex tasks will work as expected.

How To Find Your Solr Index URL

You can find the special URL in a few different ways:

Option 1: Using the command line

The Heroku CLI tool has a feature to get the value of a specific environment variable:

$ heroku config:get WEBSOLR_URL [-a APP_NAME]

The -a flag is optional, it simply tells Heroku which application should be queried.

Option 2: Using the Heroku App Dashboard

You can access your Websolr URL from the Heroku dashboard by clicking on the "Settings" tab:

Click on the "Reveal Config Vars" button to show the environment variables for the app. You will see the URL in the WEBSOLR_URL field:

Option 3: Using the Websolr Dashboard

The URL can also be found via the Websolr dashboard:

Read on for information about accessing the Websolr dashboard.

Accessing the Websolr Dashboard

Websolr provides a dashboard for managing and inspecting your Solr index. This dashboard can be accessed in one of two ways:

Option 1: Using the Heroku CLI

The Heroku CLI tool can be used to open the dashboard for an addon:

$ heroku addons:open websolr [-a APP_NAME]

The -a flag is optional, it simply tells Heroku which application is the intended target.

Option 2: Using the Heroku App Dashboard

Click on the "Resources" tab to get a list of installed addons for your app. Click on the Websolr addon to be taken to the Websolr dashboard:

This will open up a landing page with a list of Solr resources on it. For most users, there will only be one listing. Click on this index to open up the dashboard:

The Websolr dashboard shows an overview of your Solr index: name, region, version, plan, etc. There are other tabs for more advanced features as well. These are covered later in the documentation:

Note that if you have several Websolr addons for an application, each addon will have its own dashboard.

Next Steps

Now that you have a Solr index provisioned for your Heroku app, you will need to integrate it into your application. That process varies based on your application. Rails apps will need a client like Sunspot or RSolr, Django apps will need Haystack, Drupal or Wordpress apps will need Solr modules and plugins respectively.

When it's time to scale, you can easily add or remove search resources. This guide covers the process for Heroku users.

Changing Your Websolr Addon Plan

There are two ways to change your Websolr addon plan: through the Heroku CLI tool, or through the Heroku App Dashboard. Regardless of the method used, the changes will take effect immediately.

Note that changes to your Websolr addon plan do not affect your data. Upgrading or downgrading will not require any downtime or reindexing.

Option 1: Using the Heroku CLI tool

The Heroku CLI tool has options to upgrade or downgrade an addon's plan:

heroku addons:upgrade websolr:<plan-slug> [-a APP NAME]

heroku addons:downgrade websolr:<plan-slug> [-a APP NAME]

These commands have an optional -a parameter, which allows the user to specify which Heroku app should have its Websolr addon changed.

The plan-slug is a unique identifier for a Websolr plan. These can be found on the Websolr Heroku Addon page:

Option 2: Using the Heroku app dashboard

Log into Heroku and navigate to your applications list. Click on the application that has Websolr installed to navigate to its dashboard. In this example, it's mycoolsolrapp:

Once open, you'll see an Add-ons list for the app, as well as the plan you're currently on for the app. To edit the plan, click the menu icon on the far right:

Choose "Edit plan". A modal will pop up with a dropdown list of available plans. Choose the new plan you'd like to move to:

Click on the "Provision" button, and your Websolr addon will be instantly updated.

Removing the Websolr addon is a very simple and straightforward process on Heroku. However, it will result in your data being permanently destroyed. Please take proper care to ensure that the addon is being removed from an application that no longer relies on it.

Removing the Websolr Addon

There are two ways to remove the Websolr addon from a Heroku application: via the command line, or through the Heroku App Dashboard. Regardless of the method used, the index will be destroyed immediately.

Option 1: Using the Heroku CLI tool

The Heroku CLI tool has an option to remove an addon from an application:

heroku addons:destroy websolr [-a APP NAME] [-c APP NAME] [-f]

This command has three optional parameters:

• -a This allows specifying an application slug so Heroku knows exactly which application is the intended target.
• -c This option allows users to bypass the confirmation input. If left blank, the CLI tool will ask you to enter the application's name before it will remove the addon.
• -f This option tells Heroku to remove the Websolr addon even if it is connected to another Heroku app.

Option 2: Using the Heroku app dashboard

Log into Heroku and navigate to your applications list. Click on the application that has Websolr installed to navigate to its dashboard. In this example, it's mycoolsolrapp:

Once open, you'll see an addons list for the app, as well as the plan you're currently on for the app. To remove the addon, click the menu icon on the far right:

A modal will appear asking you to type the name of your application to confirm the removal of the Websolr addon:

Entering the application name will enable the "Remove add-on" button. Click on this, and your Websolr addon will be destroyed.