Installing

Seven steps on your own server. Your site gets one new folder and one script tag; nothing else on it changes.

This is the self-hosted way. To have Opensolr run the same chat for you, with nothing to install, see Put the chat on your site in the platform documentation.

The examples use /var/www/your-site for your project folder, public for its web root, /opt/opensolr-chat for the data folder and www-data for the user PHP runs as. Put your own in their place.

In your project folder, the one that holds (or will hold) vendor/:

cd /var/www/your-site
composer require opensolr/chat-bot-client

A folder outside the web root, owned by the user PHP runs as. The client keeps its SQLite database there (chat.sqlite, plus the small files SQLite writes next to it) and your logo. Nothing in it is meant to be downloaded, so it must not be reachable from the web.

sudo mkdir -p /opt/opensolr-chat
sudo chown www-data:www-data /opt/opensolr-chat
sudo chmod 700 /opt/opensolr-chat

The user PHP runs as is www-data on Debian and Ubuntu. On Red Hat, Rocky or AlmaLinux it is usually apache or nginx, and on shared hosting it is often your own user.

Copy the front controller and its .htaccess from the package into a folder of your web root named opensolr-chat:

cd /var/www/your-site
mkdir -p public/opensolr-chat
cp vendor/opensolr/chat-bot-client/examples/public/opensolr-chat/index.php public/opensolr-chat/index.php
cp vendor/opensolr/chat-bot-client/examples/apache.htaccess public/opensolr-chat/.htaccess

This is public/opensolr-chat/index.php:

<?php
require __DIR__ . '/../../vendor/autoload.php';
(new Opensolr\ChatBot\App([
    'data_dir'  => '/opt/opensolr-chat',   // outside the web root, writable by PHP; the SQLite file lives here
    'base_path' => '/opensolr-chat',       // the URL path this file answers on
]))->run();

Check three things in it:

• The require line points at your Composer autoloader. /../../vendor/autoload.php is right when the web root is a folder inside the project, as here; when the web root is the project folder itself, it is /../vendor/autoload.php.
• data_dir is the folder you created in step 2.
• base_path is the URL path of this folder. To mount the chat somewhere else, rename the folder and change base_path to match; every other address follows it.

Then send every request of that path to the front controller, on your web server:

• Apache: the .htaccess you just copied does it. See Mounting the chat on Apache.
• nginx: one location block. See Mounting the chat on nginx.
• A reverse proxy, load balancer or CDN in front of your site: also read Behind a proxy.

In the project folder, as the user PHP runs as, so the database it creates belongs to that user and the web server can write it:

cd /var/www/your-site
sudo -u www-data php vendor/bin/opensolr-chat-bot password /opt/opensolr-chat

It asks for the password twice, without showing it as you type. It must have at least 12 characters. When it is saved, the command says where:

The admin password is saved in /opt/opensolr-chat/chat.sqlite. Every admin session was signed out.

More, and how to change it later: The admin password.

1. Open https://your-site/opensolr-chat/admin and sign in with the password. See Signing in to the admin.
2. On the Account tab, enter your Opensolr email and an API key, and click Test connection. It lists your indexes.
3. Choose the index the chat answers from and click Save settings. See Account and index.

Paste this before </body> on every page that should show the chat:

<script src="/opensolr-chat/widget.js" defer></script>

The Add to your pages tab of the admin shows the same tag for the path you chose. More on Add the chat to your pages.

• https://your-site/opensolr-chat/widget.js opens as JavaScript.
• https://your-site/opensolr-chat/config shows a short JSON with the title of your chat.
• A page with the script tag shows the chat button at the bottom right, and a question gets an answer that appears word by word.

If one of them does not, Troubleshooting starts from these same three checks.