diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 06d2656bd6..a1542cb76e 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -15,8 +15,9 @@ Please delete any irrelevant options. - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] This change requires a documentation update -- [ ] Documentation update - [ ] Translation update +- [ ] Documentation update + ## Testing @@ -26,6 +27,8 @@ Please describe your test process and include instructions so that we can reprod ## Checklist +Please delete any irrelevant options. + - [ ] My code adheres to this project's style guidelines - [ ] I have performed a self-review of my own code - [ ] I have commented in any complex areas of my code @@ -34,3 +37,4 @@ Please describe your test process and include instructions so that we can reprod - [ ] I have written tests demonstrating that my changes are effective or that my feature works - [ ] Local unit tests pass with my changes - [ ] Any changes dependent on mine have been merged and published in downstream modules. +- [ ] New documents have been locally validated with mkdocs diff --git a/docs/contributions/documentation_guidelines.md b/docs/contributions/documentation_guidelines.md index bdd9873ed5..7f03f93c80 100644 --- a/docs/contributions/documentation_guidelines.md +++ b/docs/contributions/documentation_guidelines.md @@ -1,51 +1,81 @@ --- title: 📝 Documentation Guidelines -description: Learn how to write and format documentation for LibreChat. +description: Learn how to contribute to the LibreChat documentation by following these guidelines. weight: -9 --- -# Documentation Guidelines +# Documentation Contribution Guidelines -This document explains how to write and format documentation for LibreChat. +This document explains how to contribute to the LibreChat documentation by writing and formatting new documentation. ## New Documents -- Use lowercase letters and underscores to name new documents (e.g. `documentation_guidelines.md`). +- Use lowercase letters and underscores to name new document files (e.g., `documentation_guidelines.md`). - For new features, create new documentation and place it in the relevant folder/sub-folder under `../docs`. - - If the feature adds new functionality, add it to the feature section of the main `README.md` as well as in `../docs/index.md`. -- When you create a new document, **you need to add it to two table of contents:** - - in `README.md` - - and in the `index.md` file in the folder where your doc is located + - If the feature adds new functionality, add it to the appropriate section in the main `README.md` and `../docs/index.md`. +- When creating a new document, **add it to the table of contents in the `index.md` file of the folder where your document is located.** ## Markdown Formatting - Use `#`, `##`, and `###` for headings and subheadings. -- Use `#` for the title of the document. +- Use `#` for the document title. - Use `##` for the main sections of the document. - Use `###` for the sub-sections within a section. -- Use `**` to make text **bold** to highlight important information (do not use in place of a heading). +- Use `**` to make text **bold** and highlight important information (do not use in place of a heading). - Use relative paths for links to other documents. -- You can use HTML to add more features to a document. -- By default the title indexed by mkdocs will be the first heading. You can override this by adding metadata at the top of your document: -```bash +- You can use HTML to add additional features to a document. + +## Document Metadata +- Add metadata in the header of your document following this format: +```yaml --- -title: Document Title -description: This description will be used in social cards +title: 😊 Document Title +description: This description will be used in social cards and search engine results. weight: 0 --- ``` -- Setting the weight in the document metadata will influence its position in the table of contents. Lowest weight are placed first. Not setting it will default to `0`. When multiple docs have the same weight it sorts in alphabetical order. +- `title:` Begin with an emoji representing your new document, followed by a descriptive title. +- `description:` A brief description of the document's content. +- `weight:` Setting the weight in the document metadata will influence its position in the table of contents. Lowest weights are placed first. If not set, it defaults to `0`. When multiple docs have the same weight, they are sorted alphabetically. ## Important Notes -- **⚠️Keep it organized and structured⚠️** +- **⚠️Keep the documentation organized and structured⚠️** - Do not add unrelated information to an existing document. Create a new one if needed. -- All assets should be uploaded in the document from GitHub's webui -- **Before submitting a PR, double-check on GitHub that everything is properly displayed and that all links work correctly.** +- Upload all assets (images, files) directly from GitHub's web interface when editing the document. -![image](https://github.com/danny-avila/LibreChat/assets/32828263/4f138ab4-31a5-4fae-a459-5335e5ff25a8) +> **Tip:** Go to the LibreChat repository, find a conversation, and paste an image from your clipboard into the text input box. It will automatically be converted into a URL you can use in your document. (Then exit the page without actually posting the comment.😉) + + > Get the link from a text input box: + ![image](https://github.com/danny-avila/LibreChat/assets/32828263/c1612f93-a6c0-4af7-9965-9f83872cff00) + Or upload directly from the web UI: + ![image](https://github.com/danny-avila/LibreChat/assets/32828263/4f138ab4-31a5-4fae-a459-5335e5ff25a8) + +## Testing New Documents +- When adding new documents, it is important to test them locally using MkDocs to ensure correct formatting and proper organization in the table of contents (index.md and the left panel of the category). + +### Setup MkDocs Locally +- Requirement: Python 3.x + +#### Material for MkDocs Installation +- We are using MkDocs Material and multiple plugins. All of them are required to properly test new documentation. +```sh +pip install mkdocs-material +pip install mkdocs-nav-weight +pip install mkdocs-publisher +pip install mkdocs-exclude +``` +#### Running MkDocs +- Use this command to start MkDocs: +```sh +mkdocs serve +``` +- Look for any errors in the console logs and fix them if possible. +- Access the locally running documentation website at `http://127.0.0.1:8000/`. + + ![image](https://github.com/danny-avila/LibreChat/assets/32828263/d5489a5f-2b4d-4cf5-b8a1-d0ea1d8a67cd) ## Tips -- You can check the code of this document to see how it works. -- You can run MKDocs locally to test bigger documentation changes -- You can ask GPT or Bing for help with proofreading, syntax, and markdown formatting. - +- You can check the code of this document to see how it works. +- You can run MkDocs locally to test more extensive documentation changes. +- You can ask GPT or Bing for help with proofreading, syntax, and markdown formatting. + --- ### Example of HTML image embedding:

