Getting started

From the code to your first customer

This page is for someone who has never put a program on a server. It takes you from the code you downloaded to a live chat window on a customer’s website. Every command is shown in full. When something goes wrong, the step says what to do next.

Examples use the web address chat.sharmafurniture.in and the e-mail owner@sharmafurniture.in. Replace them with your own.

01Words used here#

Six words come up again and again. You do not need to know more than this to follow the page.

VPS
A small computer you rent from a company such as DigitalOcean, Hetzner or an Indian provider. It is always on and always connected to the internet. Your customers’ websites talk to it. It costs a few hundred to a few thousand rupees a month.
Domain
A web address you own, such as sharmafurniture.in. You will use a sub-address of it, such as chat.sharmafurniture.in, for this product.
DNS record
A line in your domain’s settings that says “this address points to that server”. You add one A record that points chat to your server’s number (its IP address). Your domain company’s website has the page for it.
SSH
A way to type commands on your server from your own computer. Your VPS company gives you a user name, an address and a password or key file. On Windows 10 and 11, macOS and Linux, you open a terminal and type ssh root@your-server-address.
Git
A free program that copies a project from the internet to your computer. You can also skip it and download a zip.
Knowledge base
The collection of a business’s own material (brochures, price lists, web pages, answers to common questions) that the chat assistant reads before it answers. The widget is the chat window that appears on the business’s website.

Back to top

02Get the code#

cob-rag-engine is open source under AGPL-3.0. The code is in a public repository. You can get it in two ways. Both give you the same folder.

  • Clone it. This needs git. On the server, type git clone https://github.com/callobuzz/cob-rag-engine.git.
  • Download a release zip. Open the repository’s Releases page, download the zip of the version you want, and unzip it.

The folder is called cob-rag-engine. Inside it you will find:

  • deploy: the installer, deploy/install.sh, and the upgrade and backup scripts.
  • services/dashboard/src: the source of the dashboard, readable and not minified.
  • docs: this page and the other guides as web pages.
  • tests: the developers’ own checks. You do not need them to run, change or sell the product.

Back to top

03Install on a server#

You need a VPS with Ubuntu 22.04, Ubuntu 24.04 or Debian 12, at least 2 CPUs and 4 GB of memory, and a domain. It cannot run on shared hosting, cPanel or a website builder. The full list is on the requirements page.

  1. Point a web address at the server. In your domain’s settings, add an A record: name chat, value your server’s IP address. For the example, that makes chat.sharmafurniture.in. It can take a few minutes, sometimes an hour, to start working.
  2. Sign in to the server. Use your server’s address.
    Terminal (on your computer)
    ssh root@your-server-address
  3. Get the code on the server.
    Terminal (on the server)
    sudo apt-get update && sudo apt-get install -y git
git clone https://github.com/callobuzz/cob-rag-engine.git
    If you prefer a release zip, copy it to the server and unzip it there; you get the same cob-rag-engine folder.
  4. Run the installer.
    Terminal (on the server)
    sudo bash cob-rag-engine/deploy/install.sh

The installer asks two questions: your web address (chat.sharmafurniture.in) and your e-mail (owner@sharmafurniture.in, the one you will sign in with). Then it checks the server, installs Docker if it is missing, sets everything up with generated passwords, gets a free HTTPS certificate and prints a sign-in link. It can take 10 to 20 minutes. To see what it would do without changing anything, add --dry-run to the command.

Done looks like this: the last lines say the installation is complete and show a long link starting with https://chat.sharmafurniture.in. Copy that link. If the installer stops, it says in plain words what is wrong and what to do; fix that and run the same command again. It is safe to run again.

Back to top

04First sign-in#

  1. Open the link the installer printed. It lets you choose a password for owner@sharmafurniture.in. The link works once and for a limited time; if it has expired, see Troubleshooting.
  2. Choose a password and sign in. You land in the dashboard as the operator: the person who runs the service and adds customers.
  3. Add an AI provider key. The chat assistant writes its answers with an AI model. Open the first-run steps in the dashboard and paste a key from a provider such as OpenRouter, OpenAI or Anthropic. Or choose the free local model that runs on your own server; it is slower and needs a bigger server (see the requirements page).
