Merge pull request #23 from justinh-rahb/main

Enhancements to FAQs and Updating Instructions

docs/faq.md

@@ -17,4 +17,31 @@ title: "📋 FAQ"
 
 **A:** To make services running on the host accessible to Docker containers, configure these services to listen on all network interfaces, using the IP address `0.0.0.0`, instead of `127.0.0.1` which is limited to `localhost` only. This configuration allows the services to accept connections from any IP address, including Docker containers. It's important to be aware of the security implications of this setup, especially when operating in environments with potential external access. Implementing appropriate security measures, such as firewalls and authentication, can help mitigate risks.
 
+#### **Q: Why isn't my Open WebUI updating? I've re-pulled/restarted the container, and nothing changed.**
+
+**A:** Updating Open WebUI requires more than just pulling the new Docker image. Here’s why your updates might not be showing and how to ensure they do:
+
+1. **Updating the Docker Image**: The command `docker pull ghcr.io/open-webui/open-webui:main` updates the Docker image but not the running container or its data.
+2. **Persistent Data in Docker Volumes**: Docker volumes store data independently of container lifecycles, preserving your data (like chat histories) through updates.
+3. **Applying the Update**: Ensure your update takes effect by removing the existing container (which doesn't delete the volume) and creating a new one with the updated image and existing volume attached.
+
+This process updates the app while keeping your data safe.
+
+#### **Q: Wait, delete my container, won't I lose my data?**
+
+**A:** It's a common concern, but deleting a container doesn't mean you'll lose your data, provided you're using Docker volumes correctly. Here’s why:
+
+- **Volumes Preserve Data**: Docker volumes are designed to persist data outside of container lifecycles. As long as your data is stored in a volume, it remains intact, regardless of what happens to the container.
+- **Safe Update Process**: When updating Open WebUI, removing the old container and creating a new one with the updated image does not affect the data stored in volumes. The key is not to explicitly delete the volume with commands like `docker volume rm`.
+
+By following the correct update steps—pulling the new image, removing the old container without deleting the volume, and creating a new container with the updated image and the existing volume—your application code is updated while your data remains unchanged and safe.
+
+#### **Q: Should I use the distro-packaged Docker or the official Docker package?**
+
+**A:** We recommend using the official Docker package over distro-packaged versions for running Open WebUI. The official Docker package is frequently updated with the latest features, bug fixes, and security patches, ensuring optimal performance and security. Additionally, it supports important functionalities like `host.docker.internal`, which may not be available in distro-packaged versions. This feature is essential for proper network configurations and connectivity within Docker containers.
+
+By choosing the official Docker package, you benefit from consistent behavior across different environments, more reliable troubleshooting support, and access to the latest Docker advancements. The broader Docker community and resources are also more aligned with the official package, providing you with a wealth of information and support for any issues you might encounter.
+
+Everything you need to run Open WebUI, including your data, remains within your control and your server environment, emphasizing our commitment to your privacy and security. For instructions on installing the official Docker package, please refer to the [Install Docker Engine](https://docs.docker.com/engine/install/) guide on Docker's official documentation site.
+
 If you have any further questions or concerns, please don't hesitate to reach out! 🛡️

docs/getting-started/index.md

@@ -122,14 +122,18 @@ When using Docker to install Open WebUI, make sure to include the `-v open-webui
 
 #### Open WebUI: Server Connection Error
 
-If you're experiencing connection issues, it’s often due to the WebUI docker container not being able to reach the Ollama server at 127.0.0.1:11434 (host.docker.internal:11434) inside the container . Use the `--network=host` flag in your docker command to resolve this. Note that the port changes from 3000 to 8080, resulting in the link: `http://localhost:8080`.
+Encountering connection issues between the Open WebUI Docker container and the Ollama server? This problem often arises because distro-packaged versions of Docker—like those from the Ubuntu repository—do not support the `host.docker.internal` alias for reaching the host directly. Inside a container, referring to `localhost` or `127.0.0.1` typically points back to the container itself, not the host machine.
 
-**Example Docker Command**:
+To address this, we recommend using the `--network=host` flag in your Docker command. This flag allows the container to use the host's networking stack, effectively making `localhost` or `127.0.0.1` in the container refer to the host machine. As a result, the WebUI can successfully connect to the Ollama server at `127.0.0.1:11434`. Please note, with `--network=host`, the container's port configuration aligns directly with the host, changing the access link to `http://localhost:8080`.
+
+**Here's how you can modify your Docker command**:
 
 ```bash
 docker run -d --network=host -v open-webui:/app/backend/data -e OLLAMA_BASE_URL=http://127.0.0.1:11434 --name open-webui --restart always ghcr.io/open-webui/open-webui:main
 ```
 
+For more details on networking in Docker and addressing common connectivity issues, visit our [FAQ page](/faq/). This page provides additional context and solutions for frequently encountered problems, ensuring a smoother operation of Open WebUI in various environments.
+
 ## Installing with Podman
 
 <details>
@@ -186,14 +190,22 @@ For other ways to install, like using Kustomize or Helm, check out [INSTALLATION
 
 ### Updating your Docker Installation
 
-In case you want to update your local Docker installation to the latest version, you can do it with [Watchtower](https://containrrr.dev/watchtower/):
+For detailed instructions on manually updating your local Docker installation of Open WebUI, including steps for those not using Watchtower and updates via Docker Compose, please refer to our dedicated guide: [UPDATING](/getting-started/updating).
+
+For a quick update with Watchtower, use the command below. Remember to replace `open-webui` with your actual container name if it differs.
 
 ```bash
 docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once open-webui
 ```
 
 In the last part of the command, replace `open-webui` with your container name if it is different.
 
+:::info
+
+After updating Open WebUI, you might need to refresh your browser cache to see the changes.
+
+:::
+
 ## How to Install Without Docker
 
 While we strongly recommend using our convenient Docker container installation for optimal support, we understand that some situations may require a non-Docker setup, especially for development purposes. Please note that non-Docker installations are not officially supported, and you might need to troubleshoot on your own.

docs/getting-started/updating.md

@@ -0,0 +1,120 @@
+# Updating
+
+## Updating your Docker Installation
+
+Keeping your Open WebUI Docker installation up-to-date ensures you have the latest features and security updates. You can update your installation manually or use [Watchtower](https://containrrr.dev/watchtower/) for automatic updates.
+
+### Manual Update
+
+Follow these steps to manually update your Open WebUI:
+
+1. **Pull the Latest Docker Image**:
+   ```bash
+   docker pull ghcr.io/open-webui/open-webui:main
+   ```
+
+2. **Stop and Remove the Existing Container**:
+   - This step ensures that you can create a new container from the updated image.
+   ```bash
+   docker stop open-webui
+   docker rm open-webui
+   ```
+
+3. **Create a New Container with the Updated Image**:
+   - Use the same `docker run` command you used initially to create the container, ensuring all your configurations remain the same.
+   ```bash
+   docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
+   ```
+
+This process updates your Open WebUI container to the latest version while preserving your data stored in Docker volumes.
+
+### Updating with Watchtower
+
+For those who prefer automated updates, Watchtower can monitor your Open WebUI container and automatically update it to the latest version. You have two options with Watchtower: running it once for an immediate update, or deploying it persistently to automate future updates.
+
+#### Running Watchtower Once
+
+To update your container immediately without keeping Watchtower running continuously, use the following command. Replace `open-webui` with your container name if it differs.
+
+```bash
+docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once open-webui
+```
+
+#### Deploying Watchtower Persistently
+
+If you prefer Watchtower to continuously monitor and update your container whenever a new version is available, you can run Watchtower as a persistent service. This method ensures your Open WebUI always stays up to date without any manual intervention. Use the command below to deploy Watchtower in this manner:
+
+```bash
+docker run -d --name watchtower --volume /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower open-webui
+```
+
+Remember to replace `open-webui` with the name of your container if you have named it differently. This configuration allows you to benefit from the latest improvements and security patches with minimal downtime and manual effort.
+
+### Updating Docker Compose Installation
+
+If you installed Open WebUI using Docker Compose, follow these steps to update:
+
+1. **Pull the Latest Images**:
+   - This command fetches the latest versions of the images specified in your `docker-compose.yml` files.
+   ```bash
+   docker compose pull
+   ```
+
+2. **Recreate the Containers with the Latest Images**:
+   - This command recreates the containers based on the newly pulled images, ensuring your installation is up-to-date. No build step is required for updates.
+   ```bash
+   docker compose up -d
+   ```
+
+This method ensures your Docker Compose-based installation of Open WebUI (and any associated services, like Ollama) is updated efficiently and without the need for manual container management.
+
+## Updating Your Direct Install
+
+For those who have installed Open WebUI directly without using Docker, updates are just as important to ensure access to the latest features and security patches. Remember, direct installations are not officially supported, and you might need to troubleshoot on your own. Here's how to update your installation:
+
+### Pull the Latest Changes
+
+Navigate to your Open WebUI project directory and pull the latest changes from the repository:
+
+```sh
+cd path/to/open-webui/
+git pull origin main
+```
+
+Replace `path/to/open-webui/` with the actual path to your Open WebUI installation.
+
+### Update Dependencies
+
+After pulling the latest changes, update your project dependencies. This step ensures that both frontend and backend dependencies are up to date.
+
+- **For Node.js (Frontend):**
+
+```sh
+npm install
+npm run build
+```
+
+- **For Python (Backend):**
+
+```sh
+cd backend
+pip install -r requirements.txt -U
+```
+
+### Restart the Backend Server
+
+To apply the updates, you need to restart the backend server. If you have a running instance, stop it first and then start it again using the provided script.
+
+```sh
+bash start.sh
+```
+
+This command should be run from within the `backend` directory of your Open WebUI project.
+
+:::info
+
+Direct installations require more manual effort to update compared to Docker-based installations. If you frequently need updates and want to streamline the process, consider transitioning to a Docker-based setup for easier management.
+
+:::
+
+By following these steps, you can update your direct installation of Open WebUI, ensuring you're running the latest version with all its benefits. Remember to back up any critical data or custom configurations before starting the update process to prevent any unintended loss.