Update Center

The Update Center is an admin-only, informational feature. A customer hxEASM installation checks a Central Update API for release metadata; it does not call GitHub directly.

hxEASM
  -> Central Update API
  -> Private GitHub Releases

The GitHub token is stored only in the Central Update API. Customer installations use only a customer Update Center API key. hxEASM never updates itself automatically, executes shell commands, accesses the Docker socket, runs git pull, or modifies local files.

Configuration

Runtime configuration lives in backend/configs/config.yaml under updates:

updates:
  enabled: true
  center_url: ""
  api_key: ""
  product: hxeasm
  channel: stable
  timeout_seconds: 10
  check_interval_minutes: 360
  current_version: ""

Fields:

Field	Purpose
`enabled`	Enables or disables update checks
`center_url`	Central Update API base URL, for example `https://updates.example.com`
`api_key`	Customer Update Center API key; backend-only secret
`product`	Product identifier, defaults to `hxeasm`
`channel`	Release channel, defaults to `stable`
`timeout_seconds`	HTTP request timeout, defaults to `10`
`check_interval_minutes`	Cache TTL for status checks
`current_version`	Optional override; leave empty to use `app.version`

Environment variables:

EASM_UPDATE_CENTER_URL=https://updates.example.com
EASM_UPDATE_CENTER_APIKEY=
EASM_UPDATE_CENTER_PRODUCT=hxeasm
EASM_UPDATE_CENTER_CHANNEL=stable
EASM_UPDATE_CENTER_TIMEOUT_SECONDS=10

Leave EASM_UPDATE_CENTER_URL or EASM_UPDATE_CENTER_APIKEY empty to disable update checks gracefully. API startup does not fail, and the UI shows Not configured.

Use HTTPS in production. http:// is accepted for local development only. The configured URL must be a base URL without /api/v1/update; hxEASM always requests the fixed /api/v1/update path.

EASM_UPDATES_GITHUB_TOKEN is deprecated and ignored. If it is present, the API logs a safe warning without printing the value.

Current Version

The backend exposes the current version through the existing version endpoint and uses it for update checks. In normal deployments, set only app.version; leave updates.current_version empty.

Versions such as 0.1.7 Vega are normalized before calling the Central Update API:

0.1.7 Vega -> 0.1.7
v0.1.7    -> v0.1.7
0.1.7     -> 0.1.7

The codename is not sent to the update service.

Central Update API Request

hxEASM calls:

GET {EASM_UPDATE_CENTER_URL}/api/v1/update?product=hxeasm&current_version=0.1.7&channel=stable
Authorization: Bearer <EASM_UPDATE_CENTER_APIKEY>
Accept: application/json

The browser never calls the Central Update API directly. The API key is never returned through /api/v1/admin/updates/* or placed in frontend environment variables.

Local API

Admin-only local endpoints remain:

GET  /api/v1/admin/updates/status
POST /api/v1/admin/updates/check

status uses the configured cache interval. check forces a refresh through the Central Update API.

Example local response:

{
  "enabled": true,
  "configured": true,
  "current_version": "0.1.7",
  "latest_version": "v0.2.0",
  "update_available": true,
  "cache_status": "refreshed",
  "release_name": "hxEASM v0.2.0",
  "release_notes": "Release notes from GitHub.",
  "release_url": "",
  "published_at": "2026-08-04T10:00:00Z",
  "checked_at": "2026-08-04T12:00:00Z",
  "error": ""
}

If the Central Update API does not expose a safe public release URL, release_url is empty and the frontend hides the GitHub release button.

Error Handling

Central Update API errors are mapped to safe admin UI messages:

Condition	UI message
Missing URL or API key	`Update Center is not configured`
Invalid local URL/config	`invalid Update Center configuration`
`400`	`invalid update request or local configuration`
`401`	`invalid Update Center API key`
`403`	`this customer key cannot access the hxeasm product`
`404`	`product or release not found`
`429`	`Update Center rate limit exceeded`
`502`	`release metadata temporarily unavailable`
Timeout	`Update Center request timed out`
Connection failure	`Update Center unavailable`

cache_status may be fresh, refreshed, or stale. Stale metadata is shown as a warning, not a hard failure, if the response is otherwise valid.

UI Behavior

Admins see Update Center in Settings under Administration.

The panel shows:

current version
latest version
status badge
last checked time
release notes in a collapsible section
optional release link if supplied by the Central Update API
Check now button
copyable update commands

Admins also see a top banner when an update is available. The banner is not shown to hacker or client users.

Manual Update Commands

The UI only copies commands. It never executes them.

Source deployment:

git pull && docker compose up -d --build

Image deployment:

docker compose pull && docker compose up -d

Why One-Click Update Is Not Implemented

Self-updating a running security platform is risky. It would require command execution, write access to the deployment directory, process restarts, and possibly Docker socket access. Those capabilities increase the blast radius of any admin session compromise or implementation bug.

Update Center remains read-only and informational. Operators remain in control of when and how updates are applied.