diff --git a/docs/contributing.mdx b/docs/contributing.mdx index 179a31efe..23c1c3ae1 100644 --- a/docs/contributing.mdx +++ b/docs/contributing.mdx @@ -15,6 +15,18 @@ Your interest in contributing to Open WebUI is greatly appreciated. This documen Looking to contribute? Great! Here's how you can help: +### 🧪 Test the Development Branch + +**One of the most valuable ways to contribute is running the dev branch.** You don't need to write code—just use it and report issues! + +```bash +docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:dev +``` + +**Keep it updated regularly** — the dev branch moves fast! If Docker doesn't work for you, the [Local Development Guide](/getting-started/advanced-topics/development) is another great option. + +By testing dev builds, you help us catch bugs before stable releases. Report issues on [GitHub](https://github.com/open-webui/open-webui/issues) with clear reproduction steps. **We cannot deliver high-quality releases without community testing.** + ### 🌟 Code Contribution Guidelines We welcome pull requests. Before submitting one, please: diff --git a/docs/getting-started/advanced-topics/development.md b/docs/getting-started/advanced-topics/development.md index 53d6accbb..a32713362 100644 --- a/docs/getting-started/advanced-topics/development.md +++ b/docs/getting-started/advanced-topics/development.md @@ -7,6 +7,24 @@ title: "Local Development Guide" Excited to dive into Open WebUI development? This comprehensive guide will walk you through setting up your **local development environment** quickly and easily. Whether you're a seasoned developer or just starting out, we'll get you ready to tweak the frontend, enhance the backend, and contribute to the future of Open WebUI! Let's get your development environment up and running in simple, detailed steps! +:::tip Help Us Build Better Software! + +**Running the development setup is one of the most valuable ways to contribute.** You don't need to write code—just using and testing the latest changes helps us catch bugs before stable releases. We cannot deliver high-quality software without community testing. + +**Prefer Docker?** If setting up a local dev environment seems like too much, you can also test by running the [dev Docker image](/#using-the-dev-branch-) — it's the same code, just containerized. + +**Keep your setup updated regularly** — run `git pull origin dev` frequently to stay current with the latest changes. + +::: + +:::warning Do Not Share Data with Production + +**Never share your database or data directory between dev and production setups.** Dev builds may include database migrations that are not backward-compatible. If a dev migration runs on your production data and you later need to roll back, your production setup may break. + +Keep your development data completely separate from production. + +::: + ## Prerequisites Before you begin, ensure your system meets these minimum requirements: diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index ca09ad3a8..bb6b59a37 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -12,7 +12,7 @@ As new variables are introduced, this page will be updated to reflect the growin :::info -This page is up-to-date with Open WebUI release version [v0.7.0](https://github.com/open-webui/open-webui/releases/tag/v0.7.0), but is still a work in progress to later include more accurate descriptions, listing out options available for environment variables, defaults, and improving descriptions. +This page is up-to-date with Open WebUI release version [v0.7.1](https://github.com/open-webui/open-webui/releases/tag/v0.7.1), but is still a work in progress to later include more accurate descriptions, listing out options available for environment variables, defaults, and improving descriptions. ::: @@ -5481,6 +5481,27 @@ When `DATABASE_URL` is not explicitly set, Open WebUI will attempt to construct - Default: `None` - Description: Sets the minimum time interval in seconds between user active status updates in the database. Helps reduce write operations for high-traffic instances. Set to `0.0` to update on every activity. +#### `DATABASE_ENABLE_SESSION_SHARING` + +- Type: `bool` +- Default: `False` +- Description: Controls database session sharing behavior. When enabled (`True`), `get_db_context` reuses existing database sessions, which can improve performance and scalability in high-concurrency environments. When disabled (`False`), new sessions are always created. + +:::tip Recommendations by Database Type + +- **SQLite:** Keep this setting **disabled** (default `False`). Enabling session sharing on SQLite with limited hardware resources may cause performance issues. +- **PostgreSQL:** Consider **enabling** this setting (`True`) for improved performance, especially in multi-user or high-concurrency deployments. + +This setting is very deployment-specific. Users are encouraged to experiment based on their hardware specs and database choice to find the optimal configuration. + +::: + +:::warning + +Enabling this on low-spec hardware (e.g., Raspberry Pi, containers with limited CPU allocation) may cause significant slowdowns or timeouts. If you experience slow admin page loads or API timeouts after upgrading, ensure this setting is disabled. + +::: + ### Encrypted SQLite with SQLCipher For enhanced security, Open WebUI supports at-rest encryption for its primary SQLite database using SQLCipher. This is recommended for deployments handling sensitive data where using a larger database like PostgreSQL is not needed. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 2b1c4b1a2..4e5da4ac8 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -31,4 +31,10 @@ Stay current with the latest features and security patches with our [Updating Op --- +## 🧪 Help Test Open WebUI + +**Want to help improve Open WebUI?** Run the [development branch](/#using-the-dev-branch-)! Testing dev builds is one of the most valuable contributions you can make—no code required. Just use it and report issues you find. + +--- + Happy exploring! 🎉 If you have questions, join our [community](https://discord.gg/5rJgQTnV4s) or raise an issue on [GitHub](https://github.com/open-webui/open-webui). diff --git a/docs/getting-started/quick-start/index.mdx b/docs/getting-started/quick-start/index.mdx index 91195bb66..c85c08b79 100644 --- a/docs/getting-started/quick-start/index.mdx +++ b/docs/getting-started/quick-start/index.mdx @@ -169,6 +169,10 @@ You are now ready to start using Open WebUI! ## Using Open WebUI with Ollama If you're using Open WebUI with Ollama, be sure to check out our [Starting with Ollama Guide](/getting-started/quick-start/starting-with-ollama) to learn how to manage your Ollama instances with Open WebUI. +## Help Us Improve Open WebUI 🧪 + +**Want to help make Open WebUI better?** Consider running the [development branch](/#using-the-dev-branch-)! Testing dev builds is one of the most valuable contributions you can make—no code required. Just use it and report any issues you find on [GitHub](https://github.com/open-webui/open-webui/issues). + ## Join the Community Need help? Have questions? Join our community: diff --git a/docs/getting-started/updating.mdx b/docs/getting-started/updating.mdx index c87a24b08..980bb5914 100644 --- a/docs/getting-started/updating.mdx +++ b/docs/getting-started/updating.mdx @@ -19,6 +19,11 @@ Keeping Open WebUI updated ensures you have the latest features, security patche 2. Designating a master worker using `ENABLE_DB_MIGRATIONS=True` (default) on one instance and `False` on others. Once migrations complete, you can run with multiple workers normally. ::: + +:::tip Help Us Test Before Release + +**Want to catch bugs before they hit stable releases?** Consider running the [development branch](/#using-the-dev-branch-) instead. Testing dev builds is one of the most valuable contributions you can make. + ::: ## Manual Update diff --git a/docs/intro.mdx b/docs/intro.mdx index c9b702324..4f8ef6df1 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -106,24 +106,46 @@ ghcr.io/open-webui/open-webui:v0.7.0-cuda ### Using the Dev Branch 🌙 -:::warning +:::tip Help Us Build Better Software! -The `:dev` branch contains the latest unstable features and changes. Use it at your own risk as it may have bugs or incomplete features. +**We encourage users to run the development branch!** Testing dev builds is one of the most valuable ways to contribute to Open WebUI. By running the latest development version, you help us catch bugs early, validate new features, and ensure stable releases for everyone. + +**We cannot deliver high-quality software without community testing.** When issues are only discovered after a stable release, it creates a poor experience for everyone. Your feedback on the dev branch directly improves the next release. ::: -If you want to try out the latest bleeding-edge features and are okay with occasional instability, you can use the `:dev` tag like this: +The `:dev` branch contains the latest features and changes before they reach a stable release. While it may occasionally have bugs or incomplete features, it's generally usable for day-to-day testing. +**Standard dev image:** ```bash docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:dev ``` -For the slim variant of the dev branch: - +**Slim variant (excludes bundled models):** ```bash docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:dev-slim ``` +**How to help:** +- Run the dev image on a test instance (not your primary production setup) +- **Keep it updated regularly** — the dev branch moves fast! Pull the latest image frequently or see [Updating Open WebUI](#updating-open-webui) below +- Report issues on [GitHub](https://github.com/open-webui/open-webui/issues) with clear reproduction steps +- Join our [Discord](https://discord.gg/5rJgQTnV4s) to discuss findings + +:::note Alternative: Local Development Setup + +If Docker doesn't work for your environment, you can also run the latest development code using the [Local Development Guide](/getting-started/advanced-topics/development). Conversely, if you prefer Docker over a local setup, the dev image is the easiest way to test. + +::: + +:::warning Do Not Share Data with Production + +**Never share your database or data volume between dev and production setups.** Dev builds may include database migrations that are not backward-compatible. If a dev migration runs on your production data and you later need to roll back, your production setup may break. + +Always use a separate data volume (e.g., `-v open-webui-dev:/app/backend/data`) for testing. + +::: + ### Updating Open WebUI To update Open WebUI container easily, follow these steps: diff --git a/docs/troubleshooting/connection-error.mdx b/docs/troubleshooting/connection-error.mdx index 3d7928fbc..c5163b3b9 100644 --- a/docs/troubleshooting/connection-error.mdx +++ b/docs/troubleshooting/connection-error.mdx @@ -219,6 +219,24 @@ Manual database manipulation should be a last resort. Always back up your databa See the [Environment Configuration](/getting-started/env-configuration#aiohttp_client_timeout_model_list) documentation for more details. +## 🐢 Slow Performance or Timeouts on Low-Spec Hardware + +If you're experiencing slow page loads, API timeouts, or unresponsive UI—especially on resource-constrained systems—this may be related to database session sharing. + +### Cause + +Database session sharing can overwhelm low-spec hardware (Raspberry Pi, containers with minimal CPU, etc.) or SQLite databases under concurrent load. + +### Solution + +Disable database session sharing: + +```bash +DATABASE_ENABLE_SESSION_SHARING=false +``` + +For PostgreSQL on adequate hardware, enabling this setting may improve performance. See the [DATABASE_ENABLE_SESSION_SHARING](/getting-started/env-configuration#database_enable_session_sharing) documentation for details. + ## 🔒 SSL Connection Issue with Hugging Face Encountered an SSL error? It could be an issue with the Hugging Face server. Here's what to do: diff --git a/docs/troubleshooting/index.mdx b/docs/troubleshooting/index.mdx index 543d302b3..bbec3251b 100644 --- a/docs/troubleshooting/index.mdx +++ b/docs/troubleshooting/index.mdx @@ -21,4 +21,8 @@ This project thrives on community spirit and passion. If you still face problems 🌟 If your issues are pressing and you need a quicker resolution, consider [supporting our project](/sponsorships). Your sponsorship not only fast-tracks your queries in a dedicated sponsor-only channel, but also directly supports the [dedicated maintainer](/mission) who is passionately committed to refining and enhancing this tool for everyone. +### 🧪 Help Prevent Future Issues + +**Want to help prevent issues like this from reaching stable releases?** Consider running the [development branch](/#using-the-dev-branch-)! Testing dev builds is one of the most valuable contributions you can make—no code required. Just use it and report any issues you find. + Together, let's harness these opportunities to create the best environment and keep pushing the boundaries of what we can achieve with our project. Thank you from the bottom of our hearts for your understanding, cooperation, and belief in our mission! 🙏 \ No newline at end of file diff --git a/docs/troubleshooting/multi-replica.mdx b/docs/troubleshooting/multi-replica.mdx index 9d7dc25dd..c663b9c1a 100644 --- a/docs/troubleshooting/multi-replica.mdx +++ b/docs/troubleshooting/multi-replica.mdx @@ -16,6 +16,7 @@ Before troubleshooting specific errors, ensure your deployment meets these **abs 3. **Redis for WebSockets:** [`ENABLE_WEBSOCKET_SUPPORT=True`](/getting-started/env-configuration#enable_websocket_support) and [`WEBSOCKET_MANAGER=redis`](/getting-started/env-configuration#websocket_manager) with a valid [`WEBSOCKET_REDIS_URL`](/getting-started/env-configuration#websocket_redis_url) are required. 4. **Shared Storage:** A persistent volume (RWX / ReadWriteMany if possible, or ensuring all replicas map to the same underlying storage for `data/`) is critical for RAG (uploads/vectors) and generated images. 5. **External Vector Database (Recommended):** While embedded Chroma works with shared storage, using a dedicated external Vector DB (e.g., [PGVector](/getting-started/env-configuration#pgvector_db_url), Milvus, Qdrant) is **highly recommended** to avoid file locking issues and improve performance. +6. **Database Session Sharing (Optional):** For PostgreSQL deployments with adequate resources, consider enabling [`DATABASE_ENABLE_SESSION_SHARING=True`](/getting-started/env-configuration#database_enable_session_sharing) to improve performance under high concurrency. --- @@ -128,6 +129,16 @@ This is typically caused by infrastructure latency (Network Latency to the datab **Solution:** Refer to the **[Cloud Infrastructure Latency](/tutorials/tips/performance#%EF%B8%8F-cloud-infrastructure-latency)** section in the Performance Guide for a detailed breakdown of diagnosis and mitigation strategies. +### 7. Optimizing Database Performance + +For PostgreSQL deployments with adequate resources, enabling database session sharing can improve performance under high concurrency: + +```bash +DATABASE_ENABLE_SESSION_SHARING=true +``` + +See [DATABASE_ENABLE_SESSION_SHARING](/getting-started/env-configuration#database_enable_session_sharing) for details. + --- ## Deployment Best Practices diff --git a/docs/tutorials/tips/performance.md b/docs/tutorials/tips/performance.md index 007e11219..000fa6446 100644 --- a/docs/tutorials/tips/performance.md +++ b/docs/tutorials/tips/performance.md @@ -92,6 +92,26 @@ By default, Open WebUI saves chats in **real-time**. This ensures no data loss b - **Effect**: Chats are saved only when the generation is complete (or periodically). - **Recommendation**: **Highly Recommended** for any high-user setup to reduce DB load substantially. +### Database Session Sharing + +Starting with v0.7.1, Open WebUI includes a database session sharing feature that can improve performance under high concurrency by reusing database sessions instead of creating new ones for each request. + +- **Env Var**: `DATABASE_ENABLE_SESSION_SHARING` +- **Default**: `False` + +:::tip Recommendations by Database Type + +- **SQLite:** Keep this setting **disabled** (default). Enabling session sharing on SQLite with limited hardware resources may cause severe performance degradation or timeouts. +- **PostgreSQL with adequate resources:** Consider **enabling** this setting for improved performance, especially in multi-user or high-concurrency deployments. + +::: + +:::warning Low-Spec Hardware + +If you upgraded to v0.7.0 and experienced slow admin page loads, API timeouts, or unresponsive UI, this was likely caused by database session sharing being enabled. Ensure `DATABASE_ENABLE_SESSION_SHARING=False` on low-spec hardware (Raspberry Pi, containers with limited CPU allocation like 250m or less). + +::: + ### Vector Database (RAG) For multi-user setups, the choice of Vector DB matters. @@ -314,3 +334,4 @@ For detailed information on all available variables, see the [Environment Config | `ENABLE_IMAGE_GENERATION` | [Image Generation](/getting-started/env-configuration#enable_image_generation) | | `ENABLE_AUTOCOMPLETE_GENERATION` | [Autocomplete](/getting-started/env-configuration#enable_autocomplete_generation) | | `RAG_SYSTEM_CONTEXT` | [RAG System Context](/getting-started/env-configuration#rag_system_context) | +| `DATABASE_ENABLE_SESSION_SHARING` | [Database Session Sharing](/getting-started/env-configuration#database_enable_session_sharing) |