diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 10cf8760..e41f94e2 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -48,10 +48,13 @@ ## FAQ +* [How can I deploy my Hexabot Project?](faq/how-can-i-deploy-my-hexabot-project.md) * [How can I add the Chatbot Widget to my Website?](faq/how-can-i-add-the-chatbot-widget-to-my-website.md) ## Developer Guide +* [Setup Node.js with NVM](developer-guide/setup-node.js-with-nvm.md) +* [Setting Up Docker for Development and Production](developer-guide/setting-up-docker-for-development-and-production.md) * [CLI Command Reference](developer-guide/cli-command-reference.md) * [Contributers Installation Guide](developer-guide/contributers-installation-guide.md) * [Hexabot UI Admin Panel](developer-guide/hexabot-ui-admin-panel.md) diff --git a/docs/developer-guide/setting-up-docker-for-development-and-production.md b/docs/developer-guide/setting-up-docker-for-development-and-production.md new file mode 100644 index 00000000..0e7963ce --- /dev/null +++ b/docs/developer-guide/setting-up-docker-for-development-and-production.md @@ -0,0 +1,49 @@ +# Setting Up Docker for Development and Production + +Hexabot uses Docker for development purposes as well as streamline deployment, running essential services like the API, frontend, and MongoDB in containers. The provided Docker Compose setup ensures quick and consistent startup, eliminating manual configuration complexities. + +{% hint style="info" %} +The following is an example on how to install Docker on a Ubuntu machine. If you have a different OS, please check the official guide on how to install Docker on your system [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/) +{% endhint %} + +1. Set up Docker's apt repository: + +```bash + # Add Docker's official GPG key: + sudo apt-get update + sudo apt-get install ca-certificates curl + sudo install -m 0755 -d /etc/apt/keyrings + sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc + sudo chmod a+r /etc/apt/keyrings/docker.asc + + # Add the repository to Apt sources: + echo + \"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ + $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + + sudo apt-get update +``` + +2. Install Docker Community Edition: + +```bash +sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin +``` + +3. Check if Docker is running: + +
sudo systemctl status docker
+
+ +4. Add your user to the Docker group: + +```bash +sudo usermod -aG docker $USER +``` + +5. To apply the new group membership, log out of the server and back in, or type the following: + +```bash +su - ${USER} +``` diff --git a/docs/developer-guide/setup-node.js-with-nvm.md b/docs/developer-guide/setup-node.js-with-nvm.md new file mode 100644 index 00000000..f753d5e8 --- /dev/null +++ b/docs/developer-guide/setup-node.js-with-nvm.md @@ -0,0 +1,43 @@ +# Setup Node.js with NVM + +Node.js is a pre-requisite to run both the Hexabot CLI and a Hexabot project since the API is built on NestJS. Using [NVM](https://github.com/nvm-sh/nvm) (Node Version Manager) simplifies managing the required Node.js version. When creating a new Hexabot project, the structure includes source folders like **extensions** to add custom plugins, helpers and channels, making Node.js essential tool for smooth development and customization. + +If you are new to NVM, please follow these steps to install: + +1. Update the system: + +```bash +sudo apt update +``` + +2. Install NVM: + +```bash +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash +``` + +Close and reopen your terminal to start using nvm or run the following to use it now: + +```bash +export NVM_DIR="$HOME/.nvm" +[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm +[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion +``` + +3. Verify the NVM installation: + +```bash +nvm --version +``` + +4. Install Node.js version 18.17.0 or higher : + +```bash +nvm install 18.17.0 +``` + +5. Check default Node.js version: + +```bash +node --version +``` diff --git a/docs/faq/how-can-i-deploy-my-hexabot-project.md b/docs/faq/how-can-i-deploy-my-hexabot-project.md new file mode 100644 index 00000000..111bc972 --- /dev/null +++ b/docs/faq/how-can-i-deploy-my-hexabot-project.md @@ -0,0 +1,221 @@ +# How can I deploy my Hexabot Project? + +### Introduction + +This documentation explains how to deploy your Hexabot project using two different methods: + +1. [**Using Nginx as a service and Certbot for SSL.**](how-can-i-deploy-my-hexabot-project.md#using-nginx-as-a-service-and-certbot-for-ssl) +2. [**Using Dockerized Nginx and Certbot services.**](how-can-i-deploy-my-hexabot-project.md#using-dockerized-nginx-and-certbot-services) + +### Pre-requisites + +Make sure you have access to a server running a Linux distribution with SSH enabled. The following documentation is based on an Ubuntu distribution, so you may need to adapt the steps according to your specific operating system. + +*** + +### **Using Nginx as a service and Certbot for SSL** + +#### Step 1: Install Docker + +{% content-ref url="../developer-guide/setting-up-docker-for-development-and-production.md" %} +[setting-up-docker-for-development-and-production.md](../developer-guide/setting-up-docker-for-development-and-production.md) +{% endcontent-ref %} + +#### Step 2: Install NPM + +{% content-ref url="../developer-guide/setup-node.js-with-nvm.md" %} +[setup-node.js-with-nvm.md](../developer-guide/setup-node.js-with-nvm.md) +{% endcontent-ref %} + +#### Step 3: Setup Hexabot project + +1. Install the Hexabot CLI: + +```bash +npm install -g hexabot-cli +``` + +2. Create new project: + +```bash + hexabot create my-chatbot + cd my-chatbot/ +``` + + Or clone an existing project of yours: + +```bash + git clone git@github.com:YOUR_ORG/my-chatbot.git + cd my-chatbot/ +``` + +3. Environment Setup: + +To configure the environment variables, use the following command: + +```bash +hexabot init +``` + +This command will copy the `.env.example` file to `.env` in the `./docker` directory if the file does not already exist + +4. Update your `.env` file for production, especially the following ones: + +
Variable NameExample ValueEnv variable description
NODE_ENVprodEnvironment Mode
APP_DOMAINmychatbot.aiApplication Domain Name
API_ORIGINhttps://mychatbot.ai/apiThe api endpoint will be used to communicate with the backend
FRONTEND_ORIGINhttps://mychatbot.aiThe origins that will be accepted by the API
JWT_SECRET346998ba1f171f107433Secret to encrypt jwt token
SESSION_SECRET27feaf70d2c78892bf49Secret to encrypt session token
HTTPS_ENABLEDtrueHttps setting
INVITATION_JWT_SECRET51c8ea00d82eb10ee226Secret to encrypt invitation token
PASSWORD_RESET_JWT_SECRET5ee97916017176d1ca6cSecret to encrypt reset password token
CONFIRM_ACCOUNT_SECRET80f74dce70e5385bf80bSecret to encrypt confirm account token
MONGO_USERmy_mongo_usernameMongodb username
MONGO_PASSWORDmy_mongo_passwordMongodb password
AUTH_TOKENc97643c1c1e5e9dc5745Secret to encrypt NLU token
NEXT_PUBLIC_API_ORIGINhttps://mychatbot.ai/apiNextjs api endpoint
+ +Note that you can also adjust the default token expirations durations as needed. + +{% hint style="info" %} +To be able to send email you will need to configure SMTP. Learn how to configure SMTP environment variables by following our detailed [SMTP setup guide](../developer-guide/smtp-configuration-and-emails.md)[.](../developer-guide/smtp-configuration-and-emails.md) +{% endhint %} + +5. Run your Hexabot project in production mode: + +```bash +hexabot start +# Or include additional services you may want to use +hexabot start --services nlu,ollama,influxdb +``` + +Note that this command will start all the services (api, frontend, mongodb, ...) as Docker containers. + +#### Step 4: Install Nginx + +Deploying an Hexabot project on production requires you to setup a HTTP Web Server like Apache2, HAProxy or Nginx to secure communications using SSL, establish access per domain name, and a lot of other capabilities such as rate limiting for example to help protect against abuse and prevent server overload. In this guide, we will walk you through a typical HTTP Web Server setup using Nginx and Certbot for SSL certificate generation. + +1. Update the system: + +```bash +sudo apt update +``` + +2. Install Nginx: + +```bash +sudo apt install nginx +``` + +3. Verify the Nginx installation: + +```bash +nginx -v +``` + +4. Start Nginx: + +```bash +sudo systemctl start nginx +``` + +5. Check the Nginx status: + +```bash +sudo systemctl status nginx +``` + +*** + +#### Step 5: Configure Nginx + +1. Replace Nginx server configuration with the following : **/etc/nginx/sites-available/default**. + +````bash +``` +server { + listen 80; + server_name mychatbot.ai; # You will need to update this to use your own domain + server_tokens off; + client_max_body_size 20M; + + location / { + proxy_set_header X-Forwarded-Proto https; + proxy_set_header X-Url-Scheme $scheme; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header Host $http_host; + proxy_redirect off; + proxy_pass http://localhost:8080; # Make sure to use the port configured in .env file + } + + location /api/ { + rewrite ^/api/?(.*)$ /$1 break; + proxy_pass http://localhost:4000; # Make sure to use the port configured in .env file + proxy_http_version 1.1; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Server $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; + proxy_set_header Host $http_host; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "Upgrade"; + proxy_set_header X-NginX-Proxy false; + proxy_pass_request_headers on; + } + + location ~* \.io { + rewrite ^/api/?(.*)$ /$1 break; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header Host $http_host; + proxy_set_header X-NginX-Proxy false; + + proxy_pass http://localhost:4000; # Make sure to use the port configured in .env file + proxy_redirect off; + + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + } +} +``` +```` + +#### Step6: Generate SSL certificate using Certbot + +1. Install Certbot: + +```bash +sudo apt install certbot python3-certbot-nginx +``` + +2. Obtain an SSL certificate: + +```bash +sudo certbot --nginx +``` + +3. (Optional) Automate SSL renewal: + +```bash +sudo crontab -e +``` + +4. Add the following line: + +``` +0 12 * * * certbot renew --quiet +``` + +**Step 7: Reload Nginx with new configuration** + +1. Test configuration syntax: + +```bash +sudo nginx -t +``` + +If you get an error please make sure you don't have any syntax error in `/etc/nginx/sites-available/default` + +2. Reload Nginx with new configuration: + +```bash +sudo systemctl reload nginx +``` + +*** + +Access your domain using HTTPS (eg. https://mychatbot.ai) to check if you have successfully deployed your Hexabot project using Nginx! 🚀🎉. Feel free to ask for support from the community on our Discord channel. + +## **Using Dockerized Nginx and Certbot services** : + +The second deployment method, where everything is Dockerized, is still WIP. diff --git a/docs/quickstart/installation.md b/docs/quickstart/installation.md index 26b84a8e..c6d392d0 100644 --- a/docs/quickstart/installation.md +++ b/docs/quickstart/installation.md @@ -8,21 +8,17 @@ icon: laptop-arrow-down To ensure Hexabot runs smoothly, you'll need the following: -* **Docker:** We recommend using Docker to start the app since multiple services are required (MongoDB, Nginx, etc.). All the necessary Docker Compose files are located in the docker folder. +* **Docker:** We recommend using Docker to start the app since multiple services are required (MongoDB, Nginx, etc.). All the necessary Docker Compose files are located in the **docker** folder. -{% hint style="info" %} -Check Docker official guide on how to install Docker on your system [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/) -{% endhint %} +{% content-ref url="../developer-guide/setting-up-docker-for-development-and-production.md" %} +[setting-up-docker-for-development-and-production.md](../developer-guide/setting-up-docker-for-development-and-production.md) +{% endcontent-ref %} -* **Node.js:** For development purposes, ensure you have Node.js >= v18.17.0 installed. We recommend using nvm (Node Version Manager) to easily manage and update your Node.js versions. +* **Node.js:** For development purposes, ensure you have Node.js >= v18.17.0 installed. We recommend using nvm (Node Version Manager) to easily manage and update your Node.js versions. -{% hint style="info" %} -To **install** or **update** nvm, you should run the [install script](https://github.com/nvm-sh/nvm/blob/v0.40.1/install.sh). To do that, you may either download and run the script manually, or use the following cURL or Wget command: - -_curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash_ - -Check NVM official documentation for more details :[https://github.com/nvm-sh/nvm?tab=readme-ov-file#node-version-manager---](https://github.com/nvm-sh/nvm?tab=readme-ov-file#node-version-manager---) -{% endhint %} +{% content-ref url="../developer-guide/setup-node.js-with-nvm.md" %} +[setup-node.js-with-nvm.md](../developer-guide/setup-node.js-with-nvm.md) +{% endcontent-ref %}
@@ -43,25 +39,25 @@ Learn more : [https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-contai 1. **Install Hexabot CLI globally to have easy access to its commands:** ``` -$ npm install -g hexabot-cli +npm install -g hexabot-cli ``` 2. **Create a new project**: ``` -$ hexabot create my-chatbot +hexabot create my-chatbot ``` 3. **Navigate to your project folder** ``` -$ cd my-chatbot/ +cd my-chatbot/ ``` 4. **Install dependencies**: ``` -$ npm i +npm i ``` 5. **Environment Setup:** @@ -69,7 +65,7 @@ $ npm i To configure the environment variables, use the following command: ``` -$ hexabot init +hexabot init ``` This will copy the `.env.example` file to `.env` in the `./docker` directory if the file does not already exist. @@ -77,7 +73,7 @@ This will copy the `.env.example` file to `.env` in the `./docker` directory if 6. **Run in development mode:** Once your environment is set up, you can start the app. Use the following command: ``` -$ hexabot dev --services nlu,ollama +hexabot dev --services nlu,ollama ``` {% hint style="info" %}