Skip to content

Commit 58de774

Browse files
Classic298Classic298
committed
Add an Open Terminal updating guide
Open Terminal is versioned and released separately from Open WebUI, and nothing in the setup docs explained how to move an existing install to a newer one. Users running an image from several months ago were missing features described on these pages, most visibly the accurate Word and PowerPoint previews that need the server-side renderer added in 0.12.1, with no obvious way to tell how old their server was or what to do about it. The new page covers reading the running version off the API docs page, then updating through Docker, pip, uvx or Compose. It calls out that removing the container discards its settings, so the volume and the API key have to be repeated on the new run command, and it lists which recent features need which version. The smaller images ship without LibreOffice, so that limitation is stated alongside. Also corrects a broken anchor from the performance page to MILVUS_URI.
1 parent 15abd71 commit 58de774

3 files changed

Lines changed: 151 additions & 3 deletions

File tree

‎docs/features/open-terminal/setup/installation.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,7 @@ The `--config` (path to a TOML config file) and `--cwd` (working directory for t
198198
[**Open WebUI Computer**](/ecosystem/computer) is your entire computer in a browser tab: files, terminal, git, editor, and AI, accessible from any device. It also connects to Open WebUI via its gateway API.
199199
:::
200200

201-
## Next step
201+
## Next steps
202202

203-
[**Connect to Open WebUI →**](./connecting)
203+
- [**Connect to Open WebUI →**](./connecting)
204+
- [**Updating →**](./updating), how to move an existing install to a newer version.

‎docs/features/open-terminal/setup/updating.mdx‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
sidebar_position: 3
3+
title: "Updating"
4+
---
5+
6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
9+
# Updating Open Terminal
10+
11+
Open Terminal is a separate program from Open WebUI, so updating Open WebUI does not update it. If a feature described in these pages is missing, or a preview looks worse than it should, the usual reason is a terminal server that has been running untouched for a while.
12+
13+
## Check which version you are running
14+
15+
Open `http://localhost:8000/docs` in a browser, using whatever address you gave Open WebUI. The version number sits next to the **Open Terminal** title at the top of the page.
16+
17+
If you would rather do it from a shell:
18+
19+
```bash
20+
curl -s http://localhost:8000/openapi.json | python -c "import json,sys; print(json.load(sys.stdin)['info']['version'])"
21+
```
22+
23+
Compare that against the [latest release](https://github.com/open-webui/open-terminal/releases). Neither request needs your API key.
24+
25+
---
26+
27+
## Update
28+
29+
Your files live in a Docker volume or on your own disk, and updating replaces the program rather than the data. Nothing in `/home/user` is touched.
30+
31+
<Tabs>
32+
<TabItem value="docker" label="Docker" default>
33+
34+
Three commands: fetch the new image, remove the old container, start a new one.
35+
36+
```bash
37+
docker pull ghcr.io/open-webui/open-terminal
38+
docker rm -f open-terminal
39+
```
40+
41+
Then run the same `docker run` command you used to start it:
42+
43+
```bash
44+
docker run -d \
45+
--name open-terminal \
46+
--restart unless-stopped \
47+
-p 8000:8000 \
48+
-v open-terminal:/home/user \
49+
-e OPEN_TERMINAL_API_KEY=your-secret-key \
50+
ghcr.io/open-webui/open-terminal
51+
```
52+
53+
:::warning Use the same flags as before
54+
`docker rm -f` deletes the container and its settings, so the new one only gets what you type on this line. In particular keep `-v open-terminal:/home/user`, which is what carries your files over, and keep the same `OPEN_TERMINAL_API_KEY` so Open WebUI can still connect. Everything you have forgotten here is simply gone from the new container.
55+
56+
Run `docker inspect open-terminal` before removing it if you are not sure what the old one was started with.
57+
:::
58+
59+
Using one of the smaller images? Pull the tag you actually run, such as `ghcr.io/open-webui/open-terminal:slim`, and put that same tag on the `docker run` line.
60+
61+
</TabItem>
62+
<TabItem value="bare-metal" label="Bare Metal">
63+
64+
**Installed with pip:**
65+
66+
```bash
67+
pip install --upgrade open-terminal
68+
```
69+
70+
Then stop the running server with **Ctrl+C** and start it again. The upgrade does not reach a process that is already running.
71+
72+
If you installed the MCP extra, keep it on the upgrade:
73+
74+
```bash
75+
pip install --upgrade "open-terminal[mcp]"
76+
```
77+
78+
**Running with uvx:**
79+
80+
uvx caches the version it first downloaded and keeps using it. Ask for the latest one explicitly:
81+
82+
```bash
83+
uvx open-terminal@latest run --host 0.0.0.0 --port 8000 --api-key your-secret-key
84+
```
85+
86+
</TabItem>
87+
<TabItem value="compose" label="Docker Compose">
88+
89+
From the directory holding your `docker-compose.yml`:
90+
91+
```bash
92+
docker compose pull open-terminal
93+
docker compose up -d open-terminal
94+
```
95+
96+
The first command fetches the new image and the second recreates the container with it. Your Compose file already carries the volume and the API key, so there is nothing to retype.
97+
98+
Leave the service name off both commands to update everything in the file, Open WebUI included.
99+
100+
</TabItem>
101+
</Tabs>
102+
103+
---
104+
105+
## Confirm it worked
106+
107+
Reload `http://localhost:8000/docs` and check the version number again. As long as the address and the API key stayed the same, there is nothing to change in Open WebUI.
108+
109+
---
110+
111+
## What a newer server gives you
112+
113+
A few things in the file browser are done by the terminal server rather than by your browser, so they only appear once it is new enough:
114+
115+
| Since | What it adds |
116+
| :--- | :--- |
117+
| 0.12.1 | Word and PowerPoint files preview as the real thing. The server renders them the way Office does, instead of the browser approximating the layout. |
118+
| 0.12.0 | The file browser searches file contents as well as file names, and shows the matching lines. |
119+
| 0.11.35 | A configurable file browser home, read-only markers on files you cannot change, and template variables in custom system prompts. |
120+
121+
Office rendering needs the default image. The `slim`, `alpine` and `openshift` images stay deliberately small and leave LibreOffice out, so a document preview there falls back to the browser's own rendering and warns that it may differ from the download.
122+
123+
---
124+
125+
## Troubleshooting
126+
127+
**The version has not changed.** Docker keeps using an image it already has when the tag is pinned to a specific version. Check the tag on your `docker run` line, and pull that tag rather than the bare name.
128+
129+
**Word and PowerPoint previews still look approximate.** Either the server is older than 0.12.1, or it is one of the small images that ships without LibreOffice. Switch to `ghcr.io/open-webui/open-terminal` with no tag suffix.
130+
131+
**Open WebUI says the terminal is unavailable.** The new container did not come up with the same port or key as the old one. Compare the connection in Open WebUI against the flags on your `docker run` line, and check `docker logs open-terminal`.
132+
133+
**Files are missing after the update.** The new container was started without the volume. Stop it, and start it again with `-v open-terminal:/home/user`, or with whatever volume you used originally. The data is still in the volume and only the new container is failing to see it.
134+
135+
---
136+
137+
## Running Terminals
138+
139+
[Terminals](/features/open-terminal/terminals) provisions a container per user from a policy, so operators update the image on the policy rather than by hand. Change the image there, then refresh the affected terminals as described in [Applying Changes](/features/open-terminal/terminals/orchestration/applying-changes).
140+
141+
---
142+
143+
## See also
144+
145+
- [Installation](./installation), the original setup commands for each method.
146+
- [Connecting to Open WebUI](./connecting), if the connection needs redoing.
147+
- [File browser](/features/open-terminal/file-browser), what the previews above look like.

‎docs/troubleshooting/performance.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -492,7 +492,7 @@ VECTOR_DB=milvus
492492
ENABLE_MILVUS_MULTITENANCY_MODE=True
493493
```
494494

495-
Leave `MILVUS_URI` unset. The default already points at the embedded database inside your data directory, and setting the variable to that path stops the application from starting. See [`MILVUS_URI`](/reference/env-configuration#milvus_uri) for why, and for the directory that has to exist first.
495+
Leave `MILVUS_URI` unset. The default already points at the embedded database inside your data directory, and setting the variable to that path stops the application from starting. See [`MILVUS_URI`](/reference/env-configuration#milvus_uri-required) for why, and for the directory that has to exist first.
496496

497497
With multitenancy on, users share one set of collections and each user's vectors are partitioned inside them. Without it, every user and every knowledge base gets its own collection, which is what makes the footprint grow far faster than the content does. On a device where storage is small or billed, this is usually the single biggest reduction available after offloading the embedding model.
498498

0 commit comments

Comments
 (0)