Installing

Six steps. Your site gets one new folder and one script tag; nothing else on it changes.

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

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.

Behind a reverse proxy, a load balancer or a CDN

Add trusted_proxies, the addresses or ranges of the proxies in front of your site, so the chat sees each visitor’s own IP address and knows when the visitor is on HTTPS:

(new Opensolr\ChatBot\App([
    'data_dir'        => '/opt/opensolr-chat',
    'base_path'       => '/opensolr-chat',
    'trusted_proxies' => ['127.0.0.1', '10.0.0.0/8'],
]))->run();

Without it, every visitor arrives with the address of the proxy and they all share one set of limits. List only proxies you run or trust: the chat believes the visitor address they send.

Apache

The .htaccess you copied sends every address under the folder to index.php and keeps the chat’s answers uncompressed, so they can arrive word by word:

Options -Indexes

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L,QSA]
</IfModule>

<IfModule mod_setenvif.c>
    SetEnvIf Request_URI "/chat$" no-gzip=1 dont-vary=1
</IfModule>

Apache must have mod_rewrite enabled and allow .htaccess in that folder (AllowOverride All, or at least FileInfo Options). With PHP-FPM behind Apache, also read Streaming: one line in your virtual host decides whether answers arrive word by word.

nginx

nginx does not read .htaccess. Add this to the server block of your site, with your own PHP-FPM socket:

location /opensolr-chat/ {
    try_files $uri /opensolr-chat/index.php$is_args$args;
}

location = /opensolr-chat/index.php {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root/opensolr-chat/index.php;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    fastcgi_buffering off;
    gzip off;
}

Then check and reload: sudo nginx -t && sudo systemctl reload nginx.

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.

1. Open https://your-site/opensolr-chat/admin and sign in with the password. See 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.