Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

feat(self-hosting): upgrade asks what to do with each image

Carl-Gerhard Lindesvärd1b7520c8a3e4
diff --git a/self-hosting/cli/src/commands/upgrade.ts b/self-hosting/cli/src/commands/upgrade.ts
index da6b86e4d..01f61a711 100644
--- a/self-hosting/cli/src/commands/upgrade.ts
+++ b/self-hosting/cli/src/commands/upgrade.ts
@@ -1,6 +1,8 @@
import { cancel, log as clackLog, confirm, isCancel } from '@clack/prompts';
import { applyFixes, type Finding, type Install, runDoctor } from '../doctor';
+import { IMAGE_TAG_CHECK_ID } from '../doctor/checks';
import { checkHost } from '../host';
+import { applyImage, chooseImage, imageDecisions } from '../image-choice';
import { isInstallDir, loadInstall, writeInstall } from '../install';
import { run } from '../run';
import { type Fetcher, isCompiledBinary, selfUpdate } from '../self-update';
@@ -11,10 +13,10 @@ import {
isLoggedIn,
LOGIN_HINT,
latestBuildVersion,
- pointAt,
publicVersion,
SUPPORTER_REGISTRY,
} from '../supporter';
+import { STACK_IMAGE_TAG } from '../templates';
import { bold, dim, SEVERITY_LABEL } from '../ui';
import { VERSION } from '../version';
import { compose } from './compose';
@@ -118,13 +120,13 @@ const confirmQueueDrained = async (flags: UpgradeFlags): Promise<boolean> => {
return ask('Has the old event queue drained?', false);
};
+// The version this upgrade installs: the newest build for supporters, this
+// CLI's own version otherwise. A dev build has none, so it only changes images
+// when told to (--public), using the template's tag.
const targetImageVersion = async (
channel: Channel,
- managesImages: boolean
+ explicitPublic: boolean
): Promise<string | null> => {
- if (!managesImages) {
- return null;
- }
if (channel === 'supporter') {
const version = await latestBuildVersion(fetchWithTimeout);
clackLog.info(
@@ -132,8 +134,10 @@ const targetImageVersion = async (
);
return version;
}
- const version = publicVersion();
- clackLog.info(`Public release images: ${version}`);
+ const version = STACK_IMAGE_TAG ?? (explicitPublic ? publicVersion() : null);
+ if (version !== null) {
+ clackLog.info(`Public release images: ${version}`);
+ }
return version;
};
@@ -204,12 +208,7 @@ export const upgrade = async (flags: UpgradeFlags): Promise<number> => {
);
return 1;
}
- // The image line only changes channel when asked (--supporter / --public),
- // or to follow the newest build on the supporter channel. Otherwise the tag is
- // doctor's business, which only ever moves OpenPanel's own Docker Hub images:
- // an install running its own build or a mirror keeps its images.
- const managesImages = channel === 'supporter' || flags.public;
- const version = await targetImageVersion(channel, managesImages);
+ const version = await targetImageVersion(channel, flags.public);
const findings = runDoctor(install);
@@ -223,10 +222,20 @@ export const upgrade = async (flags: UpgradeFlags): Promise<number> => {
// Everything is applied in memory first, so the list below is exactly what
// gets written, and declining leaves the files untouched.
- const fixable = findings.filter((finding) => finding.fix);
- applyFixes(install);
- const imageChanges =
- version === null ? [] : pointAt(install, channel, version);
+ // Images are a question (keep, take the new one, or type another) rather
+ // than doctor's automatic fix, so an install on its own build or a mirror is
+ // never switched without asking.
+ const fixable = findings.filter(
+ (finding) => finding.fix && finding.id !== IMAGE_TAG_CHECK_ID
+ );
+ applyFixes(install, { skip: [IMAGE_TAG_CHECK_ID] });
+ const imageChanges: string[] = [];
+ for (const decision of version === null
+ ? []
+ : imageDecisions(install, channel, version)) {
+ const image = await chooseImage(decision, flags.yes);
+ imageChanges.push(...applyImage(install, decision, image));
+ }
const changeCount = fixable.length + imageChanges.length;
if (changeCount > 0) {
listFindings(fixable);
diff --git a/self-hosting/cli/src/doctor/checks.ts b/self-hosting/cli/src/doctor/checks.ts
index 1baf070d5..fa909f5f9 100644
--- a/self-hosting/cli/src/doctor/checks.ts
+++ b/self-hosting/cli/src/doctor/checks.ts
@@ -222,6 +222,8 @@ const staleImages = (install: Install, stack: string) =>
// changes it makes only work with the images it was released for. Images from
// other registries (supporter builds, forks) are never touched, and neither is
// anything when there is no version to target (a dev build).
+export const IMAGE_TAG_CHECK_ID = 'compose/image-tag';
+
export const imageTagFor =
(stack: string | null): Check =>
(install) => {
@@ -236,7 +238,7 @@ export const imageTagFor =
.map(({ service, tag }) => `${service} ${tag} → ${stack}`)
.join(', ');
return {
- id: 'compose/image-tag',
+ id: IMAGE_TAG_CHECK_ID,
severity: 'error',
title: `OpenPanel images move to :${stack} (${changes})`,
detail: `This CLI release targets :${stack}; the compose changes it makes only work with those images.`,
diff --git a/self-hosting/cli/src/doctor/index.ts b/self-hosting/cli/src/doctor/index.ts
index 5185aa9b1..420792727 100644
--- a/self-hosting/cli/src/doctor/index.ts
+++ b/self-hosting/cli/src/doctor/index.ts
@@ -8,11 +8,15 @@ export const runDoctor = (install: Install): Finding[] =>
// Fixes run one at a time against live state, in check order, so a later fix
// sees the result of an earlier one (the worker image before its role).
-export const applyFixes = (install: Install): Finding[] => {
+// `skip` leaves findings to the caller, e.g. `upgrade` asks about images itself.
+export const applyFixes = (
+ install: Install,
+ { skip = [] }: { skip?: string[] } = {}
+): Finding[] => {
const applied: Finding[] = [];
for (const check of checks) {
const finding = check(install);
- if (!finding?.fix) {
+ if (!finding?.fix || skip.includes(finding.id)) {
continue;
}
finding.fix(install);
diff --git a/self-hosting/cli/src/image-choice.ts b/self-hosting/cli/src/image-choice.ts
new file mode 100644
index 000000000..dd5fd7da4
--- /dev/null
+++ b/self-hosting/cli/src/image-choice.ts
@@ -0,0 +1,127 @@
+import { cancel, isCancel, select, text } from '@clack/prompts';
+import type { Install } from './doctor/types';
+import {
+ type Channel,
+ publicImage,
+ SUPPORTER_REGISTRY,
+ supporterImage,
+} from './supporter';
+
+// The worker runs the api image, so the two are one decision.
+const IMAGE_GROUPS = [
+ { app: 'api', services: ['op-api', 'op-worker'] },
+ { app: 'dashboard', services: ['op-dashboard'] },
+] as const;
+
+// Images OpenPanel publishes; anything else is someone's own build or mirror.
+const OFFICIAL_PREFIXES = ['lindesvard/openpanel-', `${SUPPORTER_REGISTRY}/`];
+
+export interface ImageDecision {
+ services: string[];
+ current: string;
+ proposed: string;
+}
+
+export const isOfficialImage = (image: string): boolean =>
+ OFFICIAL_PREFIXES.some((prefix) => image.startsWith(prefix));
+
+export const proposedImage = (
+ channel: Channel,
+ app: string,
+ version: string
+): string =>
+ channel === 'supporter'
+ ? supporterImage(app, version)
+ : publicImage(app, version);
+
+const imageOf = (install: Install, service: string): string =>
+ String(install.compose.getIn(['services', service, 'image']) ?? '');
+
+// One decision per image this upgrade would change.
+export const imageDecisions = (
+ install: Install,
+ channel: Channel,
+ version: string
+): ImageDecision[] =>
+ IMAGE_GROUPS.flatMap(({ app, services }) => {
+ const present = services.filter((service) =>
+ install.compose.hasIn(['services', service])
+ );
+ const [first] = present;
+ if (!first) {
+ return [];
+ }
+ const proposed = proposedImage(channel, app, version);
+ const upToDate = present.every(
+ (service) => imageOf(install, service) === proposed
+ );
+ return upToDate
+ ? []
+ : [{ services: present, current: imageOf(install, first), proposed }];
+ });
+
+// Without a person to ask (--yes): move OpenPanel's own images, keep any other.
+export const defaultImage = (decision: ImageDecision): string =>
+ isOfficialImage(decision.current) ? decision.proposed : decision.current;
+
+const answer = <T>(value: T | symbol): T => {
+ if (isCancel(value)) {
+ cancel('Cancelled. Nothing was changed.');
+ process.exit(0);
+ }
+ return value as T;
+};
+
+const NO_WHITESPACE = /^\S+$/;
+
+export const chooseImage = async (
+ decision: ImageDecision,
+ yes: boolean
+): Promise<string> => {
+ if (yes) {
+ return defaultImage(decision);
+ }
+ const choice = answer(
+ await select({
+ message: `${decision.services.join(', ')} run ${decision.current}. This upgrade uses ${decision.proposed}.`,
+ initialValue:
+ defaultImage(decision) === decision.proposed ? 'new' : 'keep',
+ options: [
+ { value: 'new', label: `Use ${decision.proposed}` },
+ { value: 'keep', label: `Keep ${decision.current}` },
+ { value: 'custom', label: 'Use a different image…' },
+ ],
+ })
+ );
+ if (choice === 'new') {
+ return decision.proposed;
+ }
+ if (choice === 'keep') {
+ return decision.current;
+ }
+ return answer(
+ await text({
+ message: `Image for ${decision.services.join(', ')}`,
+ initialValue: decision.current,
+ validate: (value) =>
+ value && NO_WHITESPACE.test(value)
+ ? undefined
+ : 'Enter an image reference, e.g. registry/name:tag',
+ })
+ );
+};
+
+// Returns a line per service that changed, for the confirmation list.
+export const applyImage = (
+ install: Install,
+ decision: ImageDecision,
+ image: string
+): string[] =>
+ decision.services.flatMap((service) => {
+ const current = imageOf(install, service);
+ if (current === image) {
+ return [];
+ }
+ install.compose.setIn(['services', service, 'image'], image);
+ return [`${service}: ${current} → ${image}`];
+ });
diff --git a/self-hosting/cli/src/supporter.ts b/self-hosting/cli/src/supporter.ts
index 97afc1d79..c0c998eb4 100644
--- a/self-hosting/cli/src/supporter.ts
+++ b/self-hosting/cli/src/supporter.ts
@@ -15,13 +15,6 @@ const TAGS_API =
'https://api.github.com/repos/Openpanel-dev/openpanel/tags?per_page=100';
const VERSION_TAG = /^v(\d+\.\d+\.\d+)$/;
-// The worker runs the api image, so it follows the api's repository.
-const SERVICE_APP = {
- 'op-api': 'api',
- 'op-worker': 'api',
- 'op-dashboard': 'dashboard',
-} as const;
-
export type Channel = 'public' | 'supporter';
export const supporterImage = (app: string, version: string) =>
@@ -36,32 +29,6 @@ export const channelOf = (install: Install): Channel => {
: 'public';
};
-// Points every OpenPanel service at the channel's images; returns what changed.
-export const pointAt = (
- install: Install,
- channel: Channel,
- version: string
-): string[] => {
- const changes: string[] = [];
- for (const [service, app] of Object.entries(SERVICE_APP)) {
- if (!install.compose.hasIn(['services', service])) {
- continue;
- }
- const current = String(
- install.compose.getIn(['services', service, 'image']) ?? ''
- );
- const next =
- channel === 'supporter'
- ? supporterImage(app, version)
- : publicImage(app, version);
- if (current !== next) {
- install.compose.setIn(['services', service, 'image'], next);
- changes.push(`${service}: ${current} → ${next}`);
- }
- }
- return changes;
-};
-
export const publicVersion = (): string =>
STACK_IMAGE_TAG ?? TEMPLATE_IMAGE_TAG;
diff --git a/self-hosting/cli/test/image-choice.test.ts b/self-hosting/cli/test/image-choice.test.ts
new file mode 100644
index 000000000..8a9e0ee1c
--- /dev/null
+++ b/self-hosting/cli/test/image-choice.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, test } from 'bun:test';
+import { parseDocument } from 'yaml';
+import type { Install } from '../src/doctor/types';
+import { EnvFile } from '../src/env-file';
+import {
+ applyImage,
+ chooseImage,
+ defaultImage,
+ imageDecisions,
+} from '../src/image-choice';
+import { templates } from '../src/templates';
+
+const install = (images: Record<string, string> = {}): Install => {
+ const compose = parseDocument(templates.compose);
+ for (const [service, image] of Object.entries(images)) {
+ compose.setIn(['services', service, 'image'], image);
+ }
+ return {
+ compose,
+ env: new EnvFile(''),
+ caddyfile: null,
+ files: new Map(),
+ fileKind: () => 'file',
+ };
+};
+
+const GHCR_API = 'ghcr.io/openpanel-dev/api:rewrite-v2-9db2';
+const GHCR_DASHBOARD = 'ghcr.io/openpanel-dev/dashboard:rewrite-v2-9db2';
+
+describe('imageDecisions', () => {
+ test('one decision for api + worker, one for the dashboard', () => {
+ const decisions = imageDecisions(install(), 'public', '3.1.4');
+ expect(decisions).toEqual([
+ {
+ services: ['op-api', 'op-worker'],
+ current: 'lindesvard/openpanel-api:3',
+ proposed: 'lindesvard/openpanel-api:3.1.4',
+ },
+ {
+ services: ['op-dashboard'],
+ current: 'lindesvard/openpanel-dashboard:3',
+ proposed: 'lindesvard/openpanel-dashboard:3.1.4',
+ },
+ ]);
+ });
+
+ test('the supporter channel proposes the build from docker.openpanel.dev', () => {
+ const [api] = imageDecisions(install(), 'supporter', '3.1.9');
+ expect(api?.proposed).toBe('docker.openpanel.dev/openpanel-dev/api:3.1.9');
+ });
+
+ test('nothing to decide when the images are already the proposed ones', () => {
+ const target = install({
+ 'op-api': 'lindesvard/openpanel-api:3.1.4',
+ 'op-worker': 'lindesvard/openpanel-api:3.1.4',
+ 'op-dashboard': 'lindesvard/openpanel-dashboard:3.1.4',
+ });
+ expect(imageDecisions(target, 'public', '3.1.4')).toEqual([]);
+ });
+});
+
+describe('without anyone to ask (--yes)', () => {
+ test("OpenPanel's own images move to the new version", async () => {
+ const [api] = imageDecisions(install(), 'public', '3.1.4');
+ expect(await chooseImage(api!, true)).toBe(
+ 'lindesvard/openpanel-api:3.1.4'
+ );
+ });
+
+ test('an image from another registry is kept', async () => {
+ const target = install({
+ 'op-api': GHCR_API,
+ 'op-worker': GHCR_API,
+ 'op-dashboard': GHCR_DASHBOARD,
+ });
+ const decisions = imageDecisions(target, 'public', '3.1.4');
+ expect(decisions.map(defaultImage)).toEqual([GHCR_API, GHCR_DASHBOARD]);
+ for (const decision of decisions) {
+ expect(
+ applyImage(target, decision, await chooseImage(decision, true))
+ ).toEqual([]);
+ }
+ });
+});
+
+describe('applyImage', () => {
+ test('sets every service in the decision and reports the changes', () => {
+ const target = install();
+ const [api] = imageDecisions(target, 'public', '3.1.4');
+ const changes = applyImage(
+ target,
+ api!,
+ 'registry.example.com/openpanel-api:custom'
+ );
+ expect(changes).toEqual([
+ 'op-api: lindesvard/openpanel-api:3 → registry.example.com/openpanel-api:custom',
+ 'op-worker: lindesvard/openpanel-api:3 → registry.example.com/openpanel-api:custom',
+ ]);
+ expect(target.compose.getIn(['services', 'op-worker', 'image'])).toBe(
+ 'registry.example.com/openpanel-api:custom'
+ );
+ });
+});
diff --git a/self-hosting/cli/test/support-banner.test.ts b/self-hosting/cli/test/support-banner.test.ts
index 17d893baa..56568652e 100644
--- a/self-hosting/cli/test/support-banner.test.ts
+++ b/self-hosting/cli/test/support-banner.test.ts
@@ -7,7 +7,6 @@ import {
shouldShowSupportBanner,
supportBannerText,
} from '../src/support-banner';
-import { pointAt } from '../src/supporter';
import { templates } from '../src/templates';
const install = (): Install => ({
@@ -36,7 +35,10 @@ describe('support banner', () => {
test('never for supporters: supporter images, or logged in to the supporter registry', () => {
const supporterInstall = install();
- pointAt(supporterInstall, 'supporter', '3.1.9');
+ supporterInstall.compose.setIn(
+ ['services', 'op-api', 'image'],
+ 'docker.openpanel.dev/openpanel-dev/api:3.1.9'
+ );
expect(
shouldShowSupportBanner(context({ install: supporterInstall }))
).toBe(false);
diff --git a/self-hosting/cli/test/supporter.test.ts b/self-hosting/cli/test/supporter.test.ts
index c0b9a4b08..6996e0017 100644
--- a/self-hosting/cli/test/supporter.test.ts
+++ b/self-hosting/cli/test/supporter.test.ts
@@ -10,7 +10,6 @@ import {
channelOf,
isLoggedIn,
latestBuildVersion,
- pointAt,
SUPPORTER_REGISTRY,
} from '../src/supporter';
import { templates } from '../src/templates';
@@ -30,9 +29,6 @@ const install = (): Install => ({
fileKind: () => 'file',
});
-const image = (target: Install, service: string) =>
- target.compose.getIn(['services', service, 'image']);
-
const tagsFeed =
(names: string[], ok = true): Fetcher =>
async () =>
@@ -47,44 +43,16 @@ const dockerConfig = (config: unknown) => {
return dir;
};
-describe('channels', () => {
- test('a fresh install is on the public channel', () => {
- expect(channelOf(install())).toBe('public');
- });
-
- test('switching to supporter points api and worker at the api image, dashboard at its own', () => {
+describe('channelOf', () => {
+ test('an install on docker.openpanel.dev images is on the supporter channel', () => {
const target = install();
- const changes = pointAt(target, 'supporter', '3.1.9');
-
- expect(image(target, 'op-api')).toBe(
- `${SUPPORTER_REGISTRY}/openpanel-dev/api:3.1.9`
- );
- expect(image(target, 'op-worker')).toBe(
+ expect(channelOf(target)).toBe('public');
+ target.compose.setIn(
+ ['services', 'op-api', 'image'],
`${SUPPORTER_REGISTRY}/openpanel-dev/api:3.1.9`
);
- expect(image(target, 'op-dashboard')).toBe(
- `${SUPPORTER_REGISTRY}/openpanel-dev/dashboard:3.1.9`
- );
- expect(changes).toHaveLength(3);
expect(channelOf(target)).toBe('supporter');
});
-
- test('switching back to public restores the Docker Hub images', () => {
- const target = install();
- pointAt(target, 'supporter', '3.1.9');
- pointAt(target, 'public', '3.1.4');
- expect(image(target, 'op-api')).toBe('lindesvard/openpanel-api:3.1.4');
- expect(image(target, 'op-dashboard')).toBe(
- 'lindesvard/openpanel-dashboard:3.1.4'
- );
- expect(channelOf(target)).toBe('public');
- });
-
- test('nothing changes when the images are already right', () => {
- const target = install();
- pointAt(target, 'supporter', '3.1.9');
- expect(pointAt(target, 'supporter', '3.1.9')).toEqual([]);
- });
});
describe('latestBuildVersion', () => {