Skip to content

Update Center

The Update Center is an admin-only, informational feature that checks GitHub Releases and reports whether a newer hxEASM version is available.

It does not update the application automatically. It does not execute shell commands, access the Docker socket, run git pull, or modify local files.

Configuration

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

updates:
  enabled: true
  github_owner: ""
  github_repo: ""
  github_token: ""
  check_interval_minutes: 360
  current_version: ""
  allow_prereleases: false

Fields:

Field Purpose
enabled Enables or disables release checks
github_owner GitHub repository owner or organization
github_repo GitHub repository name
github_token Optional GitHub token for private repositories; prefer EASM_UPDATES_GITHUB_TOKEN
check_interval_minutes Cache TTL for background/status checks
current_version Optional override; leave empty to use app.version
allow_prereleases Allows prerelease versions to be considered when supported

If github_owner or github_repo are empty, update checking is disabled gracefully and the UI shows a disabled/check-failed state instead of affecting app startup.

Private Repositories

For private GitHub repositories, configure a fine-grained GitHub token with read-only access to repository metadata/releases. Prefer an environment variable so the token is not committed:

EASM_UPDATES_GITHUB_TOKEN=github_pat_...

Because config keys map to EASM_ environment variables, this overrides:

updates:
  github_token: ""

You can also place github_token in a private, uncommitted runtime config file, but do not commit tokens to the repository. The backend uses this token only for the GitHub API request and never returns it through /api/v1/admin/updates/* or the frontend UI.

Current Version

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

Current version is selected in this order:

  1. Go build-time value, if supplied with ldflags such as -X main.version=v0.1.5.
  2. updates.current_version, if explicitly configured.
  3. app.version from config.

For normal releases, leave updates.current_version empty and update only app.version.

GitHub Release Check

The backend calls:

GET https://api.github.com/repos/{owner}/{repo}/releases/latest

It parses:

  • tag_name
  • name
  • body
  • html_url
  • published_at
  • prerelease
  • draft

Draft releases are ignored. Prereleases are ignored unless allowed by configuration.

GitHub errors and network failures are non-fatal. They are returned in the update status response and displayed in the UI.

Common 404 causes:

  • github_owner or github_repo does not exactly match the repository path
  • the repository is private and the configured token is missing, expired, or does not have access to that repository
  • the API container was not recreated after adding EASM_UPDATES_GITHUB_TOKEN
  • the repository has tags but no published GitHub Release
  • the only releases are draft releases or prereleases while allow_prereleases is disabled

For GitHub Releases, a tag alone is not enough. Publish a release from the GitHub Releases tab, for example v0.1.5, so /releases/latest can return it.

API

Admin-only endpoints:

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

status uses the configured cache interval. check forces a refresh from GitHub.

Example response:

{
  "enabled": true,
  "current_version": "v0.1.5",
  "latest_version": "v0.1.6",
  "update_available": true,
  "release_name": "v0.1.6 Polaris",
  "release_notes": "...",
  "release_url": "https://github.com/example/hxEASM/releases/tag/v0.1.6",
  "published_at": "2026-06-09T10:00:00Z",
  "checked_at": "2026-06-09T12:00:00Z",
  "error": ""
}

Version Comparison

Version comparison is intentionally small and dependency-free:

  • strips a leading v
  • ignores suffixes such as Polaris, build metadata, or prerelease text for numeric comparison
  • compares semantic version parts numerically, so v0.1.10 is newer than v0.1.9
  • falls back to string inequality if parsing fails

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
  • GitHub release link
  • Check now button
  • copyable update commands

Admins also see a top banner when an update is available:

New version available: v0.1.6

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.

The first version of Update Center is therefore read-only and informational. Operators remain in control of when and how updates are applied.