Add Banimark to a Node.js app

Banimark is written in PHP, and it stays that way. On a Node stack it runs as a small, self-contained service on the same box, mounted under one path by your web server. Your Express, Next.js, Nuxt or Fastify app is not touched: no middleware, no npm dependency, no change to how you deploy.

Three things have to be true, and the rest is detail:

1. PHP and a database exist on the server.
2. The ionCube loader is active, because licensed builds ship encoded.
3. Banimark answers on the same origin as the pages showing the widget.

What the server needs

No queue worker, no Redis, no Node build step, no cron job required.

Put PHP and MySQL on the server

Banimark is a PHP application. If your box has never run PHP, this is the whole of it — about five minutes of copy-and-paste, and it changes nothing about how your Node app runs. PHP-FPM is a small, well-behaved service; it will not interfere with what is already there.

sudo apt update
# Ubuntu 24.04 has php8.3 in its own repositories. On older releases, or for a
# newer PHP, add Ondrej's archive first:
#   sudo add-apt-repository ppa:ondrej/php && sudo apt update

sudo apt install -y php8.3-fpm php8.3-cli php8.3-mysql php8.3-curl php8.3-mbstring php8.3-xml
sudo apt install -y mysql-server
sudo systemctl enable --now php8.3-fpm mysql

sudo dnf install -y https://rpms.remirepo.net/enterprise/remi-release-9.rpm
sudo dnf module reset php -y && sudo dnf module install php:remi-8.3 -y
sudo dnf install -y php-fpm php-cli php-mysqlnd php-curl php-mbstring php-xml mysql-server
sudo systemctl enable --now php-fpm mysqld

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
composer --version

A database for Banimark

Give Banimark its own database and its own user. It only ever touches its banimark_* tables, so it can live beside anything else you have.

CREATE DATABASE banimark CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'banimark'@'localhost' IDENTIFIED BY 'choose-a-long-random-password';
GRANT ALL PRIVILEGES ON banimark.* TO 'banimark'@'localhost';
FLUSH PRIVILEGES;

Install the ionCube loader

Your licensed build of Banimark ships encoded, so the ionCube PHP loader has to be active before anything will run. Most commercial hosts already have it — check first:

php -v
# ...with the ionCube PHP Loader   <- you are done, skip this section

If that line is there, skip the rest of this section entirely. If it is missing, the setup script below does the whole job for you.

The quick way: run the setup script

One command checks everything Banimark needs — PHP version, extensions, the ionCube loader, Composer, whether this server can reach us — and installs the loader if it is missing. It works out your operating system, processor, PHP version and control panel by itself, and asks before it changes anything.

Look before you leap. Run it with --check first: it reports exactly what it finds and what it would do, and changes nothing at all. Safe on a live server.

curl -fsSL https://banimark.com/setup.sh | bash -s -- --check

Happy with what it says? Run it for real:

curl -fsSL https://banimark.com/setup.sh | bash

irm https://banimark.com/setup.ps1 | iex

What it does, in order:

1. Finds every PHP on the server and asks which one your website uses — on cPanel, Plesk, XAMPP or a Mac with MAMP there is usually more than one.
2. Checks PHP 8.2+, the json, curl, pdo, mbstring and sodium extensions, a database driver, and zip (for one-click updates). Where it can, it offers to install or switch on what is missing.
3. Downloads the official loader from ionCube for your exact PHP, copies it in, and adds it to PHP's configuration so it loads first — backing up any file it changes. It then starts PHP to prove it works, and puts everything back if it does not.
4. Offers to restart PHP-FPM / Apache / LiteSpeed, and to check the PHP your website actually runs (a tiny, randomly named file in your public folder, read once and deleted).

The script is plain text — read it (or the Windows one) before you run it. On shared hosting, where nobody can change PHP from a terminal, it tells you where the switch is in your panel instead.

Prefer to do it by hand, or need to send it to whoever runs your server? The manual steps:

# 1. which PHP, and where do its extensions live?
php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION."\n";'      # e.g. 8.3
php -r 'echo ini_get("extension_dir")."\n";'                     # e.g. /usr/lib/php/20230831

