OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
self-hosting: openpanel upgrade with checksum-verified self-update
Carl-Gerhard Lindesvärd7cc701f6a8b5
diff --git a/self-hosting/cli/src/commands/compose.ts b/self-hosting/cli/src/commands/compose.tsindex 85270e438..b02a72838 100644--- a/self-hosting/cli/src/commands/compose.ts+++ b/self-hosting/cli/src/commands/compose.ts@@ -6,6 +6,7 @@ const ARGS = {restart: ['up', '-d', '--force-recreate'],logs: ['logs', '-f', '--tail', '200'],status: ['ps'],+ pull: ['pull'],} as const;export type ComposeCommand = keyof typeof ARGS;diff --git a/self-hosting/cli/src/commands/upgrade.ts b/self-hosting/cli/src/commands/upgrade.tsnew file mode 100644index 000000000..4e64a3913--- /dev/null+++ b/self-hosting/cli/src/commands/upgrade.ts@@ -0,0 +1,129 @@+import { cancel, log as clackLog, confirm, isCancel } from '@clack/prompts';+import { applyFixes, type Finding, runDoctor } from '../doctor';+import { checkHost } from '../host';+import { isInstallDir, loadInstall, writeInstall } from '../install';+import { run } from '../run';+import { isCompiledBinary, selfUpdate } from '../self-update';+import { bold, dim, SEVERITY_LABEL } from '../ui';+import { VERSION } from '../version';+import { compose } from './compose';++const DRAIN_FINDING_ID = 'upgrade/drain-old-queue';+const NO_SELF_UPDATE_FLAG = '--no-self-update';++export interface UpgradeFlags {+ dir: string;+ yes: boolean;+ noSelfUpdate: boolean;+}++const ask = async (message: string, yes: boolean): Promise<boolean> => {+ if (yes) {+ return true;+ }+ const answer = await confirm({ message, initialValue: false });+ if (isCancel(answer)) {+ cancel('Cancelled. Nothing was changed.');+ process.exit(0);+ }+ return answer;+};++// Returns an exit code when the CLI replaced itself and the new one took over,+// so the doctor checks and templates that run are the new release's.+const updateSelf = async (): Promise<number | null> => {+ try {+ const result = await selfUpdate({+ currentVersion: VERSION,+ execPath: process.execPath,+ fetcher: fetch,+ });+ if (result.status === 'current') {+ return null;+ }+ clackLog.success(`Updated the CLI ${result.from} → ${result.to}`);+ const args = [...process.argv.slice(2), NO_SELF_UPDATE_FLAG];+ return (await run([process.execPath, ...args], { inherit: true })).code;+ } catch (error) {+ // Offline or rate-limited: upgrading the stack with this version still works.+ clackLog.warn(`Skipped CLI self-update: ${(error as Error).message}`);+ return null;+ }+};++const listFindings = (findings: Finding[]) => {+ for (const finding of findings) {+ clackLog.message(`${SEVERITY_LABEL[finding.severity]} ${finding.title}`);+ }+};++export const upgrade = async (flags: UpgradeFlags): Promise<number> => {+ if (!flags.noSelfUpdate && isCompiledBinary()) {+ const handedOver = await updateSelf();+ if (handedOver !== null) {+ return handedOver;+ }+ }++ if (!isInstallDir(flags.dir)) {+ clackLog.error(`No install in ${flags.dir}. Run \`openpanel init\` first.`);+ return 1;+ }+ const hostProblems = (await checkHost()).filter(+ (check) => !check.ok && check.id !== 'host/memory'+ );+ if (hostProblems.length > 0) {+ for (const problem of hostProblems) {+ clackLog.error(+ `${problem.title}${problem.hint ? `\n ${dim(problem.hint)}` : ''}`+ );+ }+ return 1;+ }++ const install = loadInstall(flags.dir);+ const findings = runDoctor(install);++ if (findings.some((finding) => finding.id === DRAIN_FINDING_ID)) {+ clackLog.warn(+ `${bold('Upgrading from v1.')} Events still queued in Redis are not moved to Redpanda. Stop tracking traffic and let the old worker drain first.`+ );+ if (!(await ask('Has the old event queue drained?', flags.yes))) {+ clackLog.info('Come back once it has. Nothing was changed.');+ return 1;+ }+ }++ const fixable = findings.filter((finding) => finding.fix);+ if (fixable.length > 0) {+ listFindings(fixable);+ if (+ !(await ask(+ `Apply ${fixable.length} fix(es)? Originals are kept as <name>.bak`,+ flags.yes+ ))+ ) {+ return 1;+ }+ applyFixes(install);+ const written = await writeInstall(flags.dir, install);+ clackLog.success(`Updated ${written.join(', ')}`);+ }++ const blocking = findings.filter(+ (finding) => finding.severity === 'error' && !finding.fix+ );+ if (blocking.length > 0) {+ listFindings(blocking);+ clackLog.error(+ 'These need you before the stack can start. See `openpanel doctor`.'+ );+ return 1;+ }++ const pulled = await compose('pull', flags.dir);+ if (pulled !== 0) {+ return pulled;+ }+ return compose('up', flags.dir, ['--remove-orphans']);+};diff --git a/self-hosting/cli/src/main.ts b/self-hosting/cli/src/main.tsindex 270889cc7..c547d6c86 100644--- a/self-hosting/cli/src/main.ts+++ b/self-hosting/cli/src/main.ts@@ -4,10 +4,11 @@ import { parseArgs } from 'node:util';import { compose, isComposeCommand } from './commands/compose';import { doctor } from './commands/doctor';import { init } from './commands/init';+import { upgrade } from './commands/upgrade';import { isInstallDir } from './install';import { log } from './ui';+import { VERSION } from './version';-const VERSION = '0.1.0';const DEFAULT_DIR = join(homedir(), 'openpanel');const HELP = `openpanel ${VERSION} — run and maintain a self-hosted OpenPanel@@ -16,6 +17,7 @@ Usage: openpanel <command> [options]Commands:init Interactive setup (--yes --domain <url> to skip prompts)+ upgrade [--yes] Update the CLI, repair the install, pull images, restartdoctor [--fix] [--check] Check the host and your install; --fix repairs itup | down | restart Start, stop, or recreate the stacklogs [service] Follow logs@@ -48,6 +50,7 @@ const main = async (): Promise<number> => {fix: { type: 'boolean', default: false },yes: { type: 'boolean', short: 'y', default: false },force: { type: 'boolean', default: false },+ 'no-self-update': { type: 'boolean', default: false },domain: { type: 'string' },proxy: { type: 'string' },workers: { type: 'string' },@@ -90,6 +93,13 @@ const main = async (): Promise<number> => {emailSender: values['email-sender'],});}+ if (command === 'upgrade') {+ return upgrade({+ dir,+ yes: values.yes,+ noSelfUpdate: values['no-self-update'],+ });+ }if (command === 'doctor') {return doctor({ dir, fix: values.fix, check: values.check });}diff --git a/self-hosting/cli/src/self-update.ts b/self-hosting/cli/src/self-update.tsnew file mode 100644index 000000000..263a2df6f--- /dev/null+++ b/self-hosting/cli/src/self-update.ts@@ -0,0 +1,139 @@+import { createHash } from 'node:crypto';+import { chmod, rename, writeFile } from 'node:fs/promises';+import { basename } from 'node:path';++// CLI releases live next to the product's own, so they are told apart by tag.+const RELEASE_TAG_PREFIX = 'cli-v';+const RELEASES_API =+ process.env.OPENPANEL_RELEASES_API ??+ 'https://api.github.com/repos/Openpanel-dev/openpanel/releases?per_page=30';+const CHECKSUMS_ASSET = 'checksums.txt';+const EXECUTABLE_MODE = 0o755;++export type Fetcher = (url: string) => Promise<Response>;++export interface Release {+ version: string;+ assets: Record<string, string>;+}++export const assetName = (platform: string, arch: string): string =>+ `openpanel-${platform}-${arch}`;++// `sha256sum` output: "<hex> <file>" per line.+export const parseChecksums = (text: string): Map<string, string> => {+ const checksums = new Map<string, string>();+ for (const line of text.split('\n')) {+ const match = /^([0-9a-f]{64})\s+\*?(\S+)$/i.exec(line.trim());+ if (match) {+ checksums.set(match[2] as string, (match[1] as string).toLowerCase());+ }+ }+ return checksums;+};++const parts = (version: string) =>+ version.split('.').map((part) => Number.parseInt(part, 10) || 0);++export const isNewer = (latest: string, current: string): boolean => {+ const a = parts(latest);+ const b = parts(current);+ for (let index = 0; index < Math.max(a.length, b.length); index++) {+ const difference = (a[index] ?? 0) - (b[index] ?? 0);+ if (difference !== 0) {+ return difference > 0;+ }+ }+ return false;+};++// `bun src/main.ts` runs under the bun binary, which must never overwrite itself.+export const isCompiledBinary = (execPath = process.execPath): boolean =>+ !basename(execPath).toLowerCase().startsWith('bun');++interface ReleaseJson {+ tag_name: string;+ draft: boolean;+ prerelease: boolean;+ assets: { name: string; browser_download_url: string }[];+}++export const fetchLatestRelease = async (+ fetcher: Fetcher+): Promise<Release | null> => {+ const response = await fetcher(RELEASES_API);+ if (!response.ok) {+ throw new Error(`Could not list releases (HTTP ${response.status})`);+ }+ const releases = (await response.json()) as ReleaseJson[];+ const latest = releases.find(+ (release) =>+ release.tag_name.startsWith(RELEASE_TAG_PREFIX) &&+ !release.draft &&+ !release.prerelease+ );+ if (!latest) {+ return null;+ }+ return {+ version: latest.tag_name.slice(RELEASE_TAG_PREFIX.length),+ assets: Object.fromEntries(+ latest.assets.map((asset) => [asset.name, asset.browser_download_url])+ ),+ };+};++export type UpdateResult =+ | { status: 'current'; version: string }+ | { status: 'updated'; from: string; to: string };++interface UpdateOptions {+ currentVersion: string;+ execPath: string;+ fetcher: Fetcher;+ platform?: string;+ arch?: string;+}++// Download, verify, then swap in one rename, so a failed or corrupt download+// can never leave a half-written binary in place.+export const selfUpdate = async ({+ currentVersion,+ execPath,+ fetcher,+ platform = process.platform,+ arch = process.arch,+}: UpdateOptions): Promise<UpdateResult> => {+ const release = await fetchLatestRelease(fetcher);+ if (!(release && isNewer(release.version, currentVersion))) {+ return { status: 'current', version: currentVersion };+ }++ const name = assetName(platform, arch);+ const binaryUrl = release.assets[name];+ const checksumsUrl = release.assets[CHECKSUMS_ASSET];+ if (!(binaryUrl && checksumsUrl)) {+ throw new Error(+ `Release ${release.version} has no ${name} or ${CHECKSUMS_ASSET}`+ );+ }++ const expected = parseChecksums(+ await (await fetcher(checksumsUrl)).text()+ ).get(name);+ const download = await fetcher(binaryUrl);+ if (!(expected && download.ok)) {+ throw new Error(`Could not download ${name} ${release.version}`);+ }+ const bytes = new Uint8Array(await download.arrayBuffer());+ const actual = createHash('sha256').update(bytes).digest('hex');+ if (actual !== expected) {+ throw new Error(`Checksum mismatch for ${name}; refusing to install it`);+ }++ const staged = `${execPath}.new`;+ await writeFile(staged, bytes);+ await chmod(staged, EXECUTABLE_MODE);+ await rename(staged, execPath);+ return { status: 'updated', from: currentVersion, to: release.version };+};diff --git a/self-hosting/cli/src/version.ts b/self-hosting/cli/src/version.tsnew file mode 100644index 000000000..457ca268c--- /dev/null+++ b/self-hosting/cli/src/version.ts@@ -0,0 +1,3 @@+import pkg from '../package.json' with { type: 'json' };++export const VERSION: string = pkg.version;diff --git a/self-hosting/cli/test/self-update.test.ts b/self-hosting/cli/test/self-update.test.tsnew file mode 100644index 000000000..4142b39de--- /dev/null+++ b/self-hosting/cli/test/self-update.test.ts@@ -0,0 +1,152 @@+import { afterEach, describe, expect, test } from 'bun:test';+import { createHash } from 'node:crypto';+import {+ existsSync,+ mkdtempSync,+ readFileSync,+ rmSync,+ writeFileSync,+} from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import {+ assetName,+ type Fetcher,+ isCompiledBinary,+ isNewer,+ parseChecksums,+ selfUpdate,+} from '../src/self-update';++const tempDirs: string[] = [];+afterEach(() => {+ for (const dir of tempDirs.splice(0)) {+ rmSync(dir, { recursive: true, force: true });+ }+});++const NEW_BINARY = 'new-binary-bytes';+const sha256 = (value: string) =>+ createHash('sha256').update(value).digest('hex');++// A fake release feed: one cli release, a binary and its checksums.+const fakeFetcher = (+ options: { tag?: string; checksum?: string } = {}+): Fetcher => {+ const name = assetName('linux', 'x64');+ const base = 'https://example.test';+ const release = {+ tag_name: options.tag ?? 'cli-v0.2.0',+ draft: false,+ prerelease: false,+ assets: [+ { name, browser_download_url: `${base}/${name}` },+ { name: 'checksums.txt', browser_download_url: `${base}/checksums.txt` },+ ],+ };+ return async (url) => {+ if (url.includes('/releases')) {+ return Response.json([+ { tag_name: 'v2.9.0', draft: false, prerelease: false, assets: [] },+ release,+ ]);+ }+ if (url.endsWith('checksums.txt')) {+ return new Response(+ `${options.checksum ?? sha256(NEW_BINARY)} ${name}\n`+ );+ }+ return new Response(NEW_BINARY);+ };+};++const installedBinary = () => {+ const dir = mkdtempSync(join(tmpdir(), 'op-update-'));+ tempDirs.push(dir);+ const path = join(dir, 'openpanel');+ writeFileSync(path, 'old-binary-bytes');+ return path;+};++describe('version helpers', () => {+ test('isNewer compares numerically, not lexically', () => {+ expect(isNewer('0.10.0', '0.9.0')).toBe(true);+ expect(isNewer('1.0.0', '1.0.0')).toBe(false);+ expect(isNewer('0.1.0', '0.2.0')).toBe(false);+ });++ test('parseChecksums reads sha256sum output', () => {+ const hash = sha256('x');+ const parsed = parseChecksums(+ `${hash} openpanel-linux-x64\n${hash} *openpanel-darwin-arm64\nnoise\n`+ );+ expect(parsed.get('openpanel-linux-x64')).toBe(hash);+ expect(parsed.get('openpanel-darwin-arm64')).toBe(hash);+ expect(parsed.size).toBe(2);+ });++ test('running under the bun binary is not a compiled install', () => {+ expect(isCompiledBinary('/usr/local/bin/bun')).toBe(false);+ expect(isCompiledBinary('/usr/local/bin/openpanel')).toBe(true);+ });+});++describe('selfUpdate', () => {+ test('replaces the binary when the checksum matches', async () => {+ const execPath = installedBinary();+ const result = await selfUpdate({+ currentVersion: '0.1.0',+ execPath,+ fetcher: fakeFetcher(),+ platform: 'linux',+ arch: 'x64',+ });++ expect(result).toEqual({ status: 'updated', from: '0.1.0', to: '0.2.0' });+ expect(readFileSync(execPath, 'utf8')).toBe(NEW_BINARY);+ expect(existsSync(`${execPath}.new`)).toBe(false);+ });++ test('a checksum mismatch leaves the installed binary untouched', async () => {+ const execPath = installedBinary();+ const fetcher = fakeFetcher({ checksum: sha256('something else') });++ await expect(+ selfUpdate({+ currentVersion: '0.1.0',+ execPath,+ fetcher,+ platform: 'linux',+ arch: 'x64',+ })+ ).rejects.toThrow('Checksum mismatch');+ expect(readFileSync(execPath, 'utf8')).toBe('old-binary-bytes');+ expect(existsSync(`${execPath}.new`)).toBe(false);+ });++ test('already on the latest version does nothing', async () => {+ const execPath = installedBinary();+ const result = await selfUpdate({+ currentVersion: '0.2.0',+ execPath,+ fetcher: fakeFetcher(),+ platform: 'linux',+ arch: 'x64',+ });++ expect(result).toEqual({ status: 'current', version: '0.2.0' });+ expect(readFileSync(execPath, 'utf8')).toBe('old-binary-bytes');+ });++ test('product releases without the cli- prefix are ignored', async () => {+ const execPath = installedBinary();+ const result = await selfUpdate({+ currentVersion: '0.1.0',+ execPath,+ fetcher: fakeFetcher({ tag: 'v9.9.9' }),+ platform: 'linux',+ arch: 'x64',+ });+ expect(result.status).toBe('current');+ });+});