Andreas/LibreChat
1
0
Fork 0
mirror of https://github.com/danny-avila/LibreChat.git synced 2025-09-21 21:50:49 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs: fix/update (#525)

Browse source 
* Update README.md

* Update Hetzner doc

* Update heroku.md

* Update README.md

* Create breaking_changes.md

* Update README.md

* Update breaking_changes.md
This commit is contained in:
Fuegovic 2023-06-16 00:02:29 -04:00 • committed by GitHub
parent 3634d8691a
commit 550e566097
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 103 additions and 66 deletions
Download patch file Download diff file Expand all files Collapse all files

29
README.md
View file

@ -36,33 +36,14 @@ https://github.com/danny-avila/LibreChat/assets/110412045/c1eb0c0f-41f6-4335-b98
- Plugins now available (including web access, image generation and more)
---
# ⚠️ **Breaking Changes** ⚠️
Note: These changes only apply to users who are updating from a previous version of the app.
- We have simplified the configuration process by using a single `.env` file in the root folder instead of separate `/api/.env` and `/client/.env` files.
- If you had installed a previous version, you can run `npm run upgrade` to automatically copy the content of both files to the new `.env` file and backup the old ones in the root dir.
- If you are installing the project for the first time, it's recommend you run the installation script `npm run install` to guide your local setup (otherwise continue to use docker)
- The docker-compose file had some change. Review the [new docker instructions](docs\install\docker_install.md) to make sure you are setup properly. This is still the simplest and most effective method.
- The upgrade script requires both `/api/.env` and `/client/.env` files to run properly. If you get an error about a missing client env file, just rename the `/client/.env.example` file to `/client/.env` and run the script again.
- We have renamed the `OPENAI_KEY` variable to `OPENAI_API_KEY` to match the official documentation. The upgrade script should do this automatically for you, but please double-check that your key is correct in the new `.env` file.
- After running the upgrade script, the `OPENAI_API_KEY` variable might be placed in a different section in the new `.env` file than before. This does not affect the functionality of the app, but if you want to keep it organized, you can look for it near the bottom of the file and move it to its usual section.
##
- For enhanced security, we are now asking for crypto keys for securely storing credentials in the `.env` file. Crypto keys are used to encrypt and decrypt sensitive data such as passwords and access keys. If you don't set them, the app will crash on startup.
- You need to fill the following variables in the `.env` file with 32-byte (64 characters in hex) or 16-byte (32 characters in hex) values:
- `CREDS_KEY` (32-byte)
- `CREDS_IV` (16-byte)
- `JWT_SECRET` (32-byte, optional but recommended)
- You can use this replit to generate some crypto keys quickly: https://replit.com/@daavila/crypto#index.js
- Make sure you keep your crypto keys safe and don't share them with anyone.
We apologize for any inconvenience caused by these changes. We hope you enjoy the new and improved version of our app!
## ⚠️ [Breaking Changes as of v0.5.0](docs/general_info/breaking_changes.md#v050) ⚠️
**Please read this before updating from a previous version**
---
## Changelog
- Keep up with the latest updates by visiting the releases page - [Releases](https://github.com/danny-avila/LibreChat/releases)
Keep up with the latest updates by visiting the releases page - [Releases](https://github.com/danny-avila/LibreChat/releases)
---
@ -71,7 +52,7 @@ We apologize for any inconvenience caused by these changes. We hope you enjoy th
<details open>
<summary><strong>Getting Started</strong></summary>
* [Docker Install](/docs/install/docker_install.md)
* [Docker Install](docs/install/docker_install.md)
* [Linux Install](docs/install/linux_install.md)
* [Mac Install](docs/install/mac_install.md)
* [Windows Install](docs/install/windows_install.md)
@ -105,7 +86,7 @@ We apologize for any inconvenience caused by these changes. We hope you enjoy th
<details>
<summary><strong>Cloud Deployment</strong></summary>
* [Hetzner](docs/deployment/HetznerUbuntuSetup.md)
* [Hetzner](docs/deployment/hetzner_ubuntu.md)
* [Heroku](docs/deployment/heroku.md)
</details>

48
docs/deployment/heroku.md
View file

@ -1,6 +1,6 @@
# Heroku Deployment
- To run LibreChat on a server, you can use cloud hosting platforms like Heroku, DigitalOcean, or AWS. In this response, I'll provide instructions for deploying the project on Heroku. Other platforms will have slightly different deployment processes.
*To run LibreChat on a server, you can use cloud hosting platforms like Heroku, DigitalOcean, or AWS. In this response, I'll provide instructions for deploying the project on Heroku. Other platforms will have slightly different deployment processes.*
Heroku only supports running a single process within a Docker container. The Dockerfile for this project has two different processes - one is for serving your Node API and the other for serving your client with Nginx. In the context of Heroku, these should be considered two separate apps.
@ -11,7 +11,7 @@ If you want to deploy both these services to Heroku, you will need to create two
Here are the steps to deploy on Heroku:
1. **Create a new Dockerfile for your API named `Dockerfile-api`:**
## 1. **Create a new Dockerfile for your API named `Dockerfile-api`:**
```
# Base node image
@ -31,7 +31,7 @@ ENV HOST=0.0.0.0
CMD ["npm", "start"]
```
2. **Create a new Dockerfile for your Client named `Dockerfile-client`:**
## 2. **Create a new Dockerfile for your Client named `Dockerfile-client`:**
```
# Base node image
@ -57,53 +57,53 @@ COPY client/nginx.conf /etc/nginx/conf.d/default.conf
ENTRYPOINT ["nginx", "-g", "daemon off;"]
```
3. **Build and deploy your apps using the Heroku CLI:**
## 3. **Build and deploy your apps using the Heroku CLI:**
Login to Heroku:
### Login to Heroku:
```
heroku login
```
Login to the Heroku Container Registry:
### Login to the Heroku Container Registry:
```
heroku container:login
```
Create a Heroku app for your API:
### Create a Heroku app for your API:
```
heroku create your-api-app-name
```
Set environment variables for your API app:
### Set environment variables for your API app:
```
heroku config:set HOST=0.0.0.0 --app your-api-app-name
```
Build and deploy your API app:
### Build and deploy your API app:
```
heroku container:push web --app your-api-app-name -f Dockerfile-api
heroku container:release web --app your-api-app-name
```
Create a Heroku app for your client:
### Create a Heroku app for your client:
```
heroku create your-client-app-name
```
Build and deploy your client app:
### Build and deploy your client app:
```
heroku container:push web --app your-client-app-name -f Dockerfile-client
heroku container:release web --app your-client-app-name
```
4. **Open your apps in a web browser:**
## 4. **Open your apps in a web browser:**
```
heroku open --app your-api-app-name
@ -112,16 +112,17 @@ heroku open --app your-client-app-name
Remember to replace `your-api-app-name` and `your-client-app-name` with the actual names of your Heroku apps.
---
⚠️ If you have issues, see this discussion first: https://github.com/danny-avila/LibreChat/discussions/339
**Using Heroku Dashboard:**
## Using Heroku Dashboard:
- Open the app: After the deployment is complete, you can open the app in your browser by running heroku open or by visiting the app's URL.
*NOTE: If the heroku docker image process still needs an external mongodb/meilisearch, here are the instructions for setting up MongoDB Atlas and deploying MeiliSearch on Heroku:*
**Setting up MongoDB Atlas:
## Setting up MongoDB Atlas:
Sign up for a MongoDB Atlas account: If you don't have an account, sign up at https://www.mongodb.com/cloud/atlas/signup.
@ -133,32 +134,33 @@ Configure network access: Go to the "Network Access" section and add a new IP ad
Get the connection string: Once the cluster is created, click the "Connect" button. Select the "Connect your application" option and choose "Node.js" as the driver. Copy the connection string and replace and with the credentials you created earlier.
**Deploying MeiliSearch on Heroku:
## Deploying MeiliSearch on Heroku:
Install the Heroku CLI: If you haven't already, download and install the Heroku CLI from https://devcenter.heroku.com/articles/heroku-cli.
Login to Heroku: Open Terminal and run heroku login. Follow the instructions to log in to your Heroku account.
Create a new Heroku app for MeiliSearch:
## Create a new Heroku app for MeiliSearch:
```
heroku create your-meilisearch-app-name
```
Replace your-meilisearch-app-name with a unique name for your MeiliSearch app.
Set the buildpack:
### Set the buildpack:
```
heroku buildpacks:set meilisearch/meilisearch-cloud-buildpack --app your-meilisearch-app-name
```
Set the master key for MeiliSearch:
### Set the master key for MeiliSearch:
```
heroku config:set MEILI_MASTER_KEY=your-master-key --app your-meilisearch-app-name
```
Replace your-master-key with a secure master key.
### Replace your-master-key with a secure master key.
Deploy MeiliSearch:
### Deploy MeiliSearch:
```
git init
@ -167,9 +169,9 @@ git add .
git commit -m "Initial commit"
git push heroku master
```
Get the MeiliSearch URL: After deployment, you can find the MeiliSearch URL by visiting your app's settings page in the Heroku Dashboard. The URL will be displayed under the "Domains" section.
### Get the MeiliSearch URL: After deployment, you can find the MeiliSearch URL by visiting your app's settings page in the Heroku Dashboard. The URL will be displayed under the "Domains" section.
**Update environment variables in LibreChat:**
## Update environment variables in LibreChat:
- Now that you have your MongoDB Atlas connection string and MeiliSearch URL, update the following environment variables in your Heroku app for LibreChat:
@ -185,6 +187,8 @@ heroku config:set KEY_NAME=KEY_VALUE --app your-app-name
```
- Replace KEY_NAME and KEY_VALUE with the appropriate key names and values from your .env file. Repeat this command for each environment variable.
### Note: If you're still having trouble, before creating a new issue, please search for similar ones on our [#issues thread on our discord](https://discord.gg/weqZFtD9C4) or our [troubleshooting discussion](https://github.com/danny-avila/LibreChat/discussions/new?category=troubleshooting) on our Discussions page. If you don't find a relevant issue, feel free to create a new one and provide as much detail as possible.

46
docs/deployment/HetznerUbuntuSetup.md → docs/deployment/hetzner_ubuntu.md
View file

@ -1,26 +1,27 @@
# Hetzner Ubuntu Setup
*These instructions are designed for someone starting from scratch for a Ubuntu Installation. You can skip to any point that is useful for you.*
# Starting from Zero:
## Starting from Zero:
1. Login to Hetzner Cloud Console (https://console.hetzner.cloud/projects) and Create a new Ubuntu 20 Project with 4GB Ram. Do not worry about SSH keys *yet*.
### 1. Login to Hetzner Cloud Console (https://console.hetzner.cloud/projects) and Create a new Ubuntu 20 Project with 4GB Ram. Do not worry about SSH keys *yet*.
Hetzner will email you the root password.
2. Once you have that, you can login with any SSH terminal with:
### 2. Once you have that, you can login with any SSH terminal with:
```
ssh root@<yourserverip>
```
3. Once you have logged in, immediately create a new, nonroot user:
### 3. Once you have logged in, immediately create a new, non-root user:
```
adduser <yourusername>
usermod -aG sudo <yourusername>
```
4. Make sure you have done this correctly by double-checking you have sudo permissions:
### 4. Make sure you have done this correctly by double-checking you have sudo permissions:
```
getent group sudo | cut -d: -f4
@ -28,7 +29,7 @@ getent group sudo | cut -d: -f4
Now, quit the terminal connection.
5. Create a local ssh key:
### 5. Create a local ssh key:
```
ssh-keygen -t ed25519
@ -46,13 +47,13 @@ ssh <yourusername>@<yourserverip>
When you login, now and going forward, it will ask you for the password for your ssh key now, not your user password. Sudo commands will always want your user password.
6. Add SSH to the universal server firewall and activate it.
### 6. Add SSH to the universal server firewall and activate it.
- Run `sudo ufw allow OpenSSH`
- Run `sudo ufw enable`
7. Then, we need to install docker, update the system packages, and reboot the server:
### 7. Then, we need to install docker, update the system packages, and reboot the server:
```
sudo apt install docker
sudo apt install docker-compose
@ -61,21 +62,24 @@ sudo apt upgrade
sudo reboot
```
Ok, now that you have set up the SERVER, you will need to get all your tokens/apis/etc in order:
**Ok, now that you have set up the SERVER, you will need to get all your tokens/apis/etc in order:**
---
# PreReqs:
## Tokens/Apis/etc:
- Make sure you have all the needed variables for the following before moving forward
## [Get Your API keys and Tokens](../install/apis_and_tokens.md) (Required)
### [Get Your API keys and Tokens](../install/apis_and_tokens.md) (Required)
- You must set up at least one of these tokens or APIs to run the app.
## [User/Auth System](../features/user_auth_system.md) (Optional)
### [User/Auth System](../features/user_auth_system.md) (Optional)
- How to set up the user/auth system and Google login.
## [Plugins](../features/plugins/introduction.md)
### [Plugins](../features/plugins/introduction.md)
- Optional plugins available to enhance the application.
# Using Docker to Install the Service
---
1. **Recommended: [Docker Install](../install/docker_install.md)**
## Using Docker to Install the Service
### 1. **Recommended: [Docker Install](../install/docker_install.md)**
From the *server* commandline (as your user, not root):
```
@ -93,13 +97,13 @@ nano docker-compose.yml
VITE_SHOW_GOOGLE_LOGIN_OPTION: 'false' # default, change to true if you want to show google login
```
2. Create a global environment file and open it up to begin adding the tokens/keys you prepared in the PreReqs section.
### 2. Create a global environment file and open it up to begin adding the tokens/keys you prepared in the PreReqs section.
```
cp .env.example .env
nano .env
```
3. In addition to adding all your api tokens and other tokens that you prepared above, change:
### 3. In addition to adding all your api tokens and other tokens that you prepared above, change:
```
HOST=Localhost
@ -109,7 +113,7 @@ to
HOST=<yourserverip>
```
4. Since you're using docker, you can also change the following:
### 4. Since you're using docker, you can also change the following:
```
SEARCH=true
@ -117,12 +121,12 @@ MEILI_HOST=meilisearch
MEILI_HTTP_ADDR=meilisearch
```
5. After everything file has been updated, run `docker-compose build` then `docker-compose up`
### 5. After everything file has been updated, run `docker-compose build` then `docker-compose up`
**NOTE: You may need to run these commands with sudo permissions.**
# Once the app is running, you can access it at http://yourserverip:3080
## Once the app is running, you can access it at http://yourserverip:3080
It is safe to close the terminal -- the docker app will continue to run.
@ -131,6 +135,8 @@ It is safe to close the terminal -- the docker app will continue to run.
ALLOW_REGISTRATION:False
```
---
### Note: If you're still having trouble, before creating a new issue, please search for similar ones on our [#issues thread on our discord](https://discord.gg/weqZFtD9C4) or our [troubleshooting discussion](https://github.com/danny-avila/LibreChat/discussions/new?category=troubleshooting) on our Discussions page. If you don't find a relevant issue, feel free to create a new one and provide as much detail as possible.
---

46
docs/general_info/breaking_changes.md Normal file
View file

@ -0,0 +1,46 @@
# ⚠️ **Breaking Changes** ⚠️
## v0.5.0
**Note: These changes only apply to users who are updating from a previous version of the app.**
### Summary
- In this version, we have simplified the configuration process, improved the security of your credentials, and updated the docker instructions. 🚀
- Please read the following sections carefully to learn how to upgrade your app and avoid any issues. 🙏
- **Note:** If you're having trouble, before creating a new issue, please search for similar ones on our [#issues thread on our discord](https://discord.gg/weqZFtD9C4) or our [troubleshooting discussion](https://github.com/danny-avila/LibreChat/discussions/new?category=troubleshooting) on our Discussions page. If you don't find a relevant issue, feel free to create a new one and provide as much detail as possible.
---
### Configuration
- We have simplified the configuration process by using a single `.env` file in the root folder instead of separate `/api/.env` and `/client/.env` files.
- We have renamed the `OPENAI_KEY` variable to `OPENAI_API_KEY` to match the official documentation. The upgrade script should do this automatically for you, but please double-check that your key is correct in the new `.env` file.
- We have removed the `VITE_SHOW_GOOGLE_LOGIN_OPTION` variable, since it is no longer needed. The app will automatically enable Google Login if you provide the `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` variables. 🔑
- We have changed the variable name for setting the app title from `VITE_APP_TITLE` to `APP_TITLE`. If you had set a custom app title before, you need to update the variable name in the `.env` file to keep it. Otherwise, the app might revert to the default title.
- For enhanced security, we are now asking for crypto keys for securely storing credentials in the `.env` file. Crypto keys are used to encrypt and decrypt sensitive data such as passwords and access keys. If you don't set them, the app will crash on startup. 🔒
- You need to fill the following variables in the `.env` file with 32-byte (64 characters in hex) or 16-byte (32 characters in hex) values:
- `CREDS_KEY` (32-byte)
- `CREDS_IV` (16-byte)
- `JWT_SECRET` (32-byte) optional but recommended
- The upgrade script will do it for you, otherwise you can use this replit to generate some crypto keys quickly: https://replit.com/@daavila/crypto#index.js
- Make sure you keep your crypto keys safe and don't share them with anyone. 🙊
---
### Docker
- The docker-compose file had some change. Review the [new docker instructions](../install/docker_install.md) to make sure you are setup properly. This is still the simplest and most effective method.
---
### Local Install
- If you had installed a previous version, you can run `npm run upgrade` to automatically copy the content of both files to the new `.env` file and backup the old ones in the root dir.
- If you are installing the project for the first time, it's recommend you run the installation script `npm run ci` to guide your local setup (otherwise continue to use docker)
- The upgrade script requires both `/api/.env` and `/client/.env` files to run properly. If you get an error about a missing client env file, just rename the `/client/.env.example` file to `/client/.env` and run the script again.
- After running the upgrade script, the `OPENAI_API_KEY` variable might be placed in a different section in the new `.env` file than before. This does not affect the functionality of the app, but if you want to keep it organized, you can look for it near the bottom of the file and move it to its usual section.
---
We apologize for any inconvenience caused by these changes. We hope you enjoy the new and improved version of our app!
---
## [Go Back to ReadMe](../../README.md)