# 2. fetch the loaders (use ioncube_loaders_lin_aarch64.tar.gz on ARM servers)
cd /tmp
curl -fsSLO https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz
tar xzf ioncube_loaders_lin_x86-64.tar.gz

# 3. copy the ONE that matches your PHP
PHPMM=$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;')
sudo cp "ioncube/ioncube_loader_lin_${PHPMM}.so" "$(php -r 'echo ini_get("extension_dir");')/"

PHPMM=$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;')
echo "zend_extension=ioncube_loader_lin_${PHPMM}.so" | sudo tee /etc/php/${PHPMM}/mods-available/00-ioncube.ini

sudo ln -sf /etc/php/${PHPMM}/mods-available/00-ioncube.ini /etc/php/${PHPMM}/fpm/conf.d/00-ioncube.ini
sudo ln -sf /etc/php/${PHPMM}/mods-available/00-ioncube.ini /etc/php/${PHPMM}/cli/conf.d/00-ioncube.ini
sudo systemctl restart php${PHPMM}-fpm

php -v      # must now say "with the ionCube PHP Loader"

How you will know

You do not have to guess. If the loader is missing, or PHP has not been restarted since you added it, every Banimark admin page shows “Banimark needs the ionCube Loader” with these steps, the chat widget politely says support is temporarily unavailable, and the rest of your site carries on as normal. On Laravel, php artisan banimark:doctor says the same thing in the terminal. Once it is fixed, reload — nothing needs reinstalling.

Install Banimark

Give it a directory of its own, outside anything Node serves:

sudo mkdir -p /var/www/banimark
sudo chown "$USER" /var/www/banimark
cd /var/www/banimark

composer require "banimark/banimark:^0.32"

<?php
require __DIR__.'/vendor/autoload.php';

\Banimark\Standalone\App::run(__DIR__.'/banimark.config.php');

The directory must be writable by PHP-FPM while the installer runs — that is where banimark.config.php lands:

sudo chown -R www-data:www-data /var/www/banimark

Mount it on your origin

Put the entry file outside your web root and let the web server map the path to it. Banimark routes on PATH_INFO, so the whole desk — panel, widget, chat endpoint — lives under the one prefix you choose.

server {
    server_name example.com;

    # Banimark first: this location wins over the catch-all below.
    location ~ ^/banimark(/.*)?$ {
        include       fastcgi_params;
        fastcgi_pass  unix:/run/php/php8.3-fpm.sock;

        fastcgi_param SCRIPT_FILENAME /var/www/banimark/banimark.php;
        fastcgi_param SCRIPT_NAME     /banimark;
        fastcgi_param PATH_INFO       $1;
        fastcgi_param DOCUMENT_ROOT   /var/www/banimark;

        # an AI answer can take a while; the default 60s cuts long ones off
        fastcgi_read_timeout 120s;
        # room for the files visitors attach
        client_max_body_size 25m;
    }

    # everything else carries on to your Node app exactly as before
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Reload and check. SCRIPT_NAME is what Banimark builds its own URLs from, so every link it prints comes back as /banimark/…:

sudo nginx -t && sudo systemctl reload nginx
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/banimark/install    # 200

AcceptPathInfo On
Alias /banimark /var/www/banimark/banimark.php

<Directory /var/www/banimark>
    Require all granted
</Directory>

# your Node app keeps the rest
ProxyPass        /banimark !
ProxyPass        /  http://127.0.0.1:3000/
ProxyPassReverse /  http://127.0.0.1:3000/

Run the browser installer

Open https://example.com/banimark/install. Give it the database and user you created above, your admin account, and optionally your first AI provider. It writes the config and locks itself.

The panel is then at /banimark/admin, with its own login — nothing to do with your Node app's sessions.

Embed the widget

Wherever your templates end. It is same-origin, so your CSP needs no new hosts:

<script src="/banimark/widget.js" defer></script>

In Next.js, use the app-router script component so it loads after hydration:

import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script src="/banimark/widget.js" strategy="afterInteractive" />
      </body>
    </html>
  );
}

