Self Hosting

Docker #

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.

Prerequisites #

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.

Installation #

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

1. Clone the WebWhiz repository:

     git clone https://github.com/webwhiz-ai/webwhiz.git

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:

   OPENAI_KEY=your-openai-api-key
   OPENAI_KEY_2=your-openai-api-key-2

   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:

   http://localhost:3030

   The backend API will be available at:

   http://localhost:3000

   Widget will be available at:

   http://localhost:3031

   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.

Components #

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.

Prerequisites #

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 0.0.0.0).
   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

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:

   REACT_APP_BASE_URL='https://api.website.com'
   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

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.

Parameters #

• 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.

Example #

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

<script id="__webwhizSdk__" widgetUrl="https://widget.webwhiz.ai/" baseUrl="https://api.webwhiz.ai" src="webwhiz-sdk.js" chatbotId="64fs3dfdc33675875fd4c0ec1"></script>

In the above example, the widgetUrl is set to https://widget.webwhiz.ai/, the baseUrl is set to https://api.webwhiz.ai, 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 hi@webwhiz.ai for assistance.