Self Hosting

WebWhiz is free and open source licensed under AGPL 3.0. It allows you to modify the software for your own use. However, you must also release these modifications (Open source the project) under the same AGPL 3.0 license if you distribute the modified software to others or run it on a network server where others can use it.

If you want to modify the source code and keep the source code proprietary, to yourself, choose a Commercial license

WebWhiz self hosting


WebWhiz is an open-source project designed to be self-hosted, allowing you to run it on your own infrastructure for free. This guide will walk you through the process of setting up and running WebWhiz using Docker and docker-compose.


Before you begin, make sure you have the following prerequisites installed on your system:

  • Docker: A platform that allows you to automate the deployment and management of applications in containers. You can download and install Docker from the official Docker website.
  • docker-compose: A tool that simplifies the process of defining and running multi-container Docker applications. You can install docker-compose by following the official docker-compose installation guide.


Follow these steps to install and run WebWhiz on your local machine:

  1. Clone the WebWhiz repository:
      git clone
  2. Navigate to the root directory of the cloned repository:
    cd webwhiz
  3. Edit the .env.docker file located in the root directory. This file contains environment variables that are used to configure WebWhiz. Add your OpenAI API keys to the following variables:

    Note: You can obtain the OpenAI API keys by signing up for an account on the OpenAI website.

  4. Start the WebWhiz stack using docker-compose:
    docker-compose up

    This command will build the necessary Docker containers and start the WebWhiz application. You will see the progress of the build process in the terminal.

    The WebWhiz stack consists of multiple services defined in the `docker-compose.yml` file. It includes the WebWhiz UI, backend API, and any other required services.

  5. Once the building process is complete and WebWhiz starts, you can access the user interface (UI) by opening your web browser and navigating to:
    The backend API will be available at:
    Widget will be available at:
    Note: If you want to run WebWhiz as a background process, you can use the following command:
    docker-compose up -d
  6. To stop WebWhiz, run the following command:
    docker-compose down
  7. If you make any changes to the WebWhiz source code or the Docker configuration, and those changes are not picked up when starting the application, you can force a rebuild of all containers using the following command:
    sudo docker-compose up --build --force-recreate

    This command will ensure that all containers are rebuilt from scratch.

To add the chatbot to your website, refer Adding Chatbot to your website section.

That's it! You have now successfully set up and started WebWhiz in your own hosting environment. For further configuration details or troubleshooting, refer to the official WebWhiz documentation or the Docker and docker-compose documentation.

Remember that running a self-hosted application comes with its own set of responsibilities, including regular updates, security checks, and maintenance tasks. Always keep your system and WebWhiz up to date to ensure the best performance and security.

In addition to the self-hosted option, we also provide a fully managed hosted solution for WebWhiz. With the hosted solution, we take care of all the security and maintenance aspects, allowing you to focus solely on utilizing the chatbot capabilities of WebWhiz.

WebWhiz Manual Installation Guide

WebWhiz is designed to be a production-grade chatbot that can be scaled up or down to handle any volume of data. This guide will walk you through the process of manually setting up and installing WebWhiz.


WebWhiz consists of three main components:

  • API Server: This is the main backend web server for WebWhiz, built using NestJS.
  • JS Celery Worker: Handles crawling and embeddings generation.
  • Python Celery Worker: Handles container cosine similarity calculations and HTML/PDF content extraction.

WebWhiz uses MongoDB for the database and Redis for caching. It also utilizes third-party services, including OpenAI, for powering the chatbot and error monitoring.


Before you begin the installation process, make sure you have the following prerequisites installed on your system:

  • MongoDB v6: A document-oriented database for storing WebWhiz data.
  • Redis v7: An in-memory data structure store used for caching.
  • Node v18 or above: JavaScript runtime environment for running the API server.
  • Yarn: A package manager for managing WebWhiz dependencies.
  • Python v3.6 or above: The Python programming language is required for running the Celery workers.

Setting Environment Variables