Let the AI answer about the logged-in customer

Anonymous visitors get general answers. To let the assistant look up this customer's orders, tickets or invoices, your Node app mints a short-lived signed token and the widget carries it. The token is made on your server with a shared secret; the AI never sees it, and it cannot choose whose records to read — the scoping comes from the claims you signed.

An invalid or expired token quietly means “anonymous”. It is never an error a visitor can probe.

The token is a base64url JSON payload and an HMAC-SHA256 of it — no library needed, node:crypto is enough:

import crypto from 'node:crypto';

const b64 = (b) => Buffer.from(b).toString('base64')
  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

export function banimarkToken(claims, ttlSeconds = 86400) {
  const payload = b64(JSON.stringify({
    ...claims,
    exp: Math.floor(Date.now() / 1000) + ttlSeconds,
  }));
  const sig = crypto
    .createHmac('sha256', process.env.BANIMARK_IDENTITY_SECRET)
    .update(payload)
    .digest();

  return `${payload}.${b64(sig)}`;
}

Render it into the tag for a signed-in visitor:

const token = banimarkToken({ user_id: req.user.id, name: req.user.name });
res.render('layout', { banimarkToken: token });

// <script src="/banimark/widget.js" data-token="<%= banimarkToken %>" defer></script>

Copy the secret out of the panel's install — it is the identity_secret row in banimark_settings — and put it in your Node environment as BANIMARK_IDENTITY_SECRET. Both sides must hold the same string:

mysql -u banimark -p banimark -N -e \
  "SELECT \`value\` FROM banimark_settings WHERE \`key\`='identity_secret'"

Keeping it running

There is nothing to keep running. PHP-FPM is already a service, Banimark has no worker, no queue and no cron requirement, and it holds no state outside its database. Your Node deploys do not touch it, and updating it does not touch Node.

Updating

The short version: two buttons, no terminal

Open /banimark/admin, go to Changelog, and when a new release exists you get a button that says Update to …. Press it. When it finishes, press Update the database. That is the whole thing, and nobody needs a command line, SSH or a developer to do it.

What happens when you press it:

1. Banimark downloads the release from us, using your licence key.
2. It checks the download is byte-for-byte the file we signed. If the signature or the hash does not match, it is thrown away and nothing on your server changes.
3. It unpacks the new version beside the current one — never over it.
4. It renames your current version aside as a backup, and moves the new one into place. If anything goes wrong at that step, the backup goes straight back.
5. Your previous version stays on the server — just the one, so updates never pile copies onto your disk — and Previous versions offers a Restore this one button for it.

The same page also has, whenever they apply:

• Check for updates now — on every state of the page. Banimark remembers our answer for a few hours; this asks again straight away.
• Reinstall — downloads the version you are on and puts a fresh copy in place, for when files have been damaged or edited by mistake.

If the button is not there

The Changelog page will say which of these it is, in plain words:

• Your licence has lapsed. You can still see what is new — downloading the file is what the licence pays for. Renew and the button comes back.
• The server will not let PHP write to its own folder. Common on shared hosting. The page names the exact directory to give the web server write access to; your host can do it in a minute. Until then, use the command line below.
• This release has to be installed by hand. Some releases need a step we will not do behind your back — a newer PHP, say. We hold those back from the button deliberately.

The command line, when you want it

Nothing about the button replaces this, and a developer updating from a terminal changes nothing about how the panel behaves. Name the release line you are moving to:

cd /var/www/banimark && composer require "banimark/banimark:^0.32"

Why not composer update? Banimark is still on 0.x, where Composer treats every minor release as a breaking one: ^0.25 will never install 0.26. composer update picks up fixes within your line; composer require with the new line is how you move up. The newest line right now is ^0.32.

The database changes, and what applies them

In Laravel, a release that needs new columns ships a migration and php artisan migrate applies it. You have no migration runner, so Banimark carries the same job itself: one function, Schema::ensureCurrent(), which brings an existing database up to whatever the installed version expects. It is what the panel button calls, what the Laravel migration calls, and what you can call yourself.