diff --git a/docs/deployment/docker_ubuntu_deploy.md b/docs/deployment/docker_ubuntu_deploy.md index 2333122c35..95c040f8b0 100644 --- a/docs/deployment/docker_ubuntu_deploy.md +++ b/docs/deployment/docker_ubuntu_deploy.md @@ -1,5 +1,5 @@ --- -title: 🐳 Ubuntu Docker Deployment Guide +title: 🐳 Ubuntu Docker Deployment description: These instructions are designed for someone starting from scratch for a Docker Installation on a remote Ubuntu server weight: -9 --- diff --git a/docs/deployment/index.md b/docs/deployment/index.md index 84b40e0d96..3d8d2b4d4d 100644 --- a/docs/deployment/index.md +++ b/docs/deployment/index.md @@ -11,8 +11,9 @@ weight: 3 --- - 🌊 [DigitalOcean (✨Recommended)](./digitalocean.md) -- 🐳 [Ubuntu Docker Deployment Guide](./docker_ubuntu_deploy.md) +- 🐳 [Ubuntu Docker Deployment](./docker_ubuntu_deploy.md) - 🤗 [HuggingFace](./huggingface.md) +- 🛤️ [Railway](./railway.md) - 🐧 [Linode](./linode.md) - ⚡ [Azure](./azure-terraform.md) - ⏹️ [Render](./render.md) @@ -25,4 +26,5 @@ weight: 3 - ☁️ [Cloudflare](./cloudflare.md) - 🪨 [Ngrok](./ngrok.md) -- ↪️ [NGINX Guide](./nginx.md) +- ↪️ [Nginx Guide](./nginx.md) +- 🚦 [Traefik](./traefik.md) \ No newline at end of file diff --git a/docs/deployment/introduction.md b/docs/deployment/introduction.md index 13a7e58d71..bef4452def 100644 --- a/docs/deployment/introduction.md +++ b/docs/deployment/introduction.md @@ -21,7 +21,7 @@ In this guide, you will explore various options to efficiently deploy LibreChat | [DigitalOcean](./digitalocean.md) | Cloud Infrastructure | Intuitive interface, stable pricing | Smaller network footprint | Optimal for enthusiasts & small to medium businesses | ✅ Well Known, Reliable | | [HuggingFace](./huggingface.md) | AI/ML Solutions | ML/NLP specialization | Focused on ML applications | Excellent for AI/ML initiatives | ✅ Free | | [Azure](./azure-terraform.md) | Cloud Services | Comprehensive offerings, Microsoft ecosystem integration | Can be complex, may incur higher costs | Ideal for large enterprises | ✅ Pro | -| [Railway](https://railway.app/template/b5k2mn?referralCode=HI9hWz) | App Deployment | Simplified app deployment | Emerging service with limited info | Further evaluation recommended | ✅ Easy | +| [Railway](./railway.md) | App Deployment | Simplified app deployment | Emerging service with limited info | Further evaluation recommended | ✅ Easy | | [Linode](./linode.md) | Cloud Hosting | Responsive support, clear pricing | Fewer specialized services | Comparable to DigitalOcean | | | [Hetzner](./hetzner_ubuntu.md) | Data Hosting | Emphasizes privacy, economical | Primarily European servers | Suitable for Europe-centric operations | | | [Heroku](./heroku.md) | Platform as a Service | User-friendly, scalable | Higher cost potential, less flexibility| A good starting point for startups | | @@ -43,7 +43,7 @@ In this guide, you will explore various options to efficiently deploy LibreChat ## 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). +The integration level with cloud vendors varies: from platforms enabling single-click LibreChat deployments like [Railway](./railway.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 @@ -55,7 +55,7 @@ When deploying applications on a global scale, it is essential to consider the f 2. Global accessibility implications: Understand the implications of deploying your application globally, including the legal and compliance requirements that vary by region. 3. Secure configuration: Ensure that your application is configured securely, including the use of secure protocols, secure authentication, and authorization mechanisms. -If you choose to use IaaS or Tunnel services for your deployment, you may need to utilize a reverse proxy such as [Nginx](./nginx.md) or [Cloudflare](./cloudflare.md) to name a few. +If you choose to use IaaS or Tunnel services for your deployment, you may need to utilize a reverse proxy such as [Nginx](./nginx.md), [Traefik](./traefik.md) or [Cloudflare](./cloudflare.md) to name a few. Investing in the appropriate security measures is crucial to safeguarding your digital assets and ensuring the success of your global deployment. @@ -113,7 +113,7 @@ Platform as a Service (PaaS) is a model of cloud computing that offers a develop ### 4. One Click Deployment (PaaS) -- [Railway](https://railway.app/template/b5k2mn?referralCode=HI9hWz): Popular one-click deployment solution +- [Railway](./railway.md): Popular one-click deployment solution - [Zeabur](zeabur.md): Pioneering effortless one-click deployment solutions. ## Other / Network Services diff --git a/docs/deployment/railway.md b/docs/deployment/railway.md new file mode 100644 index 0000000000..638ce1ab7f --- /dev/null +++ b/docs/deployment/railway.md @@ -0,0 +1,55 @@ +--- +title: 🛤️ Railway (one-click) +description: Deploying LibreChat on Railway +weight: -9 +--- + +# Deploying LibreChat on Railway (One-Click Install) + +Railway provides a one-click install option for deploying LibreChat, making the process even simpler. Here's how you can do it: + +## Steps + +### **Visit the LibreChat repository** + +Go to the [LibreChat repository](https://github.com/danny-avila/LibreChat) on GitHub. + +### **Click the "Deploy on Railway" button** + +

+ + Deploy on Railway + +

+ +(The button is also available in the repository's README file) + +### **Log in or sign up for Railway** + +If you're not already logged in to Railway, you'll be prompted to log in or sign up for a free account. + +### **Configure environment variables** + +Railway will automatically detect the required environment variables for LibreChat. Review the configuration of the three containers and click `Save Config` after reviewing each of them. + +![image](https://github.com/danny-avila/LibreChat/assets/32828263/4417e997-621c-44b6-8d2d-94d7e4e1a2bf) + +The default configuration will get you started, but for more advanced features, you can consult our documentation on the subject: [Environment Variables](../install/configuration/dotenv.md) + +### **Deploy** + +Once you've filled in the required environment variables, click the "Deploy" button. Railway will handle the rest, including setting up a PostgreSQL database and building/deploying your LibreChat instance. + +![image](https://github.com/danny-avila/LibreChat/assets/32828263/d94e20c6-0ae7-42af-8937-7fbd34d63a3b) + +### **Access your LibreChat instance** + +After the deployment is successful, Railway will provide you with a public URL where you can access your LibreChat instance. + +That's it! You have successfully deployed LibreChat on Railway using the one-click install process. You can now start using and customizing your LibreChat instance as needed. + +## Additional Tips + +- Regularly check the LibreChat repository for updates and redeploy your instance to receive the latest features and bug fixes. + +For more detailed instructions and troubleshooting, refer to the official LibreChat documentation and the Railway guides. \ No newline at end of file diff --git a/docs/deployment/traefik.md b/docs/deployment/traefik.md new file mode 100644 index 0000000000..cf8dbbe1ad --- /dev/null +++ b/docs/deployment/traefik.md @@ -0,0 +1,89 @@ +--- +title: 🚦 Traefik +description: Learn how to use Traefik as a reverse proxy and load balancer to expose your LibreChat instance securely over HTTPS with automatic SSL/TLS certificate management. +weight: 10 +--- + +# Using Traefik with LibreChat on Docker + +[Traefik](https://traefik.io/) is a modern HTTP reverse proxy and load balancer that makes it easy to deploy and manage your services. If you're running LibreChat on Docker, you can use Traefik to expose your instance securely over HTTPS with automatic SSL certificate management. + +## Prerequisites + +- Docker and Docker Compose installed on your system +- A domain name pointing to your server's IP address + +## Configuration + +### **Create a Docker network for Traefik** + + ```bash + docker network create web + ``` + +### **Configure Traefik and LibreChat** + + In your docker-compose.override.yml file, add the following configuration: + + ```yaml + version: '3' + + services: + api: + labels: + - "traefik.enable=true" + - "traefik.http.routers.librechat.rule=Host(`your.domain.name`)" + - "traefik.http.routers.librechat.entrypoints=websecure" + - "traefik.http.routers.librechat.tls.certresolver=leresolver" + - "traefik.http.services.librechat.loadbalancer.server.port=3080" + networks: + - web + - librechat_default + volumes: + - ./librechat.yaml:/app/librechat.yaml + +traefik: + image: traefik:v2.9 + ports: + - "80:80" + - "443:443" + volumes: + - "/var/run/docker.sock:/var/run/docker.sock:ro" + - "./letsencrypt:/letsencrypt" + networks: + - web + command: + - "--log.level=DEBUG" + - "--api.insecure=true" + - "--providers.docker=true" + - "--providers.docker.exposedbydefault=false" + - "--entrypoints.web.address=:80" + - "--entrypoints.websecure.address=:443" + - "--certificatesresolvers.leresolver.acme.tlschallenge=true" + - "--certificatesresolvers.leresolver.acme.email=your@email.com" + - "--certificatesresolvers.leresolver.acme.storage=/letsencrypt/acme.json" + + networks: + web: + external: true + librechat_default: + external: true + ``` + + Replace `your@email.com` with your email address for Let's Encrypt certificate notifications. + +### **Start the containers** + + ```bash + docker-compose up -d + ``` + + This will start Traefik and LibreChat containers. Traefik will automatically obtain an SSL/TLS certificate from Let's Encrypt and expose your LibreChat instance securely over HTTPS. + +You can now access your LibreChat instance at `https://your.domain.name`. Traefik will handle SSL/TLS termination and reverse proxy requests to your LibreChat container. + +## Additional Notes + +- The Traefik configuration listens on ports 80 and 443 for HTTP and HTTPS traffic, respectively. Ensure that these ports are open on your server's firewall. +- Traefik stores SSL/TLS certificates in the `./letsencrypt` directory on your host machine. You may want to back up this directory periodically. +- For more advanced configuration options, refer to the official Traefik documentation: [https://doc.traefik.io/](https://doc.traefik.io/)