Costs that are not in the product
The AI provider’s key and what it is used for are paid to that provider, not to us, and are not included in the product. The same goes for your server, your domain and any e-mail sending service. The requirements page lists them.

To send invitations and password resets from your own address, add an e-mail sending service (SMTP) in the dashboard under the engine’s e-mail settings. Without it, the product still works; sign-in links are shown on screen instead.

Back to top

05Your first business#

A business is one of your customers: a clinic, a shop, a coaching class. Each business gets its own workspace, its own knowledge base and its own chat widget. Nothing from one business is ever shown to another.

  1. Add the business. In the dashboard open Customers and choose Add customer. Type the business’s name and the owner’s e-mail. You can also let businesses sign up themselves; the choice is in the engine settings.
  2. The owner signs in. The owner lands on a simple home page and a short first-run guide: the website address, brochures, the widget code, and a place to try the assistant.
  3. Teach the assistant. The owner can paste the website address, and the product reads the site by itself. The owner can also upload brochures and price lists as PDF or Word files, and type common questions and answers. The assistant answers only from this material.
  4. Try it. The owner asks a few real questions in the test chat and fixes anything that is missing.

The step-by-step guide walks the same path with screens.

Back to top

06The chat widget#

The widget is one line that the business (or you) puts on the website, just before the closing </body> tag:

Website page
<script src="https://chat.sharmafurniture.in/widget.js" data-key="pk_your_key_here" async></script>
  1. Create a widget key. In the business’s workspace open the knowledge base, then its widget keys, and create one. The dashboard shows the exact line to copy.
  2. Allow the website. A widget key only works on the websites you list under allowed sites, for example https://www.sharmafurniture.in. This stops other websites from using the key.
  3. Test it. Open the website, wait a moment and look for the chat bubble in the corner. Ask a question. If the bubble does not appear, see Troubleshooting.

The widget works on any website that lets you add a script: WordPress, Shopify, Wix, plain HTML.

Back to top

07WhatsApp#

The assistant can also answer on a business’s own WhatsApp Business number. Messages pass through Meta, the company behind WhatsApp, so you need three things from Meta: a Meta business account, a Meta app, and a WhatsApp Business number for each business. Meta has its own review steps and sometimes its own fees.

Do this after the chat widget works. The steps, with what to click at Meta, are in the deploy guide. Until then, everything else works without WhatsApp.

Back to top

08Licence#

In plain words:

AGPL-3.0
The engine and the dashboard are under the GNU AGPL-3.0. You can run it, change it and charge your customers for chatbots built on it. If you change the code and let other people use your version over the internet, AGPL-3.0 asks you to offer those people the source of your version.
MIT
The client libraries in clients/ and the widget scripts are under the MIT licence. You can put them in your own closed products.
Commercial licence
A company that does not want the AGPL-3.0 conditions can ask Callobuzz for a commercial licence at https://callobuzz.com/contact.

Every feature works for everyone. There is no activation step and no limit on the number of businesses. The “Powered by” line in the chat window is shown by default, and the operator can hide it under Branding. The product never switches itself off and never sends data about your businesses to us.

Back to top

09Upgrade#

Every release is free. The repository’s Releases page and the CHANGELOG say when a new version is out. Get the new version on the server as in the install section (a new release zip, or a fresh clone in another folder), and run:

Terminal (on the server)
sudo bash /opt/cob-rag/current/deploy/upgrade.sh cob-rag-engine-NEW.zip

Use the real file name of the new zip, or the new folder. The upgrade makes a backup first, builds the new version while the old one keeps answering, updates the database, and switches over. If something looks wrong afterwards, go back to the version and data from before the upgrade:

Terminal (on the server)
sudo bash /opt/cob-rag/current/deploy/upgrade.sh --rollback