It is version-gated. It compares the schema_version row in banimark_settings with the version of the code now on disk, does the work once if they differ, and is a no-op every time after that. The chat endpoint never runs it, so your visitors never pay for it.

If you updated from the command line instead of the panel, signing in to /banimark/admin applies it too.

The deploy-script way: do it yourself

If you deploy from CI, or you would rather not have the first staff visit of the day be the migration, call it directly. Put this beside banimark.config.php:

<?php
require __DIR__.'/vendor/autoload.php';

$cfg = require __DIR__.'/banimark.config.php';
$pdo = new PDO($cfg['dsn'], $cfg['db_user'], $cfg['db_pass'], [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

$changed = \Banimark\Storage\Schema::ensureCurrent(
    $pdo,
    \Banimark\Licensing\Master::PACKAGE_VERSION
);

echo $changed
    ? "Banimark schema brought up to date.\n"
    : "Nothing to do.\n";

cd /var/www/banimark && composer require "banimark/banimark:^0.32"
cd /var/www/banimark && php banimark-upgrade.php

Safe to run on every deploy, in any order relative to your own migrations. On a database that was never installed it does nothing at all and says so — it upgrades an install, it does not create one. Run the browser installer for that.

What it actually does to your database

• CREATE TABLE IF NOT EXISTS for any table a new release added.
• ALTER TABLE … ADD COLUMN for any column a new release added, swallowing the duplicate error so it is safe to re-run.
• Creates any missing index.
• Converts Banimark's own tables to utf8mb4 if they are not already — the reason emoji work.

It is additive. Nothing is dropped, nothing is rewritten, and it only ever touches tables with Banimark's own prefix. Your application's schema is not involved.

Check that it worked

This matters more than it sounds, because of the next section. Ask the database what version it thinks it is on:

SELECT `value` FROM banimark_settings WHERE `key` = 'schema_version';

It must match the version shown on the panel's Changelog page. If it lags behind, the upgrade has not run.

If the version never moves

Almost always one thing: the database user Banimark connects as can read and write rows but cannot change the schema. ensureCurrent() is deliberately built never to throw — a panel that cannot write a settings row must still open — so a missing privilege looks exactly like nothing happening. No error, no warning, just an old version number.

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX
    ON banimark.* TO 'banimark'@'localhost';
FLUSH PRIVILEGES;

Then run the upgrade again. Those seven are enough for both the first install and every upgrade after it; Banimark needs no DROP and no REFERENCES.

Your licence

A fresh install asks us for a free trial on its own — 7 days, one per site . When it ends, the admin panel locks until you enter a purchased key. Your chat widget is never affected: visitors carry on being served whatever your licence says.

Enter the key under License in the panel, or set it before first boot:

BANIMARK_LICENSE_KEY=BM-XXXX-XXXX-XXXX-XXXX

Activation needs one call to our servers. After that the licence is good offline for 14 days at a time, so a network problem on your side never interrupts anything.

First five minutes in the panel

1. AI Providers — add your own key. Gemini, OpenAI, Anthropic, DeepSeek, Groq, Mistral, OpenRouter, xAI, or a local Ollama / LM Studio through a base URL.
2. Rules — plain sentences in folders, not prompt engineering. “Never promise a refund date.” Switch a folder off without deleting it.
3. Tools — the read-only lookups the assistant may run against your database. Pick a table, tick the columns it may show, and scope every row to the signed-in visitor. SELECT only, always bound, never widened by the AI.
4. Staff — invite your team. Banimark has its own logins, separate from your application's users, with per-person permissions and optional 2FA.
5. Notifications — SMTP, so a handover reaches someone.

Check it over

Before you call it done:

• Open the panel and confirm the licence page is green.
• Send a message through the widget on a real page — not just curl. The widget is JavaScript; a curl check proves nothing about it.
• Type an emoji. If it comes back, your database is utf8mb4 and you are fine.
• Ask something that needs a tool, while signed in, and confirm it returns your rows.
• Trigger a handover and confirm the email lands.

Not your stack?