Skip to content

Agent Zero AI framework

Add unzip to Docker base packages, refactor API key handling, improve self-update system

frdel75b8085b65c8
diff --git a/docker/base/fs/ins/install_base_packages1.sh b/docker/base/fs/ins/install_base_packages1.sh
index 4491ca961..fbc21091c 100644
--- a/docker/base/fs/ins/install_base_packages1.sh
+++ b/docker/base/fs/ins/install_base_packages1.sh
@@ -6,6 +6,6 @@ echo "====================BASE PACKAGES1 START===================="
apt-get update && apt-get upgrade -y
apt-get install -y --no-install-recommends \
- sudo curl wget git cron
+ sudo curl wget git cron unzip
echo "====================BASE PACKAGES1 END===================="
diff --git a/docs/guides/self-update.md b/docs/guides/self-update.md
new file mode 100644
index 000000000..40aaa1159
--- /dev/null
+++ b/docs/guides/self-update.md
@@ -0,0 +1,58 @@
+# Self Update
+
+Agent Zero includes a Docker-oriented self-update flow for switching to a specific repository version tag on `main`, `testing`, or `development`.
+
+## How it works
+
+1. The WebUI writes a YAML request file outside `/a0` so the request survives upgrades and downgrades.
+2. Agent Zero restarts.
+3. The durable updater in `/exe` reads the YAML request before starting the UI.
+4. If requested, it creates a zip backup of `/a0/usr`.
+5. It fetches the requested branch and version tag from the official Agent Zero repository.
+6. It updates `/a0` while preserving gitignored paths such as `/a0/usr`.
+7. It starts Agent Zero again and waits for `/api/health` to become healthy.
+8. If the UI does not become healthy within the allowed time, it restores the previous checkout and starts that version again.
+
+## Durable files
+
+The self-update flow stores its runtime files outside `/a0`:
+
+- Trigger file: `/exe/a0-self-update.yaml`
+- Status file: `/exe/a0-self-update-status.yaml`
+- Last attempt log: `/exe/a0-self-update.log`
+
+Because these files live in `/exe`, you can recover from an older downgraded `/a0` by creating a new update YAML manually.
+
+## Backup behavior
+
+The updater can create a zip backup of `/a0/usr` before replacing repository files.
+
+- The default backup directory is `/a0/tmp/self-update-backups`
+- The default file name format is `usr-YYYYMMDD-HHMMSS.zip`
+- Conflict handling supports rename, overwrite, or fail-before-restart
+
+## Version selection
+
+The WebUI fetches repository version tags for the selected branch and lets you enter any exact version manually, including downgrades.
+
+Agent Zero version tags follow this format:
+
+`v{epoch}.{major}.{minor}.{rest}`
+
+Examples:
+
+- `v0.9.9.2`
+- `v1.0.3.0`
+
+## Major version limitation
+
+Self-update is intentionally limited to changes within the same `epoch.major` line.
+
+If the requested version changes the `epoch` or `major` part of the version, the UI blocks the update and shows a warning. Those upgrades require downloading a new Docker image because they can include operating system level changes or other breaking changes outside the repository checkout.
+
+## Safety notes
+
+- Gitignored paths are preserved during update
+- Obsolete tracked files are removed as part of the checkout replacement
+- Rollback is automatic when the updated UI fails its health check
+- The updater itself lives outside `/a0`, so it is not lost by downgrading to an older repository state
diff --git a/helpers/self_update.py b/helpers/self_update.py
index f0fb91897..50ca1355d 100644
--- a/helpers/self_update.py
+++ b/helpers/self_update.py
@@ -19,6 +19,7 @@ BRANCH_OPTIONS = [
]
SUPPORTED_BRANCHES = {option["value"] for option in BRANCH_OPTIONS}
BACKUP_CONFLICT_POLICIES = {"rename", "overwrite", "fail"}
+MIN_SELECTOR_VERSION = (0, 9, 9)
UPDATE_FILE_PATH = Path("/exe/a0-self-update.yaml")
STATUS_FILE_PATH = Path("/exe/a0-self-update-status.yaml")
@@ -206,6 +207,30 @@ def _get_branch_merged_tags(
return set()
+def _parse_selector_version(tag: str) -> tuple[int, int, int] | None:
+ match = re.fullmatch(r"v(\d+)\.(\d+)\.(\d+)(?:\..+)?", tag.strip())
+ if not match:
+ return None
+ return (
+ int(match.group(1)),
+ int(match.group(2)),
+ int(match.group(3)),
+ )
+
+
+def _is_selector_supported_tag(tag: str) -> bool:
+ parsed = _parse_selector_version(tag)
+ return parsed is not None and parsed >= MIN_SELECTOR_VERSION
+
+
+def _filter_selector_supported_tags(tags: list[str]) -> list[str]:
+ return [tag for tag in tags if _is_selector_supported_tag(tag)]
+
+
+def is_valid_selector_tag(tag: str) -> bool:
+ return _parse_selector_version(tag) is not None
+
+
def get_available_tags(
branch: str | None = None,
*,
@@ -222,6 +247,8 @@ def get_available_tags(
if merged_tags:
tags = [tag for tag in tags if tag in merged_tags]
+ tags = _filter_selector_supported_tags(tags)
+
normalized_query = query.strip().lower()
if normalized_query:
tags = [tag for tag in tags if normalized_query in tag.lower()]
@@ -280,6 +307,10 @@ def schedule_update(
normalized_tag = tag.strip()
if not normalized_tag:
raise ValueError("A release tag is required.")
+ if not is_valid_selector_tag(normalized_tag):
+ raise ValueError(
+ "Release tag must use the format vX.Y.Z with optional extra segments such as .W or .W-suffix."
+ )
normalized_policy = backup_conflict_policy.strip().lower()
if normalized_policy not in BACKUP_CONFLICT_POLICIES:
diff --git a/extensions/python/banners/_20_missing_api_key.py b/plugins/_model_config/extensions/python/banners/_20_missing_api_key.py
similarity index 100%
rename from extensions/python/banners/_20_missing_api_key.py
rename to plugins/_model_config/extensions/python/banners/_20_missing_api_key.py
diff --git a/plugins/_model_config/webui/api-keys.html b/plugins/_model_config/webui/api-keys.html
index 4189a3d18..6a01e2877 100644
--- a/plugins/_model_config/webui/api-keys.html
+++ b/plugins/_model_config/webui/api-keys.html
@@ -22,6 +22,7 @@
},
async init() {
await $store.modelConfig.ensureLoaded();
+ $store.modelConfig.resetApiKeyDrafts();
await $store.modelConfig.refreshApiKeyStatus();
$store.modelConfig.allProviders.forEach((provider) => {
this.keys[provider.value] = '';
@@ -50,9 +51,7 @@
const updates = {};
for (const provider of Object.keys(this.touched)) {
if (!this.touched[provider]) continue;
- const value = (this.keys[provider] || '').trim();
- if (!value) continue;
- updates[provider] = value;
+ updates[provider] = this.keys[provider] || '';
}
await $store.modelConfig.saveApiKeys(updates);
await $store.modelConfig.refreshApiKeyStatus();
diff --git a/plugins/_model_config/webui/config.html b/plugins/_model_config/webui/config.html
index 591a0679b..1417e888a 100644
--- a/plugins/_model_config/webui/config.html
+++ b/plugins/_model_config/webui/config.html
@@ -10,6 +10,7 @@
<div x-data
x-init="
await $store.modelConfig.ensureLoaded();
+ $store.modelConfig.resetApiKeyDrafts();
await $store.modelConfig.refreshApiKeyStatus();
$store.modelConfig.initConfigFields(config);
$store.modelConfig.installPluginSettingsSaveHook(context, config);
@@ -119,6 +120,7 @@
x-model="$store.modelConfig.apiKeyValues[config[section.key].provider]"
:placeholder="$store.modelConfig.apiKeyStatus[config[section.key].provider] ? '&#x2022;&#x2022;&#x2022;&#x2022;&#x2022;&#x2022;&#x2022;&#x2022;&#x2022;&#x2022;&#x2022;&#x2022;' : ''"
autocomplete="off"
+ @input="$store.modelConfig.touchApiKey(config[section.key].provider)"
style="padding-right:32px;" />
<span class="material-symbols-outlined eye-toggle"
@click="
diff --git a/plugins/_model_config/webui/model-config-store.js b/plugins/_model_config/webui/model-config-store.js
index 867a95f1b..3882e69e6 100644
--- a/plugins/_model_config/webui/model-config-store.js
+++ b/plugins/_model_config/webui/model-config-store.js
@@ -52,6 +52,7 @@ export const store = createStore("modelConfig", {
embeddingProviders: [],
apiKeyStatus: {},
apiKeyValues: {},
+ apiKeyDirty: {},
allProviders: [],
_loaded: false,
@@ -81,6 +82,19 @@ export const store = createStore("modelConfig", {
if (!(provider in this.apiKeyValues)) {
this.apiKeyValues = { ...this.apiKeyValues, [provider]: '' };
}
+ if (!(provider in this.apiKeyDirty)) {
+ this.apiKeyDirty = { ...this.apiKeyDirty, [provider]: false };
+ }
+ },
+
+ _setApiKeyDirty(provider, isDirty) {
+ if (!provider) return;
+ this._ensureApiKeySlot(provider);
+ this.apiKeyDirty = { ...this.apiKeyDirty, [provider]: !!isDirty };
+ },
+
+ touchApiKey(provider) {
+ this._setApiKeyDirty(provider, true);
},
_normalizePresets(rawPresets) {
@@ -98,13 +112,16 @@ export const store = createStore("modelConfig", {
this.embeddingProviders = data.embedding_providers || [];
this.apiKeyStatus = data.api_key_status || {};
const keys = {};
+ const dirty = {};
const seen = new Set();
for (const p of [...this.chatProviders, ...this.embeddingProviders]) {
if (!p.value || seen.has(p.value)) continue;
seen.add(p.value);
if (!(p.value in keys)) keys[p.value] = '';
+ if (!(p.value in dirty)) dirty[p.value] = false;
}
this.apiKeyValues = keys;
+ this.apiKeyDirty = dirty;
const allProviders = [];
const provSeen = new Set();
@@ -131,23 +148,40 @@ export const store = createStore("modelConfig", {
const nextStatus = { ...this.apiKeyStatus };
const nextValues = { ...this.apiKeyValues };
+ const nextDirty = { ...this.apiKeyDirty };
for (const provider of this.allProviders) {
const entry = keys[provider.value] || {};
const hasKey = !!entry.has_key;
nextStatus[provider.value] = hasKey;
provider.has_key = hasKey;
- if (!hasKey && !nextValues[provider.value]) {
+ if (!(provider.value in nextDirty)) {
+ nextDirty[provider.value] = false;
+ }
+ if (!hasKey && !nextDirty[provider.value]) {
nextValues[provider.value] = '';
}
}
this.apiKeyStatus = nextStatus;
this.apiKeyValues = nextValues;
+ this.apiKeyDirty = nextDirty;
this.allProviders = [...this.allProviders];
return keys;
},
+ resetApiKeyDrafts() {
+ const nextValues = {};
+ const nextDirty = {};
+ for (const provider of this.allProviders || []) {
+ if (!provider?.value) continue;
+ nextValues[provider.value] = '';
+ nextDirty[provider.value] = false;
+ }
+ this.apiKeyValues = nextValues;
+ this.apiKeyDirty = nextDirty;
+ },
+
async _fetchConfigData() {
const res = await fetchApi(`${API_BASE}/model_config_get`, {
method: 'POST',
@@ -229,8 +263,7 @@ export const store = createStore("modelConfig", {
const normalized = {};
for (const [provider, value] of Object.entries(updates || {})) {
if (!provider || typeof value !== 'string') continue;
- if (!value.trim()) continue;
- normalized[provider] = value;
+ normalized[provider] = value.trim() ? value : '';
}
if (Object.keys(normalized).length === 0) {
@@ -248,11 +281,14 @@ export const store = createStore("modelConfig", {
}
const nextValues = { ...this.apiKeyValues };
+ const nextDirty = { ...this.apiKeyDirty };
for (const [provider, value] of Object.entries(normalized)) {
nextValues[provider] = value;
- this._setProviderHasKey(provider, true);
+ nextDirty[provider] = false;
+ this._setProviderHasKey(provider, !!value.trim());
}
this.apiKeyValues = nextValues;
+ this.apiKeyDirty = nextDirty;
return data;
},
@@ -261,8 +297,9 @@ export const store = createStore("modelConfig", {
},
saveApiKeyIfSet(provider) {
- const val = this.apiKeyValues[provider];
- if (val) return this.saveApiKey(provider, val);
+ if (provider in this.apiKeyValues) {
+ return this.saveApiKey(provider, this.apiKeyValues[provider] || '');
+ }
},
async revealApiKey(provider) {
@@ -276,23 +313,24 @@ export const store = createStore("modelConfig", {
throw new Error(data?.error || 'Failed to load API key.');
}
const value = data.value || '';
- if (provider && value) {
+ if (provider) {
this._ensureApiKeySlot(provider);
this.apiKeyValues = { ...this.apiKeyValues, [provider]: value };
- this._setProviderHasKey(provider, true);
+ this._setApiKeyDirty(provider, false);
+ this._setProviderHasKey(provider, !!value.trim());
}
return value;
},
async persistApiKeysForConfig(config) {
const updates = {};
+ const seen = new Set();
for (const section of this.MODEL_SECTIONS) {
const provider = config?.[section.key]?.provider;
- if (!provider) continue;
+ if (!provider || seen.has(provider) || !this.apiKeyDirty[provider]) continue;
+ seen.add(provider);
const value = this.apiKeyValues[provider];
- if (typeof value === 'string' && value.trim()) {
- updates[provider] = value;
- }
+ updates[provider] = typeof value === 'string' ? value : '';
}
return this.saveApiKeys(updates);
},
diff --git a/tests/test_model_config_api_keys.py b/tests/test_model_config_api_keys.py
new file mode 100644
index 000000000..f2170871c
--- /dev/null
+++ b/tests/test_model_config_api_keys.py
@@ -0,0 +1,85 @@
+import sys
+import threading
+import types
+from pathlib import Path
+
+from flask import Flask
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+ sys.path.insert(0, str(PROJECT_ROOT))
+
+sys.modules["giturlparse"] = types.SimpleNamespace(parse=lambda *args, **kwargs: None)
+
+
+class _DummyObserver:
+ def __init__(self):
+ self._alive = False
+
+ def is_alive(self):
+ return self._alive
+
+ def start(self):
+ self._alive = True
+
+ def stop(self):
+ self._alive = False
+
+ def join(self, *args, **kwargs):
+ return None
+
+ def unschedule_all(self):
+ return None
+
+ def schedule(self, *args, **kwargs):
+ return None
+
+
+watchdog = types.ModuleType("watchdog")
+watchdog.observers = types.SimpleNamespace(Observer=_DummyObserver)
+watchdog.events = types.SimpleNamespace(FileSystemEventHandler=object)
+sys.modules["watchdog"] = watchdog
+sys.modules["watchdog.observers"] = watchdog.observers
+sys.modules["watchdog.events"] = watchdog.events
+
+from plugins._model_config.api.api_keys import ApiKeys
+import models
+
+
+def test_model_config_api_keys_can_be_cleared_via_backend(monkeypatch, tmp_path):
+ from helpers import dotenv
+
+ env_file = tmp_path / ".env"
+ monkeypatch.setattr(dotenv, "get_dotenv_file_path", lambda: str(env_file))
+
+ for key in ("API_KEY_OPENROUTER", "OPENROUTER_API_KEY", "OPENROUTER_API_TOKEN"):
+ monkeypatch.delenv(key, raising=False)
+
+ handler = ApiKeys(Flask(__name__), threading.Lock())
+
+ assert handler._set_keys({"keys": {"openrouter": "sk-test-openrouter"}}) == {"ok": True}
+ assert models.get_api_key("openrouter") == "sk-test-openrouter"
+
+ assert handler._set_keys({"keys": {"openrouter": ""}}) == {"ok": True}
+ assert models.get_api_key("openrouter") == "None"
+ assert handler._reveal_key({"provider": "openrouter"}) == {"ok": True, "value": ""}
+
+
+def test_model_config_frontend_tracks_inline_api_key_edits():
+ store_path = PROJECT_ROOT / "plugins" / "_model_config" / "webui" / "model-config-store.js"
+ config_path = PROJECT_ROOT / "plugins" / "_model_config" / "webui" / "config.html"
+ modal_path = PROJECT_ROOT / "plugins" / "_model_config" / "webui" / "api-keys.html"
+
+ store_content = store_path.read_text(encoding="utf-8")
+ config_content = config_path.read_text(encoding="utf-8")
+ modal_content = modal_path.read_text(encoding="utf-8")
+
+ assert "apiKeyDirty" in store_content
+ assert "resetApiKeyDrafts()" in store_content
+ assert "!provider || seen.has(provider) || !this.apiKeyDirty[provider]" in store_content
+ assert "normalized[provider] = value.trim() ? value : '';" in store_content
+ assert "$store.modelConfig.resetApiKeyDrafts();" in config_content
+ assert '@input="$store.modelConfig.touchApiKey(config[section.key].provider)"' in config_content
+ assert "updates[provider] = this.keys[provider] || '';" in modal_content
+ assert "$store.modelConfig.resetApiKeyDrafts();" in modal_content
diff --git a/tests/test_self_update_tag_filter.py b/tests/test_self_update_tag_filter.py
new file mode 100644
index 000000000..54540af5b
--- /dev/null
+++ b/tests/test_self_update_tag_filter.py
@@ -0,0 +1,39 @@
+import sys
+import types
+from pathlib import Path
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+ sys.path.insert(0, str(PROJECT_ROOT))
+
+sys.modules["giturlparse"] = types.SimpleNamespace(parse=lambda *args, **kwargs: None)
+
+from helpers import self_update
+
+
+def test_self_update_minimum_selector_tag_is_enforced():
+ assert self_update.is_valid_selector_tag("v0.9.9")
+ assert self_update._is_selector_supported_tag("v0.9.9.0")
+ assert self_update._is_selector_supported_tag("v0.10.0.0")
+ assert self_update.is_valid_selector_tag("v0.9.12.5-pre")
+ assert not self_update.is_valid_selector_tag("0.9.9")
+ assert not self_update.is_valid_selector_tag("v0.9")
+ assert not self_update._is_selector_supported_tag("v0.9.8.9")
+ assert not self_update._is_selector_supported_tag("v0.7.0.0")
+
+
+def test_self_update_frontend_filters_old_tag_suggestions():
+ store_path = (
+ PROJECT_ROOT
+ / "webui"
+ / "components"
+ / "settings"
+ / "external"
+ / "self-update-store.js"
+ )
+ content = store_path.read_text(encoding="utf-8")
+
+ assert "const MIN_SELECTOR_VERSION = [0, 9, 9];" in content
+ assert "response.tags.filter((tag) => this.isSupportedSuggestionTag(tag))" in content
+ assert "if (!this.parseSelectorTag(this.form.tag)) {" in content
diff --git a/webui/components/settings/backup/self-update.html b/webui/components/settings/backup/self-update.html
index 63bbc8b31..6f80552c8 100644
--- a/webui/components/settings/backup/self-update.html
+++ b/webui/components/settings/backup/self-update.html
@@ -4,8 +4,9 @@
</head>
<body>
- <div x-data>
- <div>
+ <div x-data="{ get settings() { return $store.settings.settings } }">
+ <template x-if="settings">
+ <div>
<div class="section-title">Self Update</div>
<div class="field">
@@ -40,12 +41,13 @@
</div>
<div class="field-control">
<label class="toggle">
- <input type="checkbox" x-model="$store.settings.settings.update_check_enabled" />
+ <input type="checkbox" x-model="settings.update_check_enabled" />
<span class="toggler"></span>
</label>
</div>
</div>
- </div>
+ </div>
+ </template>
</div>
</body>
</html>
diff --git a/webui/components/settings/external/self-update-modal.html b/webui/components/settings/external/self-update-modal.html
index 26b930ce7..467d87db1 100644
--- a/webui/components/settings/external/self-update-modal.html
+++ b/webui/components/settings/external/self-update-modal.html
@@ -14,23 +14,35 @@
x-destroy="$store.selfUpdateStore.cleanup()"
class="self-update-modal"
>
- <details class="self-update-howto">
- <summary>How it works?</summary>
- <div class="self-update-copy">
- <p>
- Agent Zero saves this request into
- <code x-text="$store.selfUpdateStore.info?.paths?.update_file || '/exe/a0-self-update.yaml'"></code>,
- restarts once, applies the requested branch and release tag before the UI
- starts again, then reloads this page when <code>/api/health</code> is healthy.
- </p>
- <p>
- If the updated UI does not become healthy within 2 minutes, the bootstrap
- manager in <code>/exe</code> restores the previous checkout and starts that
- version again, so even an older downgraded <code>/a0</code> can be upgraded back
- by creating the YAML file manually.
- </p>
+ <div class="self-update-howto">
+ <button
+ type="button"
+ class="self-update-howto-toggle"
+ data-bs-toggle="collapse"
+ data-bs-target="#self-update-howto-collapse"
+ aria-expanded="false"
+ aria-controls="self-update-howto-collapse"
+ >
+ <span>How it works?</span>
+ <span class="material-symbols-outlined self-update-howto-toggle-icon">expand_more</span>
+ </button>
+ <div class="collapse" id="self-update-howto-collapse">
+ <div class="self-update-howto-body self-update-copy">
+ <p>
+ Agent Zero saves this request into
+ <code x-text="$store.selfUpdateStore.info?.paths?.update_file || '/exe/a0-self-update.yaml'"></code>,
+ restarts once, applies the requested branch and release tag before the UI
+ starts again, then reloads this page when <code>/api/health</code> is healthy.
+ </p>
+ <p>
+ If the updated UI does not become healthy within 2 minutes, the bootstrap
+ manager in <code>/exe</code> restores the previous checkout and starts that
+ version again, so even an older downgraded <code>/a0</code> can be upgraded back
+ by creating the YAML file manually.
+ </p>
+ </div>
</div>
- </details>
+ </div>
<div class="self-update-summary-grid">
<div class="self-update-summary-card">
@@ -98,6 +110,7 @@
<div class="field-control">
<select
x-model="$store.selfUpdateStore.form.branch"
+ x-effect="$nextTick(() => { $el.value = $store.selfUpdateStore.form.branch || 'main'; })"
@change="$store.selfUpdateStore.onBranchChanged()"
:disabled="$store.selfUpdateStore.isBusy"
>
@@ -110,9 +123,11 @@
<div class="field">
<div class="field-label">
- <div class="field-title">Target release tag</div>
+ <div class="field-title">Version</div>
<div class="field-description">
- Start typing to filter, or use the search button to fetch tags from the selected branch. Exact text entry is still allowed, including downgrades.
+ Enter a version tag from the
+ <a href="https://github.com/agent0ai/agent-zero" target="_blank" rel="noreferrer">Agent Zero repository</a>.
+ Start typing to filter, or use the search button to fetch versions from the selected branch. Exact text entry is still allowed, including downgrades.
</div>
<template x-if="$store.selfUpdateStore.tagsError">
<div class="field-description">
@@ -150,7 +165,20 @@
<template x-if="!$store.selfUpdateStore.tagsLoading && $store.selfUpdateStore.tagSuggestions.length === 0">
<div class="self-update-tag-item disabled">No matching tags found</div>
</template>
- <template x-for="tag in $store.selfUpdateStore.tagSuggestions" :key="tag">
+ <template x-for="tag in $store.selfUpdateStore.groupedTagSuggestions.matched" :key="`match-${tag}`">
+ <div
+ class="self-update-tag-item"
+ @click="$store.selfUpdateStore.selectTag(tag)"
+ x-text="tag"
+ ></div>
+ </template>
+ <div
+ class="self-update-tag-separator"
+ x-show="$store.selfUpdateStore.groupedTagSuggestions.matched.length > 0 && $store.selfUpdateStore.groupedTagSuggestions.rest.length > 0"
+ >
+ Other versions
+ </div>
+ <template x-for="tag in $store.selfUpdateStore.groupedTagSuggestions.rest" :key="`rest-${tag}`">
<div
class="self-update-tag-item"
@click="$store.selfUpdateStore.selectTag(tag)"
@@ -161,6 +189,10 @@
</div>
</div>
+ <div class="self-update-warning-banner" x-show="$store.selfUpdateStore.versionCompatibilityWarning">
+ <span x-text="$store.selfUpdateStore.versionCompatibilityWarning"></span>
+ </div>
+
<div class="field">
<div class="field-label">
<div class="field-title">Back up <code>/a0/usr</code> first</div>
@@ -261,7 +293,7 @@
<button
class="btn btn-ok"
@click="$store.selfUpdateStore.scheduleUpdate()"
- :disabled="!$store.selfUpdateStore.isSupported || $store.selfUpdateStore.isBusy"
+ :disabled="!$store.selfUpdateStore.canScheduleUpdate"
>
Schedule Update And Restart
</button>
@@ -300,7 +332,7 @@
right: 0.5rem;
top: 0.55rem;
cursor: pointer;
- color: var(--color-text-secondary, #777);
+ color: var(--color-text-muted);
display: inline-flex;
align-items: center;
justify-content: center;
@@ -312,32 +344,42 @@
max-height: 14rem;
overflow-y: auto;
z-index: 20;
- border: 1px solid var(--color-border, #ddd);
+ border: 1px solid var(--color-border);
border-radius: 0.75rem;
- background: var(--color-surface, #fff);
+ background: var(--color-panel);
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);
}
.self-update-tag-item {
padding: 0.65rem 0.85rem;
cursor: pointer;
+ color: var(--color-text);
}
.self-update-tag-item:hover {
- background: var(--color-panel-bg, rgba(0, 0, 0, 0.04));
+ background: var(--color-background-hover);
}
.self-update-tag-item.disabled {
cursor: default;
- color: var(--color-text-secondary, #777);
+ color: var(--color-text-muted);
}
.self-update-tag-item.disabled:hover {
background: transparent;
}
+ .self-update-tag-separator {
+ padding: 0.45rem 0.85rem;
+ border-top: 1px solid var(--color-border);
+ color: var(--color-text-muted);
+ font-size: 0.85rem;
+ text-transform: uppercase;
+ letter-spacing: 0.04em;
+ }
+
.self-update-copy {
- color: var(--color-text-secondary);
+ color: var(--color-text-muted);
line-height: 1.5;
}
@@ -346,24 +388,36 @@
}
.self-update-howto {
- border: 1px solid var(--color-border, #ddd);
+ border: 1px solid var(--color-border);
border-radius: 0.9rem;
- background: var(--color-surface, #fff);
- padding: 0.9rem 1rem;
+ background: var(--color-panel);
}
- .self-update-howto summary {
+ .self-update-howto-toggle {
+ width: 100%;
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 0.75rem;
+ padding: 0.9rem 1rem;
+ border: 0;
+ background: transparent;
cursor: pointer;
font-weight: 700;
- list-style: none;
+ color: var(--color-text);
+ text-align: left;
+ }
+
+ .self-update-howto-toggle-icon {
+ transition: transform 0.2s ease;
}
- .self-update-howto summary::-webkit-details-marker {
- display: none;
+ .self-update-howto-toggle[aria-expanded="true"] .self-update-howto-toggle-icon {
+ transform: rotate(180deg);
}
- .self-update-howto[open] summary {
- margin-bottom: 0.75rem;
+ .self-update-howto-body {
+ padding: 0 1rem 1rem;
}
.self-update-progress-state {
@@ -373,7 +427,7 @@
padding: 1rem 1.1rem;
border-radius: 0.9rem;
background: rgba(37, 99, 235, 0.08);
- color: var(--color-text, #111827);
+ color: var(--color-text);
}
.self-update-progress-spinner {
@@ -392,10 +446,19 @@
}
.self-update-progress-copy {
- color: var(--color-text-secondary, #475569);
+ color: var(--color-text-muted);
line-height: 1.45;
}
+ .self-update-warning-banner {
+ padding: 0.85rem 0.95rem;
+ border: 1px solid var(--color-warning-text);
+ border-radius: 0.8rem;
+ background: color-mix(in srgb, var(--color-warning-text) 12%, transparent);
+ color: var(--color-warning-text);
+ line-height: 1.5;
+ }
+
.self-update-summary-grid {
display: grid;
gap: 0.75rem;
@@ -407,14 +470,14 @@
border: 1px solid var(--color-border);
border-radius: 10px;
padding: 0.9rem 1rem;
- background: var(--color-bg-secondary);
+ background: var(--color-panel);
}
.summary-label {
font-size: 0.8rem;
text-transform: uppercase;
letter-spacing: 0.04em;
- color: var(--color-text-secondary);
+ color: var(--color-text-muted);
}
.summary-value {
@@ -426,7 +489,7 @@
.summary-meta,
.status-path {
margin-top: 0.35rem;
- color: var(--color-text-secondary);
+ color: var(--color-text-muted);
font-size: 0.9rem;
word-break: break-word;
}
@@ -449,12 +512,12 @@
}
.self-update-loading {
- background: var(--color-bg-secondary);
- color: var(--color-text-secondary);
+ background: var(--color-panel);
+ color: var(--color-text-muted);
}
.self-update-file-hint {
- color: var(--color-text-secondary);
+ color: var(--color-text-muted);
line-height: 1.5;
font-size: 0.95rem;
}
diff --git a/webui/components/settings/external/self-update-store.js b/webui/components/settings/external/self-update-store.js
index 726a66a3e..50b1c9301 100644
--- a/webui/components/settings/external/self-update-store.js
+++ b/webui/components/settings/external/self-update-store.js
@@ -4,9 +4,9 @@ import { store as notificationStore } from "/components/notifications/notificati
const HEALTH_POLL_INTERVAL_MS = 2000;
const HEALTH_WAIT_BUFFER_MS = 30000;
-const TAG_SEARCH_DEBOUNCE_MS = 250;
const SELF_UPDATE_RETURN_URL_KEY = "a0:self-update:return-url";
const SELF_UPDATE_OVERLAY_ID = "self-update-progress-overlay";
+const MIN_SELECTOR_VERSION = [0, 9, 9];
const model = {
loading: false,
@@ -29,7 +29,6 @@ const model = {
backup_conflict_policy: "rename",
},
_reconnectTimer: null,
- _tagSearchTimer: null,
_tagRequestId: 0,
get isBusy() {
@@ -48,13 +47,48 @@ const model = {
return this.info?.current?.branch || "";
},
+ get groupedTagSuggestions() {
+ const tags = Array.isArray(this.tagSuggestions) ? this.tagSuggestions : [];
+ const query = (this.form.tag || "").trim().toLowerCase();
+ if (!query) {
+ return { matched: [], rest: tags };
+ }
+
+ const matched = [];
+ const rest = [];
+ for (const tag of tags) {
+ if ((tag || "").toLowerCase().includes(query)) {
+ matched.push(tag);
+ } else {
+ rest.push(tag);
+ }
+ }
+ return { matched, rest };
+ },
+
+ get versionCompatibilityWarning() {
+ const current = this.parseVersionTag(this.currentVersion);
+ const target = this.parseVersionTag(this.form.tag);
+ if (!current || !target) return "";
+ if (current.epoch !== target.epoch || current.major !== target.major) {
+ return (
+ "Updating across major versions requires downloading a new Docker image, " +
+ "because those releases can include operating system level changes or other breaking changes."
+ );
+ }
+ return "";
+ },
+
+ get canScheduleUpdate() {
+ return this.isSupported && !this.isBusy && !this.versionCompatibilityWarning;
+ },
+
async init() {
await this.refresh();
},
cleanup() {
this.clearReconnectTimer();
- this.clearTagSearchTimer();
this.error = "";
this.tagsError = "";
this.loading = false;
@@ -74,13 +108,6 @@ const model = {
}
},
- clearTagSearchTimer() {
- if (this._tagSearchTimer) {
- clearTimeout(this._tagSearchTimer);
- this._tagSearchTimer = null;
- }
- },
-
formatTimestamp(value) {
if (!value) return "";
try {
@@ -138,7 +165,8 @@ const model = {
alignItems: "center",
justifyContent: "center",
padding: "1.5rem",
- background: "rgba(15, 23, 42, 0.42)",
+ background:
+ "color-mix(in srgb, var(--color-background) 74%, transparent)",
backdropFilter: "blur(6px)",
});
document.body.appendChild(overlay);
@@ -149,19 +177,33 @@ const model = {
#${SELF_UPDATE_OVERLAY_ID} .self-update-progress-card {
width: min(28rem, calc(100vw - 2rem));
border-radius: 1rem;
- background: var(--color-surface, #ffffff);
- color: var(--color-text, #111827);
- box-shadow: 0 24px 64px rgba(15, 23, 42, 0.22);
+ border: 1px solid var(--color-border);
+ background: color-mix(
+ in srgb,
+ var(--color-panel) 92%,
+ var(--color-background)
+ );
+ color: var(--color-text);
+ box-shadow: 0 24px 64px color-mix(
+ in srgb,
+ var(--color-background) 65%,
+ transparent
+ );
padding: 1.5rem;
text-align: center;
+ font-family: var(--font-family-main);
}
#${SELF_UPDATE_OVERLAY_ID} .self-update-progress-spinner {
width: 2.5rem;
height: 2.5rem;
margin: 0 auto 1rem;
border-radius: 999px;
- border: 3px solid rgba(15, 23, 42, 0.12);
- border-top-color: var(--color-primary, #2563eb);
+ border: 3px solid color-mix(
+ in srgb,
+ var(--color-border) 55%,
+ transparent
+ );
+ border-top-color: var(--color-primary);
animation: self-update-spin 1s linear infinite;
}
#${SELF_UPDATE_OVERLAY_ID} .self-update-progress-title {
@@ -170,7 +212,7 @@ const model = {
margin-bottom: 0.5rem;
}
#${SELF_UPDATE_OVERLAY_ID} .self-update-progress-detail {
- color: var(--color-text-secondary, #475569);
+ color: var(--color-text-muted);
line-height: 1.5;
}
@keyframes self-update-spin {
@@ -256,15 +298,6 @@ const model = {
onTagInput() {
this.openTagDropdown();
- this.scheduleTagSearch();
- },
-
- scheduleTagSearch() {
- this.clearTagSearchTimer();
- this._tagSearchTimer = setTimeout(() => {
- this._tagSearchTimer = null;
- void this.searchTags();
- }, TAG_SEARCH_DEBOUNCE_MS);
},
async searchTags({ openResults = true } = {}) {
@@ -275,7 +308,7 @@ const model = {
try {
const response = await API.callJsonApi("self_update_tags", {
branch: this.form.branch,
- query: this.form.tag,
+ query: "",
});
if (!response?.success) {
throw new Error(response?.error || "Failed to fetch release tags.");
@@ -283,7 +316,9 @@ const model = {
if (requestId !== this._tagRequestId) {
return;
}
- this.tagSuggestions = Array.isArray(response?.tags) ? response.tags : [];
+ this.tagSuggestions = Array.isArray(response?.tags)
+ ? response.tags.filter((tag) => this.isSupportedSuggestionTag(tag))
+ : [];
this.tagsError = response?.error || "";
this.tagDropdownOpen = openResults;
} catch (error) {
@@ -306,6 +341,37 @@ const model = {
this.tagDropdownOpen = false;
},
+ parseSelectorTag(value) {
+ const match = /^v(\d+)\.(\d+)\.(\d+)(?:\..+)?$/.exec((value || "").trim());
+ if (!match) return null;
+ return [
+ Number.parseInt(match[1], 10),
+ Number.parseInt(match[2], 10),
+ Number.parseInt(match[3], 10),
+ ];
+ },
+
+ isSupportedSuggestionTag(value) {
+ const parsed = this.parseSelectorTag(value);
+ if (!parsed) return false;
+ for (let i = 0; i < MIN_SELECTOR_VERSION.length; i += 1) {
+ if (parsed[i] > MIN_SELECTOR_VERSION[i]) return true;
+ if (parsed[i] < MIN_SELECTOR_VERSION[i]) return false;
+ }
+ return true;
+ },
+
+ parseVersionTag(value) {
+ const match = /^v(\d+)\.(\d+)\.(\d+)(?:\.(.+))?$/.exec((value || "").trim());
+ if (!match) return null;
+ return {
+ epoch: Number.parseInt(match[1], 10),
+ major: Number.parseInt(match[2], 10),
+ minor: Number.parseInt(match[3], 10),
+ rest: match[4] || "",
+ };
+ },
+
async scheduleUpdate() {
if (!this.form.branch?.trim()) {
this.error = "Choose a branch.";
@@ -317,6 +383,12 @@ const model = {
return;
}
+ if (!this.parseSelectorTag(this.form.tag)) {
+ this.error =
+ "Release tag must use the format vX.Y.Z with optional extra segments such as .W or .W-suffix.";
+ return;
+ }
+
this.saving = true;
this.error = "";
try {