Add --dry-run to see what an upgrade would do without changing anything.

Back to top

10Backups#

The installer sets up a backup every night at 2:30 and keeps the last 7 days in /opt/cob-rag/backups. To make one right now:

Terminal (on the server)
sudo bash /opt/cob-rag/current/deploy/backup.sh

To put one back, name its folder. The command checks the backup, asks you to type restore, and puts the data back:

Terminal (on the server)
ls /opt/cob-rag/backups
sudo bash /opt/cob-rag/current/deploy/restore.sh /opt/cob-rag/backups/THE-BACKUP-FOLDER
A backup on the same server is not enough
If the server is deleted, its backups go with it. Copy the backup folder to another computer or to storage at another company every week. The folder contains your settings file, so keep the copy private.

Back to top

11Support#

Community support runs through GitHub issues, best effort. Commercial support is by contract: https://callobuzz.com/contact.

  • Community support: questions about how a feature works, bug reports, and every update.
  • Not covered by community support: installation on your server, customisation, hosting and server administration, and third-party services and keys such as AI providers, Meta and e-mail providers, with their costs.
  • How to ask: open an issue in the repository with the version, what happened and what you expected.
  • Security problems: do not post them in a public issue. E-mail callobuzz@gmail.com with a subject that starts with “SECURITY:”. The support page says what happens next.

Back to top

12Questions#

Can I use shared hosting?
No. Shared hosting, cPanel, WordPress hosts and website builders cannot run Docker, and the product needs it. Rent a VPS instead.
Do I need a GPU?
No. A normal server is enough. The AI model that writes answers usually runs at your AI provider, not on your server.
Which AI providers can I use?
Any of the big ones, for example OpenRouter, OpenAI, Anthropic, Google and Mistral, and the free local model on your own server. You choose, and you can change later.
Can I change the dashboard?
Yes. Its source is in cob-rag-engine/services/dashboard/src. Change it, then run the upgrade or the installer again to rebuild it. Community support covers the product as released, not your changes.
Does it send data to you?
No. Nothing about your businesses, visitors or documents leaves your server, except to the AI provider you choose.
Can I remove the “Powered by” line?
Yes. The operator can hide it under Branding.
Does it run on Windows or macOS?
For trying it on your own computer, yes, with Docker Desktop; see the step-by-step guide. A live server runs on Linux.

Back to top

13Troubleshooting#

Problem
The browser says the connection is not secure, or the site does not load, right after install.
What to do
The free HTTPS certificate needs the DNS record to be working. Wait 10 minutes, then check that the web address shows your server’s IP address. Make sure ports 80 and 443 are open at your VPS company. Then run the installer again; it is safe to repeat.
Problem
The installer says port 80 or 443 is already in use.
What to do
Another program on the server (often an old Apache or Nginx) is using it. Stop and disable it, for example sudo systemctl disable --now apache2, then run the installer again.
Problem
The sign-in link has expired or does not work.
What to do
Ask for a new one:
Terminal (on the server)
sudo docker compose --project-directory /opt/cob-rag/current exec app python -m callobuzz_rag.accounts.bootstrap --resend --print-link
Problem
The server runs out of memory while the installer builds, and the installer stops.
What to do
The server is too small. 4 GB of memory is the minimum. Resize the server at your VPS company, then run the installer again. It adds a swap file on small servers, which helps but does not replace memory.
Problem
The chat bubble does not show on the website.
What to do
Check three things. First, the website’s exact address (with https:// and, if it is used, www.) is listed under the widget key’s allowed sites. Second, the script line is on the page and the key starts with pk_. Third, open the page, press F12 and look at the Console tab for a message that starts with [cob-rag widget]; it says what is wrong.
Problem
Something else is wrong and you want to see what the product says.
What to do
Read the last lines of its log, and send them with your question to support:
Terminal (on the server)
sudo docker compose --project-directory /opt/cob-rag/current logs --tail 100 app

More answers are in the deploy guide’s troubleshooting section.

Back to top