Andreas/LibreChat
1
0
Fork 0
mirror of https://github.com/danny-avila/LibreChat.git synced 2025-12-16 16:30:15 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

📝 docs: additions to deployment guide (#2001)

Browse source 
* docs: add intro to deployment guide

* doc: update intro

* doc: Add NGINX deployment guide and update reverse proxy link

* doc:: add  reverse proxy pages and weight for the pages

* doc: Update NGINX configuration file

* doc: imporve new doc

* Doc: fix file names

* doc: fix references names + improve the introduction with chatgpt :-)

* doc: update introduction  guide headings
This commit is contained in:
Ido Ophir 2024-03-07 15:10:44 +02:00 • committed by GitHub
parent ab66747e97
commit 11bca134e7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 438 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

30
docs/deployment/index.md
View file

@ -4,16 +4,24 @@ description: 🌐 Step-by-step guides on how to deploy LibreChat on various clou
weight: 3
---
[Introduction)](introduction.md)
# Deployment
* 🌊 [DigitalOcean (✨Recommended)](digitalocean.md)
* 🤗 [HuggingFace](huggingface.md)
* 🐧 [Linode](linode.md)
* ☁️ [Cloudflare](cloudflare.md)
* ⚡ [Azure](azure-terraform.md)
* 🪨 [Ngrok](ngrok.md)
* ⏹️ [Render](render.md)
* 🔎 [Meilisearch in Render](meilisearch_in_render.md)
* 🏗️ [Hetzner](hetzner_ubuntu.md)
* 🌈 [Heroku](heroku.md)
* 🦓 [Zeabur](zeabur.md)
- 🌊 [DigitalOcean (✨Recommended)](digitalocean.md)
- 🤗 [HuggingFace](huggingface.md)
- 🐧 [Linode](linode.md)
- ☁️ [Cloudflare](cloudflare.md)
- ⚡ [Azure](azure-terraform.md)
- 🪨 [Ngrok](ngrok.md)
- ⏹️ [Render](render.md)
- 🔎 [Meilisearch in Render](meilisearch_in_render.md)
- 🏗️ [Hetzner](hetzner_ubuntu.md)
- 🌈 [Heroku](heroku.md)
- 🦓 [Zeabur](zeabur.md)
# Security
## Deploying with HTTPS and NGINX
- [Reverse Proxy Guide)](nginx.md)

110
docs/deployment/introduction.md Normal file
View file