To configure WebWhiz, follow these steps:

  1. Create a copy of the .env.sample file located in the root directory of the WebWhiz repository.
  2. Rename the copied file as .env
  3. Open the .env file in a text editor and set the following mandatory variables:
    HOST: The IP to which the web server should bind (typically set as
    PORT: The port on which the web server should listen (default is 3000).
    SECRET_KEY: A secret used for encryption (e.g., JWT).
    MONGO_URI: The MongoDB URI to connect to the MongoDB database.
    MONGO_DBNAME: The name of the MongoDB database.
    OPENAI_KEY: Your OpenAI API key.
    OPENAI_KEY_2: An alternate OpenAI API key. You can use the same API key for both if you don't have a separate one.
  4. Inside the workers folder, create a copy of the .env.sample file and rename it as .env
  5. Set the values for the following variables in the .env file: MONGO_URI, MONGO_DBNAME, REDIS_HOST, REDIS_PORT

Installing Dependencies and Running the App

Follow these steps to install the necessary dependencies and run the WebWhiz application:

  1. Open a terminal and navigate to the root folder of the WebWhiz repository.
  2. Run the following command to install the Node dependencies:
      yarn install
  3. Navigate to the workers folder:
      cd workers
  4. Create a Python virtual environment:
      python3 -m venv venv
  5. Activate the virtual environment:
      source venv/bin/activate
  6. Install the Python worker dependencies:
      pip install -r requirements.txt
  7. Go back to the root folder of the WebWhiz repository:
      cd ..
  8. Build the application:
    yarn run build
  9. Install pm2, a process manager for Node.js (use sudo if required):
    npm install -g pm2
  10. Start the application using pm2:
    pm2 start ecosystem.config.js
This command will start the backend HTTP server, the JS Celery worker, and the Python Celery worker.

Frontend Setup

To set up the WebWhiz frontend, follow these steps:

  1. Create a .env file in the frontend folder.
  2. Add the following variables to the .env file:
    GOOGLE_AUTH_ID='Only if you need Google login'
  3. Navigate to the frontend folder in the terminal.
  4. Install the frontend dependencies:
      npm install
  5. Run the frontend app:
      npm run start
Alternatively, you can run npm run build to package the frontend app.

Adding Chatbot to your website

To set up the WebWhiz chatbot on your website, add the following script tag to your HTML:

<script id="__webwhizSdk__" widgetUrl="YOUR_WIDGET_URL" baseUrl="YOUR_BASE_URL" src="webwhiz-sdk.js" chatbotId="YOUR_CHATBOT_ID"></script>

Replace YOUR_WIDGET_URL, YOUR_BASE_URL, and YOUR_CHATBOT_ID with your actual values.


  • widgetUrl: This is the URL of the chatbot iframe that the script uses to build the chatbot. Replace YOUR_WIDGET_URL with the URL where the chatbot iframe resides.
  • baseUrl: This is the base URL of the API used to fetch the data. Replace YOUR_BASE_URL with the base URL of your API.
  • chatbotId: The unique identifier of your chatbot. Replace YOUR_CHATBOT_ID with your chatbot’s unique identifier.


Here’s an example of a configured script tag for self-hosted configuration:

<script id="__webwhizSdk__" widgetUrl="" baseUrl="" src="webwhiz-sdk.js" chatbotId="64fs3dfdc33675875fd4c0ec1"></script>

In the above example, the widgetUrl is set to, the baseUrl is set to, and the chatbotId is 64fs3dfdc33675875fd4c0ec1.

Please ensure to replace these values with your actual URLs and Chatbot ID.

If you’re not self-hosting, you only need to specify the chatbotId. The widgetUrl and baseUrl will use default values. After inserting the relevant script tag into your website, the WebWhiz chatbot will be enabled and configured as per your settings.

If you encounter any issues during the installation process, please reach out to for assistance.

Frequently Asked Question

Have more questions? Ask the chatbot or email us at

What does it mean for the software to be dual licensed?

Dual licensing means that the software is available under two different licenses: AGPL 3.0 and a commercial license. Users can choose the license that best suits their needs. The AGPL 3.0 offers open-source distribution and modification rights, while the commercial license allows users to keep the source code closed.

Can I customize the software for my own needs?

Yes, the Affero General Public License v3.0 (AGPL 3.0) allows you to modify the software for your own use. However, you must also release these modifications (Open source the project) under the same AGPL 3.0 license if you distribute the modified software to others or run it on a network server where others can use it.

Am I allowed to distribute the software?

Absolutely. You can freely distribute the software under the AGPL 3.0. However, you must provide the source code, including any modifications you've made, to the recipients. If the software is run over a network, users must be able to access its source code.

How does the "network use" clause in AGPL 3.0 affect my application?

AGPL 3.0 has a clause for software running over a network (often referred to as the "ASP loophole"). If your application is running on a network server and users interact with it there, you must provide a way for them to receive the source code of the application.

Can I purchase a commercial license to keep my modifications private?

Yes, the commercial license allows you to modify the source code and keep it closed source. This is a common practice for businesses who want to use the software in a proprietary product or service without having to share their modifications.

If I purchase a commercial license, am I exempt from the AGPL 3.0 conditions?

Yes, purchasing a commercial license allows you to use the software without adhering to the AGPL 3.0 conditions. You would instead need to adhere to the terms set out in the commercial license agreement.

Can I customize and keep the source code closed without purchasing a commercial license?

No, if you wish to customize the software and keep the source code closed, you need to acquire a commercial license. The AGPL 3.0 requires that any distribution of the modified software must also be licensed under AGPL 3.0, including the corresponding source code. To keep the modifications private, you must obtain a commercial license.

Can I remove the powered by option if I self-host?

It depends, If you use the project under AGPL 3.0, you can remove the branding but, you'll have to open source the entire applications source code. If you purchase a commercial Team or organization license, you can remove the powered by option and keep the source code private