Skip to content

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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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, restart
doctor [--fix] [--check] Check the host and your install; --fix repairs it
up | down | restart Start, stop, or recreate the stack
logs [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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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');
+ });
+});