@ -0,0 +1,110 @@
---
title: Deployment
description: 🌐 starting point for deploying the LibreChat application across various environments and platforms.
weight: -20
---
# Comprehensive Deployment Guide for LibreChat
Ahoy, brave digital explorers and savvy code wranglers! Welcome to the fantastical journey of deploying LibreChat, where magic meets machinery, and dreams become digital reality. Strap on your virtual boots and hoist the sails; an adventure awaits in the boundless realms of the cloud!
That is to say... Here, you'll learn how to seamlessly launch LibreChat across diverse environments tailored to your requirements.
## Cloud Vendor Integration and Configuration
The integration level with cloud vendors varies: from platforms enabling single-click LibreChat deployments like [Zeabur](zeabur.md), through platforms leveraging Infrastructure as Code tools such as [Azure with Terraform](azure-terraform.md), to more traditional VM setups requiring manual configuration, exemplified by [DigitalOcean](digitalocean.md), [Linode](linode.md), and [Hetzner](hetzner_ubuntu.md).
## Essential Security Considerations
Venturing into the global digital wilderness unveils untold dangers: marauding cyber-dragons and shadowy data thieves. Arm yourself with the enchanted shield of HTTPS, and conjure the SSL wards to protect your digital dominion from the dark sorcery of data breaches.
When deploying applications globally, it’s paramount to safeguard your setup. Key considerations include enabling HTTPS to encrypt data in transit, understanding the global accessibility implications, and ensuring secure configuration. So if you select Iaas or Tunnel service for your deployment, you will probably need reverse proxy such as Nginx. don't know what is nginx and what it is used for? See [Nginx Guide)](nginx.md)
# Choosing the Cloud vendor (e.g. platform)
Choosing a cloud vendor, for the "real deployment" is crucial as it impacts cost, performance, security, and scalability. You should consider factors such as data center locations, compliance with industry standards, compatibility with existing tools, and customer support.
There is a lot of options that differ in many aspects. In this section you can find some options that the team and the community uses that can help you in your first deployment.
Once you gain more knowledge on your application usage and audience you will probably be in a position to decide what cloud vendor fits you the best for the long run.
As said the cloud providers / platforms differ in many aspects. For our purpose we can assume that in our context your main concerns is will ease of use, security and (initial) cost. In case that you have more concerns like scaling, previous experience with any of the platforms or any other specific feature then you probably know better what platform fit's you and you can jump directly to the information that you are seeking without following any specific guide.
## Deployment "options" & Specific guides overview
The list goes from the more effort more controlled, to the lease effort less controlled.
Generally speaking Iaas will consume more time and expertise then Iac, Iac more the PaaS etc.
### 1. Iaas - VM + Docker compose installation Guide
IaaS (Infrastructure as a Service): Provides fundamental computing resources like virtual servers, network, and storage on a pay-per-use basis.
- [DigitalOcean](digitalocean.md): User-friendly interface with predictable pricing.
- [Linode](linode.md): Renowned for excellent customer support and straightforward pricing.
- [Hetzner](hetzner_ubuntu.md): Prioritizes privacy and cost-effectiveness, ideal for European-centric deployments.
#### For Iaas we recommend Docker Compose
**Why Docker Compose?** We advocate the use of Docker Compose to ensure a seamless and uniform deployment experience across all platforms. This guide elucidates each step, ensuring clarity and ease of understanding throughout the deployment lifecycle.
##### Beware there are 2 versions of Docker Compose in the repo
Beware that LibraChat has to docker compose versions
1. **Development Oriented docker compose `docker-compose.yml`**
2. **Deployment Oriented docker compose `deploy-compose.yml`**
The main difference is that `deploy-compose.yml` includes nginx in the docker (and therefore it's nginx configuration is docker internal).
don't know what is nginx and what it is used for? See [Reverse Proxy Guide)](nginx.md)
### 2. IaC - Terraform
IaC ("Infrastructure as Code"): managing and provisioning computing infrastructures through machine-readable definition files, rather than physical hardware configuration or interactive configuration tools. This practice supports reproducibility, disposability, and scalability in modern cloud environments.
- [Azure](azure-terraform.md): Comprehensive services suitable for enterprise-level deployments
**Important Note**
- Digital Ocean, Linode, Hetzner also support IaC. But currently we don't have a dedicated guide for this.
So you are welcome to try it with the Azure Guide and help us update it to make it Terraform IaC guide for all platforms.
### 3. PaaS (Platform as a Service)
PaaS (Platform as a Service): Offers a development and deployment environment in the cloud, with resources enabling users to deliver simple cloud-based apps to sophisticated enterprise applications.
- [Hugging Face](huggingface.md): Tailored for machine learning and NLP projects.
- [Render](render.md): Simplifies deployments with integrated CI/CD pipelines.
- [Heroku](heroku.md): Optimal for startups and quick deployment scenarios.
### 4. Feature PaaS
- [Meilisearch in Render](meilisearch_in_render.md): Quick setup guide for integrating the fast search engine with LibreChat on Render.
### 5. One Click Deployment of PaaS
- [Zeabur](zeabur.md): Pioneering effortless one-click deployment solutions.
## Other Categories
### 1. Tunneling Services
Tunneling services allow you to expose a local development server to the internet, making it accessible via a public URL. This is particularly useful for sharing work, testing, and integrating with third-party services. It allows you to deploy your development computer for testing or for on-prem installation.
- [Ngrok](ngrok.md): Facilitates secure local tunneling to the internet.
- [Cloudflare](cloudflare.md): Enhances web performance and security.
### 2. DNS Service
- Cloudflare Domain Setup part of the Cloudflare guide (we should make it DNS service and put Cloudflare as the provider ...)
# The Voyage Commences
Before you chart your course through the cloud archipelago, ponder your heart's desires: the serenity of ease, the bastion of security, or the treasure trove of affordability. Your chosen path will illuminate the way to your destined cloud realm.
# Embarkation on the Legendary Deployment
With a quill dipped in starlight, mark your chosen path and embark upon the legendary deployment of LibreChat. May the digital winds be ever in your favor, as you navigate the binary seas and uncover the treasures of the cloud.
Remember, our community is here to assist. Should you encounter challenges or have queries, our [Discord channel](https://discord.librechat.ai) and [troubleshooting discussion](https://github.com/danny-avila/LibreChat/discussions/categories/troubleshooting) are excellent resources for support and advice.
Happy deploying!

309
docs/deployment/nginx.md Normal file
View file

@ -0,0 +1,309 @@
---
title: Deployment
description: 🌐 Step-by-step guides on how to deploy LibreChat on various cloud platforms.
weight: 10
---
# Deploying Application in the Cloud with HTTPS and NGINX
This guide covers the essential steps for deploying your LibreChat application in the cloud, securing it with an SSL/TLS certificate for HTTPS, setting up NGINX as a reverse proxy, and configuring your domain.
## Why do I need reverse proxy?
A reverse proxy is a server that sits between clients and the web servers that host actual applications. It forwards client requests to the back-end servers and returns the server's response to the client. Using a reverse proxy in deployment can enhance security, load balancing, and caching. It hides the characteristics and origins of the back-end servers, providing an additional layer of defense against attacks. Additionally, it can distribute traffic among several servers, improving performance and scalability.
## Why Do I need HTTPS?
Implementing HTTPS in your Nginx configuration is vital when deploying an application for several reasons:
Data Security: HTTPS encrypts the data transmitted between the client (user's browser) and the server, protecting sensitive information from being intercepted by third parties. This is particularly important for applications handling personal, financial, or otherwise confidential information.
Authentication: HTTPS provides a mechanism for users to verify that they are communicating with the intended website, reducing the risk of man-in-the-middle attacks, phishing, and other threats where an attacker might impersonate your site.
SEO and Trust: Search engines like Google give preference to HTTPS-enabled websites, potentially improving your site's search ranking. Additionally, browsers display security warnings for sites not using HTTPS, which can erode trust and deter users from using your application.
Regulatory Compliance: For many types of applications, particularly those dealing with personal data, HTTPS may be required to comply with legal standards and regulations, such as GDPR, HIPAA, or PCI-DSS.
By configuring HTTPS in Nginx, you ensure that your application benefits from enhanced security, improved trust and compliance, and better user experience.
## Prerequisites:
1. A cloud server (e.g., AWS, Google Cloud, Azure, Digital Ocean).
2. A registered domain name.
3. Terminal access to your cloud server.
4. Node.js and NPM installed on your server.
## Initial Setup: Pointing Your Domain to Your Website
Before proceeding with certificate acquisition, it's crucial to direct your domain to your cloud server. This step is foundational and must precede SSL certificate setup due to the time DNS records may require to propagate globally. Ensure that this DNS configuration is fully operational before moving forward.
1. **Configure DNS**:
- Log in to your domain registrar's control panel.
- Navigate to DNS settings.
- Create an `A record` pointing your domain to the IP address of your cloud server.
2. **Verify Domain Propagation**:
- It may take some time for DNS changes to propagate.
- You can check the status by pinging your domain: `ping your_domain.com`
Comment: remember to replace `your_domain.com` with your actual domain name.
## Step 1: Obtain a SSL/TLS Certificate
To secure your LibreChat application with HTTPS, you'll need an SSL/TLS certificate. Let's Encrypt offers free certificates:
1. **Install Certbot**:
- For Ubuntu: `sudo apt-get install certbot python3-certbot-nginx`
- For CentOS: `sudo yum install certbot python2-certbot-nginx`
2. **Obtain the Certificate**:
- Run `sudo certbot --nginx` to obtain and install the certificate automatically for NGINX.
- Follow the on-screen instructions. Certbot will ask for information and complete the validation process.
- Once successful, Certbot will store your certificate files.
## Step 2: Set Up NGINX as a Reverse Proxy
NGINX acts as a reverse proxy, forwarding client requests to your LibreChat application.
There are 2 different options for the nginx server, which depends on the method you want to deploy the LibreChat.
### Using the `deploy-compose.yml` Docker Compose (the recommended way)
The `deploy-compose.yml` has already the Nginx app within it. it used the file `client/nginx.conf` for the Nginx configuration.
But here is the problem... using the `sudo certbot --nginx` you extracted the cert to the ... host conf so we will need to duplicate the cert to the dockers to make it work.
### Normal Host based deployment
If you are deploying from the host without dockers you need to install the Nginx on the host, as below. However if you use the docker compose `deploy-compose.yml` - DON'T install Nginx on the host since it will mess within your Nginx within the Docker.
1. **Install NGINX**:
- Ubuntu: `sudo apt-get install nginx`
- CentOS: `sudo yum install nginx`
2. **Start NGINX**:
- Start NGINX: `sudo systemctl start nginx`
- Follow the on-screen instructions. Press Enter for any screen that opens during the process.
- You might be asked to execute `sudo reboot` to restart your server. This will apply any kernel updates and restart your services.
3. **What type of Nginx Configuration I want?**
There are 2 different use cases, each calling for a bit different configuration.
### Configuration without Basic Authentication
#### Use Case
Suitable for production environments or when application has a built-in robust authentication system. Ideal for dynamic user management scenarios.
#### User Perspective
- Seamless access after application login.
- No additional Nginx login required.
#### Administrator Perspective
- No `.htpasswd` maintenance required.
- Focus on application security and SSL certificate management.
#### Configuration Example
This guide assumes the use case of installing without Basic Authentication, so if this is your case, jump over to `Configure NGINX without Basic Authentication` below.
---
### Configuration with Basic Authentication
#### Use Case
Appropriate for smaller environments like staging, internal tools, or additional security layers. Useful if application lacks its own authentication.
#### User Perspective
- Additional login prompt for Nginx access.
- Separate credentials for Nginx and application.
#### Administrator Perspective
- Maintenance of `.htpasswd` file required.
- Extra security layer management.
#### Configuration Example
For example configuration with Basic Authentication see [🌀 Miscellaneous](../install/configuration/misc.md)
---
### Summary of Differences
- **User Experience**: Direct application access vs. additional Nginx login.
- **Administration**: Less overhead vs. `.htpasswd` management.
- **Security**: Application security vs. added Nginx layer.
4. **Option A: Configure NGINX without Basic Authentication using Docker Compose with SSL**:
For the time being - this requires a bit of an effort...
The exact details might change in the future so I will try to give here the basics, and I invite you to improve this section.
You need to change 2 files
1. client/nginx.conf
Here is an example (it is not one to one with the current code base - TODO: Fix the code and this in the future)
```
# Secure default configuration with SSL enabled
# Based on Mozilla SSL Configuration Generator and provided configuration
# Block to handle direct IP access and undefined server names
server {
listen 80 default_server;
listen [::]:80 default_server;
listen 443 ssl http2 default_server;
listen [::]:443 ssl http2 default_server;
ssl_certificate /etc/letsencrypt/live/<put.here.your.domain.name>/fullchain.pem; # Use your cert paths
ssl_certificate_key /etc/letsencrypt/live/<put.here.your.domain.name>/privkey.pem; # Use your cert paths
server_name _; # Catch all other domain requests or direct IP access
return 403; # Forbidden or use 'return 444;' to drop the request immediately without response
}
# Redirect HTTP to HTTPS for your domain
server {
listen 80;
listen [::]:80;
server_name <put.here.your.domain.name>; # Your domain
# Redirect all HTTP traffic to HTTPS
location / {
return 301 https://$host$request_uri;
}
}
# HTTPS server configuration for your domain
server {
listen 443 ssl http2;
listen [::]:443 ssl http2; # IPv6 support
server_name <put.here.your.domain.name>; # Your domain
# SSL Certificate settings
ssl_certificate /etc/letsencrypt/live/<put.here.your.domain.name>/fullchain.pem; # managed by Certbot
ssl_certificate_key /etc/letsencrypt/live/<put.here.your.domain.name>/privkey.pem; # managed by Certbot
# Recommended SSL settings
include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot or replace with Mozilla's recommended settings
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot or Mozilla's recommended dhparam
# Increase the client_max_body_size to allow larger file uploads
client_max_body_size 25M;
# Proxy settings for the API and front-end
location /api {
proxy_pass http://api:3080/api; # or use http://api:3080/api if 'api' is a service name in Docker
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
location / {
proxy_pass http://api:3080; # or use http://api:3080 if 'api' is a service name in Docker
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
```
2. deploy-compose.yml
go to the client section
```yaml
client:
build:
context: .
dockerfile: Dockerfile.multi
target: prod-stage
container_name: LibreChat-NGINX
ports:
- 80:80
- 443:443
depends_on:
- api
restart: always
volumes:
- ./client/nginx.conf:/etc/nginx/conf.d/default.conf
```
and add to the volumes reference to the certificates that `sudo certbot --nginx` added to your **host** configuration
e.g.
```yaml
client:
build:
context: .
dockerfile: Dockerfile.multi
target: prod-stage
container_name: LibreChat-NGINX
ports:
- 80:80
- 443:443
depends_on:
- api
restart: always
volumes:
- ./client/nginx.conf:/etc/nginx/conf.d/default.conf
- /etc/letsencrypt/live/<put.here.your.domain.name>:/etc/letsencrypt/live/<put.here.your.domain.name>
- /etc/letsencrypt/archive/<put.here.your.domain.name>:/etc/letsencrypt/archive/<put.here.your.domain.name>
- /etc/letsencrypt/options-ssl-nginx.conf:/etc/letsencrypt/options-ssl-nginx.conf
- /etc/letsencrypt/ssl-dhparams.pem:/etc/letsencrypt/ssl-dhparams.pem
```
after you changed them you should follow the instruction from [Part V: Editing the NGINX file](digitalocean.md#part-v-editing-the-nginx-file-for-custom-domains-and-advanced-configs)\*\*
in order to update the git and deploy from a rebased branch.
[TBA: TO ADD HERE a simple explanation based on that explanation]
3. **Option B: Configure NGINX without Basic Authentication on the host**:
- Open the LibreChat NGINX configuration file: `sudo nano /etc/nginx/sites-available/default`
- Replace the file content with the following, ensuring to replace `your_domain.com` with your domain and `app_port` with your application's port:
```
server {
listen 80;
server_name your_domain.com;
location / {
proxy_pass http://localhost:3080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
```
6. **Check NGINX Configuration & Restart**:
- Validate the configuration: `sudo nginx -t`
- Reload NGINX: `sudo systemctl reload nginx`
## Step 3: Run the application
1. Navigate to your application's directory:
```bash
cd LibreChat # Replace 'LibreChat' with your actual application directory.
```
2. Start your application using Docker Compose:
```bash
sudo docker-compose -f ./deploy-compose.yml up -d
```