OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
self-hosting: fix what the CLI review found
Carl-Gerhard Lindesvärde8740887677a
diff --git a/self-hosting/.env.template b/self-hosting/.env.templateindex 7754df534..6aa7b5cce 100644--- a/self-hosting/.env.template+++ b/self-hosting/.env.template@@ -38,8 +38,8 @@ ENCRYPTION_KEY="$ENCRYPTION_KEY"# URI. Requires ENCRYPTION_KEY (generated by the setup script).# GSC_GOOGLE_REDIRECT_URI=https://your-domain.com/api/gsc/callback-# Events transport (ADR-004). The op-rp service (Redpanda) is a required part-# of this stack, not optional infra — see docker-compose.template.yml.+# Events go through Kafka. The bundled op-rp service (Redpanda) listens here;+# point this at your own brokers to use an external Kafka instead.KAFKA_BROKERS="op-rp:9092"# Partition count for the `events` topic, applied once by redpanda/bootstrap.yaml# on first boot. Set once at install — see the footgun warning indiff --git a/self-hosting/caddy/Caddyfile.template b/self-hosting/caddy/Caddyfile.templateindex 5a6d86635..9ad915b38 100644--- a/self-hosting/caddy/Caddyfile.template+++ b/self-hosting/caddy/Caddyfile.template@@ -15,10 +15,8 @@ worker.$DOMAIN_NAME {$SSL_CONFIGadmin $BASIC_AUTH_PASSWORD}- # Bull-board moved from `/` (v2's separate worker server) to `/bullboard`- # on the merged process's single port, so keep worker.<domain> landing on- # it. It is additionally behind the dashboard session guard now - this- # basic_auth is no longer the only thing in front of it.+ # The queue dashboard lives at /bullboard on the worker. It also requires+ # a dashboard login, so this basic_auth is a second lock, not the only one.redir / /bullboard/reverse_proxy op-worker:3000diff --git a/self-hosting/cli/src/commands/doctor.ts b/self-hosting/cli/src/commands/doctor.tsindex 1a0f0a420..b0b00c48f 100644--- a/self-hosting/cli/src/commands/doctor.ts+++ b/self-hosting/cli/src/commands/doctor.ts@@ -4,7 +4,9 @@ import { isInstallDir, loadInstall, writeInstall } from '../install';import { bold, dim, green, log, red, SEVERITY_LABEL } from '../ui';interface DoctorOptions {- dir: string;+ // null when no install was found; the host checks still run.+ dir: string | null;+ missingMessage: string;fix: boolean;check: boolean;}@@ -29,8 +31,12 @@ const printHost = async (): Promise<boolean> => {return results.every((result) => result.ok);};+const isBlocking = (finding: Finding) =>+ finding.severity === 'error' && !finding.fix;+export const doctor = async ({dir,+ missingMessage,fix,check,}: DoctorOptions): Promise<number> => {@@ -38,10 +44,16 @@ export const doctor = async ({const hostOk = await printHost();log();- if (!isInstallDir(dir)) {- log(`No install found in ${dir}. Run \`openpanel init\` to create one.`);+ if (dir === null) {+ log(missingMessage);return hostOk ? 0 : 1;}+ if (!isInstallDir(dir)) {+ log(+ `${dir} is not an OpenPanel install (its docker-compose.yml has no op-api and op-dashboard).`+ );+ return 1;+ }const install = loadInstall(dir);const findings = runDoctor(install);@@ -64,7 +76,8 @@ export const doctor = async ({? `Run \`openpanel doctor --fix\` to repair ${fixable.length} of ${findings.length}.`: 'Nothing here can be fixed automatically.');- return check && blocking.length > 0 ? 1 : 0;+ const failed = blocking.length > 0 || !hostOk;+ return check && failed ? 1 : 0;}applyFixes(install);@@ -79,5 +92,7 @@ export const doctor = async ({if (manual.length > 0) {log(`${manual.length} item(s) still need you — see above.`);}- return 0;+ // Fixed files are not a healthy install while a blocker or the host is broken.+ const stillBlocked = findings.some(isBlocking);+ return stillBlocked || !hostOk ? 1 : 0;};diff --git a/self-hosting/cli/src/commands/export.ts b/self-hosting/cli/src/commands/export.tsindex 4841601ea..7fdbe1aae 100644--- a/self-hosting/cli/src/commands/export.ts+++ b/self-hosting/cli/src/commands/export.ts@@ -65,17 +65,17 @@ const resolveClient = async (if (flags.container) {if (!(await holdsEvents(flags.container, flags.db, auth))) {throw new Error(- `Container '${flags.container}' has no '${flags.db}.events' table. Wrong container, or wrong --db? Try \`openpanel export --list\`.`+ `Container '${flags.container}' has no '${flags.db}.events' table, or rejected the credentials. Check --container, --db and CH_USER / CH_PASSWORD, or try \`openpanel export --list\`.`);}- return createClient(dockerPrefix(flags.container), flags.db, auth);+ return createClient(dockerPrefix(flags.container, auth), flags.db, auth);}const matches = await findContainers(flags.db, auth);const [only] = matches;if (matches.length === 1 && only) {clackLog.info(`ClickHouse container: ${only.name} (${only.id})`);- return createClient(dockerPrefix(only.id), flags.db, auth);+ return createClient(dockerPrefix(only.id, auth), flags.db, auth);}if (matches.length > 1) {const names = matchesdiff --git a/self-hosting/cli/src/commands/init.ts b/self-hosting/cli/src/commands/init.tsindex ca815a76e..3ced023a5 100644--- a/self-hosting/cli/src/commands/init.ts+++ b/self-hosting/cli/src/commands/init.ts@@ -1,4 +1,6 @@+import { readFileSync } from 'node:fs';import { cpus } from 'node:os';+import { join } from 'node:path';import {cancel,log as clackLog,@@ -10,6 +12,7 @@ import {select,text,} from '@clack/prompts';+import { EnvFile } from '../env-file';import { checkHost, DOCKER_INSTALL_COMMAND, type HostCheck } from '../host';import {defaultAnswers,@@ -19,12 +22,15 @@ import {type InitAnswers,} from '../init/generate';import { isInstallDir, writeFiles } from '../install';+import { discoverInstall, isEmptyOrMissing, rememberDir } from '../install-dir';import { run } from '../run';import { bold } from '../ui';import { compose } from './compose';export interface InitFlags {dir: string;+ // True when the user named the directory (--dir / OPENPANEL_DIR).+ explicit: boolean;yes: boolean;force: boolean;domain?: string;@@ -39,9 +45,14 @@ export interface InitFlags {}const MIN_WORKERS = 1;+// One or two workers carry most installs; more is a deliberate choice (--workers).+const MAX_DEFAULT_WORKERS = 2;const defaultWorkers = () =>- Math.max(Math.floor(cpus().length / 2), MIN_WORKERS);+ Math.min(+ Math.max(Math.floor(cpus().length / 2), MIN_WORKERS),+ MAX_DEFAULT_WORKERS+ );const isHttpUrl = (value: string) => /^https?:\/\/[^\s/]+/.test(value);@@ -232,14 +243,41 @@ const queueDashboardLines = (answers: InitAnswers, adminPassword: string) =>]: [];+const readExistingEnv = (dir: string): EnvFile | null => {+ try {+ return new EnvFile(readFileSync(join(dir, '.env'), 'utf8'));+ } catch {+ return null;+ }+};++// Why init should not write here, or null when it may.+const targetProblem = async (flags: InitFlags): Promise<string | null> => {+ if (isInstallDir(flags.dir)) {+ return flags.force+ ? null+ : `${flags.dir} already has an install. Run \`openpanel doctor\` to check it or \`openpanel upgrade\` to update it. --force regenerates the files but keeps your secrets.`;+ }+ // Without --dir, an install elsewhere (say ~/openpanel/self-hosting from the+ // old git clone) is the likelier explanation than a user wanting a second one.+ if (!flags.explicit) {+ const existing = await discoverInstall();+ if (existing.kind === 'found') {+ return `You already have an install at ${existing.dir}. Use \`openpanel doctor\` / \`openpanel upgrade\` there, or pass --dir <path> to set up another one.`;+ }+ }+ if (!isEmptyOrMissing(flags.dir)) {+ return `${flags.dir} is not empty and is not an OpenPanel install (a git clone, perhaps). Choose another directory with --dir <path>.`;+ }+ return null;+};+export const init = async (flags: InitFlags): Promise<number> => {intro(bold('OpenPanel setup'));- if (isInstallDir(flags.dir) && !flags.force) {- clackLog.error(`${flags.dir} already has an install.`);- clackLog.message(- 'Run `openpanel doctor` to check it, or `openpanel upgrade` to update it.\nUse --force to overwrite (originals are kept as .bak).'- );+ const problem = await targetProblem(flags);+ if (problem) {+ clackLog.error(problem);return 1;}if (!(await ensureDocker(flags))) {@@ -247,17 +285,21 @@ export const init = async (flags: InitFlags): Promise<number> => {}const answers = await askAnswers(flags);- const secrets = generateSecrets();+ // --force on a live install must not rotate secrets: the encryption key guards+ // stored credentials in databases that --force leaves in place.+ const secrets = generateSecrets(readExistingEnv(flags.dir));const written = await writeFiles(flags.dir,await generateInstall(answers, secrets));+ await rememberDir(flags.dir);+note([`Files: ${written.length} written to ${flags.dir}`,`Dashboard: ${answers.domain}`,- `Workers: ${answers.workers}`,+ `Workers: ${answers.workers} (change with OP_WORKER_REPLICAS in .env)`,...queueDashboardLines(answers, secrets.adminPassword),].join('\n'),'Installed'@@ -271,8 +313,6 @@ export const init = async (flags: InitFlags): Promise<number> => {if (start) {return compose('up', flags.dir);}- outro(- `Start it with: openpanel up${flags.dir === process.cwd() ? '' : ` --dir ${flags.dir}`}`- );+ outro('Start it with: openpanel up');return 0;};diff --git a/self-hosting/cli/src/commands/reset.ts b/self-hosting/cli/src/commands/reset.tsindex afde23d18..d9c2f5e16 100644--- a/self-hosting/cli/src/commands/reset.ts+++ b/self-hosting/cli/src/commands/reset.ts@@ -4,23 +4,61 @@ import { isInstallDir } from '../install';import { run } from '../run';import { bold, red } from '../ui';+// Caddy keeps its certificates here. Deleting them on every reset would+// re-request certificates and can hit Let's Encrypt rate limits.+const KEPT_VOLUME_PREFIX = 'op-proxy';+export interface ResetFlags {dir: string;yes: boolean;}-// Scoped to this install's compose project on purpose. The old script also ran-// host-wide `docker volume prune` / `image prune`, which deletes other projects'-// data; `down --volumes` removes only what this stack created.+const composeOutput = async (dir: string, args: string[]): Promise<string> => {+ const { code, stdout } = await run(['docker', 'compose', ...args], {+ cwd: dir,+ });+ if (code !== 0) {+ throw new Error(`docker compose ${args.join(' ')} failed in ${dir}`);+ }+ return stdout.trim();+};++// Compose labels every volume with its project and key, so this finds exactly+// this install's volumes, whatever the project happens to be called.+const volumeIds = async (project: string, key: string): Promise<string[]> => {+ const { stdout } = await run([+ 'docker',+ 'volume',+ 'ls',+ '-q',+ '--filter',+ `label=com.docker.compose.project=${project}`,+ '--filter',+ `label=com.docker.compose.volume=${key}`,+ ]);+ return stdout.split('\n').filter(Boolean);+};++// Scoped to this install on purpose: the old script also ran host-wide+// `docker volume prune` / `image prune`, which deletes other projects' data.export const reset = async ({ dir, yes }: ResetFlags): Promise<number> => {if (!isInstallDir(dir)) {- clackLog.error(`No install in ${dir}.`);+ clackLog.error(`${dir} is not an OpenPanel install.`);return 1;}+ const project = (+ JSON.parse(await composeOutput(dir, ['config', '--format', 'json'])) as {+ name: string;+ }+ ).name;+ const dataVolumes = (await composeOutput(dir, ['config', '--volumes']))+ .split('\n')+ .filter((key) => key && !key.startsWith(KEPT_VOLUME_PREFIX));+const confirmation = basename(dir);clackLog.warn(- `${red(bold('This deletes all OpenPanel data in this install'))}: Postgres, ClickHouse, Redis and Redpanda volumes.\nYour docker-compose.yml and .env are kept. Export first if you need the events: openpanel export`+ `${red(bold('This deletes all OpenPanel data in this install'))}: ${dataVolumes.join(', ')}.\nKept: docker-compose.yml, .env and Caddy's certificates. Export first if you need the events: openpanel export`);if (!yes) {const typed = await text({ message: `Type "${confirmation}" to continue` });@@ -30,12 +68,19 @@ export const reset = async ({ dir, yes }: ResetFlags): Promise<number> => {}}- const { code } = await run(- ['docker', 'compose', 'down', '--volumes', '--remove-orphans'],- { cwd: dir, inherit: true }- );- if (code === 0) {- clackLog.success('Wiped. Start fresh with: openpanel up');+ const down = await run(['docker', 'compose', 'down', '--remove-orphans'], {+ cwd: dir,+ inherit: true,+ });+ if (down.code !== 0) {+ return down.code;+ }+ for (const key of dataVolumes) {+ const ids = await volumeIds(project, key);+ if (ids.length > 0) {+ await run(['docker', 'volume', 'rm', ...ids], { inherit: true });+ }}- return code;+ clackLog.success('Wiped. Start fresh with: openpanel up');+ return 0;};diff --git a/self-hosting/cli/src/commands/upgrade.ts b/self-hosting/cli/src/commands/upgrade.tsindex 4e64a3913..03b8a1f3d 100644--- a/self-hosting/cli/src/commands/upgrade.ts+++ b/self-hosting/cli/src/commands/upgrade.ts@@ -3,17 +3,21 @@ 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 { type Fetcher, 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';+// Generous: the binary is ~80 MB and some servers sit on slow links.+const SELF_UPDATE_TIMEOUT_MS = 5 * 60 * 1000;+const PERMISSION_ERRORS = new Set(['EACCES', 'EPERM']);export interface UpgradeFlags {dir: string;yes: boolean;+ queueDrained: boolean;noSelfUpdate: boolean;}@@ -29,25 +33,40 @@ const ask = async (message: string, yes: boolean): Promise<boolean> => {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> => {+const fetchWithTimeout: Fetcher = (url) =>+ fetch(url, { signal: AbortSignal.timeout(SELF_UPDATE_TIMEOUT_MS) });++type SelfUpdateOutcome = { kind: 'continue' } | { kind: 'exit'; code: number };++// A newer CLI carries the checks and image tag for the newer stack, so when one+// exists but cannot be installed, stopping beats upgrading with stale knowledge.+const updateSelf = async (): Promise<SelfUpdateOutcome> => {try {const result = await selfUpdate({currentVersion: VERSION,execPath: process.execPath,- fetcher: fetch,+ fetcher: fetchWithTimeout,});if (result.status === 'current') {- return null;+ return { kind: 'continue' };}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;+ const { code } = await run([process.execPath, ...args], { inherit: true });+ return { kind: 'exit', 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 code = (error as NodeJS.ErrnoException).code ?? '';+ if (PERMISSION_ERRORS.has(code)) {+ clackLog.error(+ `A newer CLI is available but ${process.execPath} is not writable.\nRun \`sudo openpanel upgrade\`, or \`openpanel upgrade ${NO_SELF_UPDATE_FLAG}\` to continue with ${VERSION}.`+ );+ return { kind: 'exit', code: 1 };+ }+ // Offline or rate-limited: nothing newer is known, so this version is current enough.+ clackLog.warn(+ `Could not check for a newer CLI: ${(error as Error).message}`+ );+ return { kind: 'continue' };}};@@ -57,16 +76,42 @@ const listFindings = (findings: Finding[]) => {}};+const isBlocking = (finding: Finding) =>+ finding.severity === 'error' && !finding.fix;++// Applies the fixes to a throwaway copy, so problems that a fix resolves (an+// old variable name carrying DASHBOARD_URL) do not count as blockers.+const blockersAfterFixes = (dir: string): Finding[] => {+ const preview = loadInstall(dir);+ applyFixes(preview);+ return runDoctor(preview).filter(isBlocking);+};++const confirmQueueDrained = async (flags: UpgradeFlags): Promise<boolean> => {+ clackLog.warn(+ `${bold('This install predates Redpanda.')} Events still queued in Redis are not moved over. Stop tracking traffic and let the old worker drain first.`+ );+ if (flags.queueDrained) {+ return true;+ }+ // --yes is for routine confirmations; losing queued events is not routine.+ if (flags.yes) {+ clackLog.error('Pass --queue-drained once the old events queue is empty.');+ return false;+ }+ return ask('Has the old event queue drained?', false);+};+export const upgrade = async (flags: UpgradeFlags): Promise<number> => {if (!flags.noSelfUpdate && isCompiledBinary()) {- const handedOver = await updateSelf();- if (handedOver !== null) {- return handedOver;+ const outcome = await updateSelf();+ if (outcome.kind === 'exit') {+ return outcome.code;}}if (!isInstallDir(flags.dir)) {- clackLog.error(`No install in ${flags.dir}. Run \`openpanel init\` first.`);+ clackLog.error(`${flags.dir} is not an OpenPanel install.`);return 1;}const hostProblems = (await checkHost()).filter(@@ -81,28 +126,36 @@ export const upgrade = async (flags: UpgradeFlags): Promise<number> => {return 1;}+ // Refuse before touching anything, so a stopped upgrade leaves v2 files with+ // v2 containers rather than v3 files with v2 containers.+ const blockers = blockersAfterFixes(flags.dir);+ if (blockers.length > 0) {+ listFindings(blockers);+ clackLog.error(+ 'Fix these first (see `openpanel doctor`). Nothing was changed.'+ );+ 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 needsDrain = findings.some(+ (finding) => finding.id === DRAIN_FINDING_ID+ );+ if (needsDrain && !(await confirmQueueDrained(flags))) {+ clackLog.info('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- ))- ) {+ const approved = await ask(+ `Apply ${fixable.length} change(s)? Originals are kept as <name>.bak`,+ flags.yes+ );+ if (!approved) {return 1;}applyFixes(install);@@ -110,17 +163,6 @@ export const upgrade = async (flags: UpgradeFlags): Promise<number> => {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;diff --git a/self-hosting/cli/src/doctor/checks.ts b/self-hosting/cli/src/doctor/checks.tsindex 255bc5783..849660be5 100644--- a/self-hosting/cli/src/doctor/checks.ts+++ b/self-hosting/cli/src/doctor/checks.ts@@ -1,5 +1,5 @@import { randomBytes } from 'node:crypto';-import { isMap, isSeq, parseDocument } from 'yaml';+import { type Document, isAlias, isMap, isSeq, parseDocument } from 'yaml';import {DEFAULT_EVENTS_TOPIC_PARTITIONS,renderRedpandaBootstrap,@@ -25,9 +25,16 @@ const REMOVED_ENV_VARS = ['SHUTDOWN_GRACE_PERIOD_MS','FUNNEL_NON_STRICT_ORDERING','CHART_VALUES_LOOKBACK_DAYS',- 'NEXT_PUBLIC_API_URL',] as const;+// Renamed in 2.0; a pre-2.0 .env may still carry only the old name.+const RENAMED_ENV_VARS = [+ ['NEXT_PUBLIC_DASHBOARD_URL', 'DASHBOARD_URL'],+ ['NEXT_PUBLIC_API_URL', 'API_URL'],+ ['NEXT_PUBLIC_SELF_HOSTED', 'SELF_HOSTED'],+] as const;+const BUNDLED_KAFKA_HOST = 'op-rp:';+const templateCompose = parseDocument(templates.compose);const randomHex = (bytes: number) => randomBytes(bytes).toString('hex');@@ -64,17 +71,68 @@ const envEntries = (install: Install, service: string): string[] => {const hasWorkerRole = (install: Install) =>envEntries(install, 'op-worker').includes('ROLE=worker');-const hasHealthyDependency = (- install: Install,+const dependsOnPath = (service: string) => ['services', service, 'depends_on'];++// depends_on comes as a map (with conditions), a plain list, or a YAML alias+// shared between services; all three are valid compose.+const dependencyNames = (compose: Document, service: string): string[] => {+ const node = compose.getIn(dependsOnPath(service), true);+ const resolved = isAlias(node) ? node.resolve(compose) : node;+ if (isMap(resolved)) {+ return resolved.items.map((pair) =>+ String((pair.key as { value?: unknown }).value ?? pair.key)+ );+ }+ if (isSeq(resolved)) {+ return resolved.items.map((item) =>+ String((item as { value?: unknown }).value ?? item)+ );+ }+ return [];+};++const addDependency = (+ compose: Document,service: string,dependency: string-) => install.compose.hasIn(['services', service, 'depends_on', dependency]);+) => {+ const path = dependsOnPath(service);+ if (dependencyNames(compose, service).includes(dependency)) {+ return;+ }+ const node = compose.getIn(path, true);+ // Editing an alias would change every service sharing the anchor, so this+ // service gets its own copy first.+ if (isAlias(node)) {+ compose.setIn(path, compose.createNode(node.resolve(compose)?.toJSON()));+ }+ const current = compose.getIn(path, true);+ if (isSeq(current)) {+ current.add(dependency);+ return;+ }+ compose.setIn(+ [...path, dependency],+ compose.createNode({ condition: 'service_healthy' })+ );+};++// External Kafka (KAFKA_BROKERS pointing elsewhere) means no bundled Redpanda.+const usesBundledKafka = (install: Install) => {+ const brokers = install.env.get('KAFKA_BROKERS');+ return (+ !brokers ||+ brokers+ .split(',')+ .some((broker) => broker.trim().startsWith(BUNDLED_KAFKA_HOST))+ );+};const isLegacyWorkerImage = (install: Install) =>(serviceImage(install, 'op-worker') ?? '').includes('openpanel-worker');export const redpandaService: Check = (install) => {- if (hasService(install, 'op-rp')) {+ if (hasService(install, 'op-rp') || !usesBundledKafka(install)) {return null;}return {@@ -89,14 +147,8 @@ export const redpandaService: Check = (install) => {target.compose.setIn(['services', 'op-rp'], service);target.compose.setIn(['volumes', 'op-rp-data'], volume);for (const name of ['op-api', 'op-worker']) {- if (- hasService(target, name) &&- !hasHealthyDependency(target, name, 'op-rp')- ) {- target.compose.setIn(- ['services', name, 'depends_on', 'op-rp'],- target.compose.createNode({ condition: 'service_healthy' })- );+ if (hasService(target, name)) {+ addDependency(target.compose, name, 'op-rp');}}},@@ -104,9 +156,22 @@ export const redpandaService: Check = (install) => {};export const redpandaBootstrapFile: Check = (install) => {- if (install.hasFile(BOOTSTRAP_PATH)) {+ const needsBootstrap =+ hasService(install, 'op-rp') || usesBundledKafka(install);+ const kind = install.fileKind(BOOTSTRAP_PATH);+ if (!needsBootstrap || kind === 'file') {return null;}+ if (kind === 'directory') {+ return {+ id: 'files/redpanda-bootstrap',+ severity: 'error',+ title: `${BOOTSTRAP_PATH} is a directory`,+ detail:+ 'Docker creates a directory when a bind-mounted file is missing at start, and op-rp then cannot read its config.',+ manual: `Remove it (it is usually root-owned): sudo rm -rf ${BOOTSTRAP_PATH}, then run \`openpanel doctor --fix\`.`,+ };+ }return {id: 'files/redpanda-bootstrap',severity: 'error',@@ -127,8 +192,6 @@ export const redpandaBootstrapFile: Check = (install) => {};const OPENPANEL_IMAGE = /^(lindesvard\/openpanel-(?:api|dashboard)):(.+)$/;-// A floating tag follows a release line; anything else is a version the user chose.-const FLOATING_TAG = /^(\d+|latest)$/;const IMAGE_SERVICES = ['op-api', 'op-dashboard', 'op-worker'] as const;// The tag this CLI release is built for, read from the template so there is one@@ -149,37 +212,30 @@ const staleImages = (install: Install) =>: [];});+// The CLI owns the OpenPanel image tag, pinned versions included: the compose+// changes it makes only work with the images it was released for. Images from+// other registries (supporter builds, forks) are never touched.export const imageTag: Check = (install) => {const stale = staleImages(install);if (stale.length === 0) {return null;}- const floating = stale.filter(({ tag }) => FLOATING_TAG.test(tag));- const pinned = stale.filter(({ tag }) => !FLOATING_TAG.test(tag));- const pinnedNote =- pinned.length > 0- ? ` Pinned versions (${pinned.map(({ service, tag }) => `${service}:${tag}`).join(', ')}) are left for you to change.`- : '';+ const changes = stale+ .map(({ service, tag }) => `${service} ${tag} → ${STACK_IMAGE_TAG}`)+ .join(', ');return {id: 'compose/image-tag',- severity: floating.length > 0 ? 'error' : 'warn',- title: `OpenPanel images are not on :${STACK_IMAGE_TAG}`,- detail: `This CLI release targets :${STACK_IMAGE_TAG}; the compose changes here only work with those images.${pinnedNote}`,- fix:- floating.length > 0- ? (target) => {- for (const { service, repository } of floating) {- target.compose.setIn(- ['services', service, 'image'],- `${repository}:${STACK_IMAGE_TAG}`- );- }- }- : undefined,- manual:- floating.length === 0- ? `Change the pinned tags to ${STACK_IMAGE_TAG} (or a ${STACK_IMAGE_TAG}.x.y version) in docker-compose.yml.`- : undefined,+ severity: 'error',+ title: `OpenPanel images move to :${STACK_IMAGE_TAG} (${changes})`,+ detail: `This CLI release targets :${STACK_IMAGE_TAG}; the compose changes it makes only work with those images.`,+ fix: (target) => {+ for (const { service, repository } of staleImages(target)) {+ target.compose.setIn(+ ['services', service, 'image'],+ `${repository}:${STACK_IMAGE_TAG}`+ );+ }+ },};};@@ -233,6 +289,29 @@ export const workerRole: Check = (install) => {};};+const REPLICAS_PATH = ['services', 'op-worker', 'deploy', 'replicas'];++// Installs from before the CLI have a literal count; the variable form lets+// OP_WORKER_REPLICAS in .env change it without editing compose.+export const workerReplicas: Check = (install) => {+ const replicas = install.compose.getIn(REPLICAS_PATH);+ if (typeof replicas !== 'number') {+ return null;+ }+ return {+ id: 'compose/worker-replicas',+ severity: 'info',+ title: `op-worker replica count is fixed at ${replicas}`,+ detail:+ 'Switching to the OP_WORKER_REPLICAS variable keeps the count and makes it settable from .env.',+ fix: (target) =>+ target.compose.setIn(+ REPLICAS_PATH,+ `\${OP_WORKER_REPLICAS:-${replicas}}`+ ),+ };+};+export const workerHealthcheck: Check = (install) => {if (!hasService(install, 'op-worker')) {return null;@@ -359,6 +438,48 @@ export const cookieSecret: Check = (install) => {};};+export const renamedEnvVars: Check = (install) => {+ const present = RENAMED_ENV_VARS.filter(([oldName]) =>+ install.env.has(oldName)+ );+ if (present.length === 0) {+ return null;+ }+ return {+ id: 'env/renamed-vars',+ severity: 'error',+ title: `Old variable names in .env: ${present.map(([oldName]) => oldName).join(', ')}`,+ detail:+ 'Renamed in 2.0. Their values are moved to the new names unless those are already set.',+ fix: (target) => {+ for (const [oldName, newName] of present) {+ const value = target.env.get(oldName);+ if (value && !target.env.get(newName)) {+ target.env.set(newName, value);+ }+ target.env.remove(oldName);+ }+ },+ };+};++export const apiUrl: Check = (install) => {+ if (install.env.get('API_URL')) {+ return null;+ }+ const dashboard = install.env.get('DASHBOARD_URL');+ return {+ id: 'env/api-url',+ severity: 'error',+ title: 'API_URL is not set',+ detail:+ 'The dashboard calls the api at this address; without it every request fails.',+ manual: dashboard+ ? `With the bundled Caddy it is ${dashboard}/api. Set API_URL to that, or to wherever your proxy serves the api.`+ : 'Set API_URL to the public address of the api, e.g. https://analytics.example.com/api.',+ };+};+export const dashboardUrl: Check = (install) => {if (install.env.get('DASHBOARD_URL')) {return null;@@ -475,10 +596,12 @@ export const caddyBullboardRedirect: Check = (install) => {};};-// Reminder, not a repair: surfaced only while the install still looks like v1.+// Reminder, not a repair: surfaced only while the install still looks like it+// predates Kafka (old worker image, or no Redpanda while using the bundled one).export const drainOldQueue: Check = (install) => {- const looksLikeV1 =- isLegacyWorkerImage(install) || !hasService(install, 'op-rp');+ const missingBundledKafka =+ !hasService(install, 'op-rp') && usesBundledKafka(install);+ const looksLikeV1 = isLegacyWorkerImage(install) || missingBundledKafka;if (!looksLikeV1) {return null;}@@ -493,7 +616,8 @@ export const drainOldQueue: Check = (install) => {};// Order matters for fixes: the worker image is swapped before its role is-// checked, and op-rp is added before anything asks for its bootstrap file.+// checked, op-rp is added before anything asks for its bootstrap file, and old+// env names are migrated before the new ones are checked.export const checks: Check[] = [drainOldQueue,redpandaService,@@ -501,13 +625,16 @@ export const checks: Check[] = [imageTag,workerImage,workerRole,+ workerReplicas,workerHealthcheck,apiMigrations,kafkaBrokers,kafkaPartitions,encryptionKey,cookieSecret,+ renamedEnvVars,dashboardUrl,+ apiUrl,adminCredentials,selfHosted,enabledQueues,diff --git a/self-hosting/cli/src/doctor/types.ts b/self-hosting/cli/src/doctor/types.tsindex df71cda37..071d0b672 100644--- a/self-hosting/cli/src/doctor/types.ts+++ b/self-hosting/cli/src/doctor/types.ts@@ -11,7 +11,9 @@ export interface Install {caddyfile: string | null;// Files doctor may create, keyed by path relative to the install dir.files: Map<string, string>;- hasFile: (relativePath: string) => boolean;+ // Pending writes count as files. A directory matters separately: Docker+ // creates one when a bind-mounted file is missing, and it then shadows the file.+ fileKind: (relativePath: string) => 'file' | 'directory' | 'missing';}export interface Finding {diff --git a/self-hosting/cli/src/export/clickhouse.ts b/self-hosting/cli/src/export/clickhouse.tsindex 2c9e064cc..8a015991f 100644--- a/self-hosting/cli/src/export/clickhouse.ts+++ b/self-hosting/cli/src/export/clickhouse.ts@@ -21,11 +21,20 @@ export interface Candidate {image: string;}-const authArgs = (auth: Auth): string[] => [- ...(auth.host ? [`--host=${auth.host}`] : []),- ...(auth.user ? [`--user=${auth.user}`] : []),- ...(auth.password ? [`--password=${auth.password}`] : []),-];+// Credentials travel in the environment (clickhouse-client reads+// CLICKHOUSE_USER / CLICKHOUSE_PASSWORD), never on a command line where `ps`+// would show them for the length of the export. Only the host is an argument.+const hostArgs = (auth: Auth): string[] =>+ auth.host ? [`--host=${auth.host}`] : [];++const credentialEnv = (auth: Auth): Record<string, string> => ({+ ...(auth.user ? { CLICKHOUSE_USER: auth.user } : {}),+ ...(auth.password ? { CLICKHOUSE_PASSWORD: auth.password } : {}),+});++// `-e NAME` without a value makes docker copy NAME from its own environment.+const forwardedEnv = (auth: Auth): string[] =>+ Object.keys(credentialEnv(auth)).flatMap((name) => ['-e', name]);const finish = (child: ChildProcess, label: string): Promise<void> =>new Promise((resolve, reject) => {@@ -42,18 +51,19 @@ export const createClient = (database: string,auth: Auth): ClickHouse => {+ const env = credentialEnv(auth);const [binary = '', ...base] = prefix;// `--max_execution_time=0`: a day of events can outlast the default limit.const args = (sql: string) => [...base,`--database=${database}`,'--max_execution_time=0',- ...authArgs(auth),+ ...hostArgs(auth),`--query=${sql}`,];return {query: async (sql) => {- const { code, stdout } = await run([binary, ...args(sql)]);+ const { code, stdout } = await run([binary, ...args(sql)], { env });if (code !== 0) {throw new Error(`ClickHouse query failed: ${sql.slice(0, 80)}`);}@@ -63,6 +73,7 @@ export const createClient = (// stdin is closed on purpose: `docker exec -i` would otherwise read ours.const child = spawn(binary, args(sql), {stdio: ['ignore', 'pipe', 'inherit'],+ env: { ...process.env, ...env },});return {output: child.stdout as Readable,@@ -99,15 +110,19 @@ export const holdsEvents = async (database: string,auth: Auth): Promise<boolean> => {- const { code, stdout } = await run([- 'docker',- 'exec',- containerId,- 'clickhouse-client',- ...authArgs(auth),- '--query',- PROBE_SQL(database),- ]);+ const { code, stdout } = await run(+ [+ 'docker',+ 'exec',+ ...forwardedEnv(auth),+ containerId,+ 'clickhouse-client',+ ...hostArgs(auth),+ '--query',+ PROBE_SQL(database),+ ],+ { env: credentialEnv(auth) }+ );return code === 0 && stdout.trim() === '1';};@@ -143,10 +158,11 @@ export const findContainers = async (return [];};-export const dockerPrefix = (containerId: string): string[] => [+export const dockerPrefix = (containerId: string, auth: Auth): string[] => ['docker','exec','-i',+ ...forwardedEnv(auth),containerId,'clickhouse-client',];diff --git a/self-hosting/cli/src/init/generate.ts b/self-hosting/cli/src/init/generate.tsindex 8ec2b3c84..0c17cc08c 100644--- a/self-hosting/cli/src/init/generate.ts+++ b/self-hosting/cli/src/init/generate.ts@@ -1,6 +1,7 @@import { password } from 'bun';import { randomBytes } from 'node:crypto';import { parseDocument } from 'yaml';+import type { EnvFile } from '../env-file';import {DEFAULT_EVENTS_TOPIC_PARTITIONS,renderRedpandaBootstrap,@@ -43,10 +44,17 @@ export interface Secrets {adminPassword: string;}-export const generateSecrets = (): Secrets => ({- cookieSecret: randomBytes(SECRET_BYTES.cookie).toString('hex'),- encryptionKey: randomBytes(SECRET_BYTES.encryption).toString('hex'),- adminPassword: randomBytes(SECRET_BYTES.admin).toString('hex'),+// Values already in an existing .env win, so regenerating never rotates them.+export const generateSecrets = (existing: EnvFile | null = null): Secrets => ({+ cookieSecret:+ existing?.get('COOKIE_SECRET') ??+ randomBytes(SECRET_BYTES.cookie).toString('hex'),+ encryptionKey:+ existing?.get('ENCRYPTION_KEY') ??+ randomBytes(SECRET_BYTES.encryption).toString('hex'),+ adminPassword:+ existing?.get('ADMIN_PASSWORD') ??+ randomBytes(SECRET_BYTES.admin).toString('hex'),});export const hostOf = (domain: string): string =>diff --git a/self-hosting/cli/src/install-dir.ts b/self-hosting/cli/src/install-dir.tsnew file mode 100644index 000000000..c1071b76c--- /dev/null+++ b/self-hosting/cli/src/install-dir.ts@@ -0,0 +1,167 @@+import { existsSync, readdirSync, readFileSync } from 'node:fs';+import { mkdir, writeFile } from 'node:fs/promises';+import { homedir } from 'node:os';+import { dirname, join, resolve } from 'node:path';+import { isInstallDir } from './install';+import { run } from './run';++// Where the old `git clone … && cd openpanel/self-hosting` flow left installs,+// plus the default `init` target.+export const DEFAULT_INSTALL_DIR = join(homedir(), 'openpanel');+const KNOWN_PATHS = [+ DEFAULT_INSTALL_DIR,+ join(DEFAULT_INSTALL_DIR, 'self-hosting'),+ '/opt/openpanel',+ '/opt/openpanel/self-hosting',+];+const OLD_CLONE_SUBDIR = 'self-hosting';++const CONFIG_PATH = join(+ process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'),+ 'openpanel',+ 'config.json'+);++export type DirSource =+ | '--dir'+ | 'OPENPANEL_DIR'+ | 'current directory'+ | './self-hosting'+ | 'remembered'+ | 'running stack'+ | 'known location';++export type Resolution =+ | { kind: 'found'; dir: string; source: DirSource }+ | { kind: 'ambiguous'; candidates: string[] }+ | { kind: 'none'; searched: string[] };++export interface ResolveInputs {+ flag?: string;+ envDir?: string;+ cwd: string;+ remembered: string | null;+ runningDirs: string[];+ knownPaths?: string[];+ isInstall?: (dir: string) => boolean;+}++// First match wins, most explicit first. An explicit --dir / OPENPANEL_DIR is+// trusted as given (init creates it); everything after that must actually be+// an OpenPanel install, so a random compose project is never picked up.+export const resolveInstallDir = ({+ flag,+ envDir,+ cwd,+ remembered,+ runningDirs,+ knownPaths = KNOWN_PATHS,+ isInstall = isInstallDir,+}: ResolveInputs): Resolution => {+ if (flag) {+ return { kind: 'found', dir: resolve(flag), source: '--dir' };+ }+ if (envDir) {+ return { kind: 'found', dir: resolve(envDir), source: 'OPENPANEL_DIR' };+ }+ if (isInstall(cwd)) {+ return { kind: 'found', dir: cwd, source: 'current directory' };+ }+ const cloneDir = join(cwd, OLD_CLONE_SUBDIR);+ if (isInstall(cloneDir)) {+ return { kind: 'found', dir: cloneDir, source: './self-hosting' };+ }+ if (remembered && isInstall(remembered)) {+ return { kind: 'found', dir: remembered, source: 'remembered' };+ }++ const running = [...new Set(runningDirs)].filter(isInstall);+ const known = knownPaths.filter(+ (path) => !running.includes(path) && isInstall(path)+ );+ const candidates = [...running, ...known];+ const [only] = candidates;+ if (candidates.length === 1 && only) {+ return {+ kind: 'found',+ dir: only,+ source: running.includes(only) ? 'running stack' : 'known location',+ };+ }+ if (candidates.length > 1) {+ return { kind: 'ambiguous', candidates };+ }+ return {+ kind: 'none',+ searched: [+ cwd,+ cloneDir,+ ...(remembered ? [remembered] : []),+ ...knownPaths,+ ],+ };+};++export const readRememberedDir = (): string | null => {+ try {+ const { installDir } = JSON.parse(readFileSync(CONFIG_PATH, 'utf8')) as {+ installDir?: string;+ };+ return installDir ?? null;+ } catch {+ return null;+ }+};++// Best effort: failing to remember only means discovery runs next time.+export const rememberDir = async (dir: string): Promise<void> => {+ try {+ await mkdir(dirname(CONFIG_PATH), { recursive: true });+ await writeFile(+ CONFIG_PATH,+ `${JSON.stringify({ installDir: dir }, null, 2)}\n`+ );+ } catch {+ // ignore+ }+};++// Directories of compose projects Docker is running (or has stopped), from+// `docker compose ls`, which knows every project's config file path.+export const runningComposeDirs = async (): Promise<string[]> => {+ const { code, stdout } = await run([+ 'docker',+ 'compose',+ 'ls',+ '--all',+ '--format',+ 'json',+ ]);+ if (code !== 0) {+ return [];+ }+ try {+ const projects = JSON.parse(stdout) as { ConfigFiles?: string }[];+ return projects.flatMap(({ ConfigFiles }) =>+ (ConfigFiles ?? '')+ .split(',')+ .filter(Boolean)+ .map((file) => dirname(file))+ );+ } catch {+ return [];+ }+};++export const discoverInstall = async (flag?: string): Promise<Resolution> =>+ resolveInstallDir({+ flag,+ envDir: process.env.OPENPANEL_DIR,+ cwd: process.cwd(),+ remembered: readRememberedDir(),+ runningDirs: await runningComposeDirs(),+ });++// `init` may only write into a directory that is empty or missing.+export const isEmptyOrMissing = (dir: string): boolean =>+ !existsSync(dir) || readdirSync(dir).length === 0;diff --git a/self-hosting/cli/src/install.ts b/self-hosting/cli/src/install.tsindex 6b0696001..55d567317 100644--- a/self-hosting/cli/src/install.ts+++ b/self-hosting/cli/src/install.ts@@ -1,4 +1,4 @@-import { existsSync, readFileSync } from 'node:fs';+import { existsSync, readFileSync, statSync } from 'node:fs';import { chmod, copyFile, mkdir, writeFile } from 'node:fs/promises';import { dirname, join } from 'node:path';import { parseDocument } from 'yaml';@@ -14,8 +14,24 @@ const YAML_OUTPUT = { flowCollectionPadding: false, lineWidth: 0 } as const;const readIfExists = (path: string): string | null =>existsSync(path) ? readFileSync(path, 'utf8') : null;-export const isInstallDir = (dir: string): boolean =>- existsSync(join(dir, COMPOSE_FILE));+// Services every OpenPanel stack has. A compose file without them is some other+// project, notably the repo's own dev docker-compose.yml in a git clone.+const SIGNATURE_SERVICES = ['op-api', 'op-dashboard'] as const;++export const isInstallDir = (dir: string): boolean => {+ const text = readIfExists(join(dir, COMPOSE_FILE));+ if (text === null) {+ return false;+ }+ try {+ const compose = parseDocument(text);+ return SIGNATURE_SERVICES.every((service) =>+ compose.hasIn(['services', service])+ );+ } catch {+ return false;+ }+};export const loadInstall = (dir: string): Install => {const composeText = readIfExists(join(dir, COMPOSE_FILE));@@ -30,15 +46,37 @@ export const loadInstall = (dir: string): Install => {env: new EnvFile(readIfExists(join(dir, ENV_FILE)) ?? ''),caddyfile: readIfExists(join(dir, CADDYFILE)),files,- hasFile: (relativePath) =>- files.has(relativePath) || existsSync(join(dir, relativePath)),+ fileKind: (relativePath) => {+ if (files.has(relativePath)) {+ return 'file';+ }+ const path = join(dir, relativePath);+ if (!existsSync(path)) {+ return 'missing';+ }+ return statSync(path).isDirectory() ? 'directory' : 'file';+ },};};const EXECUTABLE_MODE = 0o755;+// .env holds the encryption key, cookie secret and admin password.+const SECRET_MODE = 0o600;++const isSecretFile = (relativePath: string) => relativePath === ENV_FILE;-// Originals are kept next to the file as `<name>.bak` so a bad fix is one `mv`-// away from undone. Only files that actually change are touched.+// The first backup is `<name>.bak`; later ones get a timestamp, so running a+// fix twice never overwrites the only copy of the original.+const backupPath = (target: string): string => {+ const plain = `${target}.bak`;+ if (!existsSync(plain)) {+ return plain;+ }+ const stamp = new Date().toISOString().replace(/[:.]/g, '-');+ return `${target}.bak.${stamp}`;+};++// Only files that actually change are touched.export const writeFiles = async (dir: string,outputs: Map<string, string>@@ -51,10 +89,23 @@ export const writeFiles = async (continue;}await mkdir(dirname(target), { recursive: true });+ const secret = isSecretFile(relativePath);if (previous !== null) {- await copyFile(target, `${target}.bak`);+ const backup = backupPath(target);+ await copyFile(target, backup);+ if (secret) {+ await chmod(backup, SECRET_MODE);+ }+ }+ await writeFile(+ target,+ content,+ secret ? { mode: SECRET_MODE } : undefined+ );+ // writeFile keeps an existing file's mode, so tighten it explicitly.+ if (secret) {+ await chmod(target, SECRET_MODE);}- await writeFile(target, content);if (relativePath.endsWith('.sh')) {await chmod(target, EXECUTABLE_MODE);}diff --git a/self-hosting/cli/src/main.ts b/self-hosting/cli/src/main.tsindex e866498af..a7d37ef6c 100644--- a/self-hosting/cli/src/main.ts+++ b/self-hosting/cli/src/main.ts@@ -1,5 +1,4 @@-import { homedir } from 'node:os';-import { join, resolve } from 'node:path';+import { resolve } from 'node:path';import { parseArgs } from 'node:util';import { compose, isComposeCommand } from './commands/compose';import { doctor } from './commands/doctor';@@ -7,13 +6,16 @@ import { exportData } from './commands/export';import { init } from './commands/init';import { reset } from './commands/reset';import { upgrade } from './commands/upgrade';-import { isInstallDir } from './install';-import { log, red } from './ui';+import {+ DEFAULT_INSTALL_DIR,+ discoverInstall,+ type Resolution,+ rememberDir,+} from './install-dir';+import { dim, log, red } from './ui';import { CHECK_TIMEOUT_MS, startUpdateCheck } from './update-notice';import { VERSION } from './version';-const DEFAULT_DIR = join(homedir(), 'openpanel');-const HELP = `openpanel ${VERSION} — run and maintain a self-hosted OpenPanelUsage: openpanel <command> [options]@@ -29,21 +31,56 @@ Commands:status Show running servicesOptions:- --dir <path> Install directory (default: current dir if it has- a docker-compose.yml, else ~/openpanel)+ --dir <path> Install directory. Without it the CLI looks in the+ current dir, ./self-hosting, the last install it+ used, and running stacks. init defaults to ~/openpanel-h, --help Show this help-v, --version Show the version`;-// A user standing in their install dir should not have to say so.-const resolveDir = (flag: string | undefined): string => {+const EXPLICIT_SOURCES = new Set(['--dir', 'OPENPANEL_DIR']);++const describeNone = (searched: string[]) =>+ `No OpenPanel install found. Looked in:\n${[...new Set(searched)].map((path) => ` ${path}`).join('\n')}\nRun \`openpanel init\`, or point at yours with --dir <path>.`;++// Says which install a command acts on, since that is no longer always the cwd.+const locateInstall = async (flag: string | undefined): Promise<Resolution> => {+ const resolution = await discoverInstall(flag);+ if (resolution.kind === 'ambiguous') {+ const list = resolution.candidates.map((dir) => ` ${dir}`).join('\n');+ throw new Error(+ `Found ${resolution.candidates.length} OpenPanel installs:\n${list}\nChoose one with --dir <path> (or set OPENPANEL_DIR).`+ );+ }+ if (resolution.kind === 'found') {+ process.stderr.write(+ `${dim(`Using ${resolution.dir} (${resolution.source})`)}\n`+ );+ if (!EXPLICIT_SOURCES.has(resolution.source)) {+ await rememberDir(resolution.dir);+ }+ }+ return resolution;+};++const requireInstall = async (flag: string | undefined): Promise<string> => {+ const resolution = await locateInstall(flag);+ if (resolution.kind !== 'found') {+ throw new Error(+ describeNone(resolution.kind === 'none' ? resolution.searched : [])+ );+ }+ return resolution.dir;+};++const initDir = (flag: string | undefined) => {if (flag) {- return resolve(flag);+ return { dir: resolve(flag), explicit: true };}if (process.env.OPENPANEL_DIR) {- return resolve(process.env.OPENPANEL_DIR);+ return { dir: resolve(process.env.OPENPANEL_DIR), explicit: true };}- return isInstallDir(process.cwd()) ? process.cwd() : DEFAULT_DIR;+ return { dir: DEFAULT_INSTALL_DIR, explicit: false };};const parseFlags = () =>@@ -56,6 +93,7 @@ const parseFlags = () =>yes: { type: 'boolean', short: 'y', default: false },force: { type: 'boolean', default: false },'no-self-update': { type: 'boolean', default: false },+ 'queue-drained': { type: 'boolean', default: false },container: { type: 'string' },out: { type: 'string' },'project-id': { type: 'string' },@@ -96,11 +134,10 @@ const main = async (): Promise<number> => {return 0;}- const dir = resolveDir(values.dir);// `upgrade` does its own (authoritative) check.const updateCheck =command === 'upgrade' ? Promise.resolve() : startUpdateCheck(VERSION);- const code = await route(command, rest, values, dir);+ const code = await route(command, rest, values);// A slow or offline network must not hold up the command's own exit.await Promise.race([updateCheck, Bun.sleep(CHECK_TIMEOUT_MS)]);return code;@@ -109,12 +146,11 @@ const main = async (): Promise<number> => {const route = async (command: string,rest: string[],- values: Flags,- dir: string+ values: Flags): Promise<number> => {if (command === 'init') {return init({- dir,+ ...initDir(values.dir),yes: values.yes,force: values.force,domain: values.domain,@@ -142,21 +178,29 @@ const route = async (noGzip: values['no-gzip'],});}- if (command === 'reset') {- return reset({ dir, yes: values.yes });+ if (command === 'doctor') {+ const resolution = await locateInstall(values.dir);+ return doctor({+ dir: resolution.kind === 'found' ? resolution.dir : null,+ missingMessage:+ resolution.kind === 'none' ? describeNone(resolution.searched) : '',+ fix: values.fix,+ check: values.check,+ });}if (command === 'upgrade') {return upgrade({- dir,+ dir: await requireInstall(values.dir),yes: values.yes,+ queueDrained: values['queue-drained'],noSelfUpdate: values['no-self-update'],});}- if (command === 'doctor') {- return doctor({ dir, fix: values.fix, check: values.check });+ if (command === 'reset') {+ return reset({ dir: await requireInstall(values.dir), yes: values.yes });}if (isComposeCommand(command)) {- return compose(command, dir, rest);+ return compose(command, await requireInstall(values.dir), rest);}log(`Unknown command "${command}".\n\n${HELP}`);diff --git a/self-hosting/cli/src/run.ts b/self-hosting/cli/src/run.tsindex 5dba3e89e..345d955fd 100644--- a/self-hosting/cli/src/run.ts+++ b/self-hosting/cli/src/run.ts@@ -12,12 +12,17 @@ const MISSING_BINARY_CODE = 127;// command instead of throwing, so host checks can report it.export const run = (command: string[],- options: { cwd?: string; inherit?: boolean } = {}+ options: {+ cwd?: string;+ inherit?: boolean;+ env?: Record<string, string>;+ } = {}): Promise<RunResult> =>new Promise((resolve) => {const [binary = '', ...args] = command;const child = spawn(binary, args, {cwd: options.cwd,+ env: options.env ? { ...process.env, ...options.env } : process.env,stdio: options.inherit ? 'inherit' : ['ignore', 'pipe', 'ignore'],});let stdout = '';diff --git a/self-hosting/cli/test/doctor-edge.test.ts b/self-hosting/cli/test/doctor-edge.test.tsnew file mode 100644index 000000000..7e16acaed--- /dev/null+++ b/self-hosting/cli/test/doctor-edge.test.ts@@ -0,0 +1,207 @@+import { afterEach, describe, expect, test } from 'bun:test';+import {+ cpSync,+ mkdirSync,+ mkdtempSync,+ readdirSync,+ readFileSync,+ rmSync,+ statSync,+ writeFileSync,+} from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { parseDocument } from 'yaml';+import { applyFixes, runDoctor } from '../src/doctor';+import { loadInstall, writeInstall } from '../src/install';++const V1_FIXTURE = join(import.meta.dir, 'fixtures/v1');+// Owner read/write only, as `ls -l` shows the last three octal digits.+const SECRET_MODE = '600';+// Compose interpolation syntax, spelled so the linter does not read it as a template.+const DOLLAR = '$';+const tempDirs: string[] = [];++afterEach(() => {+ for (const dir of tempDirs.splice(0)) {+ rmSync(dir, { recursive: true, force: true });+ }+});++const v1Copy = () => {+ const dir = mkdtempSync(join(tmpdir(), 'op-edge-'));+ tempDirs.push(dir);+ cpSync(V1_FIXTURE, dir, { recursive: true });+ return dir;+};++const editCompose = (dir: string, edit: (text: string) => string) => {+ const path = join(dir, 'docker-compose.yml');+ writeFileSync(path, edit(readFileSync(path, 'utf8')));+};++const editEnv = (dir: string, edit: (text: string) => string) => {+ const path = join(dir, '.env');+ writeFileSync(path, edit(readFileSync(path, 'utf8')));+};++const ids = (dir: string) =>+ runDoctor(loadInstall(dir)).map((finding) => finding.id);++const fixed = (dir: string) => {+ const install = loadInstall(dir);+ applyFixes(install);+ return install;+};++describe('depends_on shapes', () => {+ test('a list gains op-rp as a list entry', () => {+ const dir = v1Copy();+ editCompose(dir, (text) =>+ text.replace(+ / {2}op-worker:\n(.*\n)*? {4}depends_on:\n {6}op-api:\n {8}condition: service_healthy\n/,+ (block) =>+ block.replace(+ ' op-api:\n condition: service_healthy\n',+ ' - op-api\n'+ )+ )+ );+ const compose = parseDocument(String(fixed(dir).compose)).toJS();+ expect(compose.services['op-worker'].depends_on).toEqual([+ 'op-api',+ 'op-rp',+ ]);+ });++ test('an alias shared by two services is copied, not edited in place', () => {+ const dir = mkdtempSync(join(tmpdir(), 'op-edge-'));+ tempDirs.push(dir);+ writeFileSync(+ join(dir, 'docker-compose.yml'),+ [+ 'x-deps: &deps',+ ' op-db:',+ ' condition: service_healthy',+ 'services:',+ ' op-db: { image: postgres:14-alpine }',+ ' op-api:',+ ' image: lindesvard/openpanel-api:2',+ ' depends_on: *deps',+ ' op-dashboard:',+ ' image: lindesvard/openpanel-dashboard:2',+ ' depends_on: *deps',+ '',+ ].join('\n')+ );+ writeFileSync(join(dir, '.env'), 'KAFKA_BROKERS="op-rp:9092"\n');++ const compose = parseDocument(String(fixed(dir).compose)).toJS();+ expect(Object.keys(compose.services['op-api'].depends_on)).toEqual([+ 'op-db',+ 'op-rp',+ ]);+ expect(Object.keys(compose.services['op-dashboard'].depends_on)).toEqual([+ 'op-db',+ ]);+ expect(Object.keys(compose['x-deps'])).toEqual(['op-db']);+ });+});++describe('external Kafka', () => {+ test('KAFKA_BROKERS pointing elsewhere skips Redpanda and the drain reminder', () => {+ const dir = v1Copy();+ editEnv(dir, (text) => `${text}KAFKA_BROKERS="kafka.internal:9092"\n`);+ editCompose(dir, (text) =>+ text.replace(+ 'lindesvard/openpanel-worker:2',+ 'lindesvard/openpanel-api:2'+ )+ );++ const found = ids(dir);+ expect(found).not.toContain('compose/redpanda-service');+ expect(found).not.toContain('files/redpanda-bootstrap');+ expect(found).not.toContain('upgrade/drain-old-queue');+ });+});++describe('env renames', () => {+ test('pre-2.0 names are carried over to the new names, then removed', () => {+ const dir = v1Copy();+ editEnv(dir, (text) =>+ text+ .replace(+ /^DASHBOARD_URL=.*\n/m,+ 'NEXT_PUBLIC_DASHBOARD_URL="https://old.example.com"\n'+ )+ .replace(+ /^API_URL=.*\n/m,+ 'NEXT_PUBLIC_API_URL="https://old.example.com/api"\n'+ )+ );+ const { env } = fixed(dir);+ expect(env.get('DASHBOARD_URL')).toBe('https://old.example.com');+ expect(env.get('API_URL')).toBe('https://old.example.com/api');+ expect(env.has('NEXT_PUBLIC_API_URL')).toBe(false);+ });++ test('a missing API_URL is a manual step that suggests the bundled-Caddy address', () => {+ const dir = v1Copy();+ editEnv(dir, (text) => text.replace(/^API_URL=.*\n/m, ''));+ const finding = runDoctor(loadInstall(dir)).find(+ (item) => item.id === 'env/api-url'+ );+ expect(finding?.fix).toBeUndefined();+ expect(finding?.manual).toContain('https://analytics.example.com/api');+ });+});++describe('files', () => {+ test('a bootstrap.yaml directory (made by docker) is reported, not written over', () => {+ const dir = v1Copy();+ mkdirSync(join(dir, 'redpanda/bootstrap.yaml'), { recursive: true });+ const finding = runDoctor(loadInstall(dir)).find(+ (item) => item.id === 'files/redpanda-bootstrap'+ );+ expect(finding?.title).toContain('is a directory');+ expect(finding?.fix).toBeUndefined();+ });++ test('a second write keeps the first backup and adds a timestamped one', async () => {+ const dir = v1Copy();+ const original = readFileSync(join(dir, '.env'), 'utf8');++ await writeInstall(dir, fixed(dir));+ const once = loadInstall(dir);+ once.env.set('EXTRA', '1');+ await writeInstall(dir, once);++ expect(readFileSync(join(dir, '.env.bak'), 'utf8')).toBe(original);+ const backups = readdirSync(dir).filter((name) =>+ name.startsWith('.env.bak')+ );+ expect(backups.length).toBe(2);+ });++ test('.env and its backups are only readable by the owner', async () => {+ const dir = v1Copy();+ await writeInstall(dir, fixed(dir));+ const mode = (name: string) =>+ statSync(join(dir, name)).mode.toString(8).slice(-3);+ expect(mode('.env')).toBe(SECRET_MODE);+ expect(mode('.env.bak')).toBe(SECRET_MODE);+ });+});++describe('worker replicas', () => {+ test('a literal count becomes an overridable variable with the same default', () => {+ const replicas = fixed(v1Copy()).compose.getIn([+ 'services',+ 'op-worker',+ 'deploy',+ 'replicas',+ ]);+ expect(replicas).toBe(`${DOLLAR}{OP_WORKER_REPLICAS:-1}`);+ });+});diff --git a/self-hosting/cli/test/doctor.test.ts b/self-hosting/cli/test/doctor.test.tsindex 6edac6edc..ac4125e7b 100644--- a/self-hosting/cli/test/doctor.test.ts+++ b/self-hosting/cli/test/doctor.test.ts@@ -31,6 +31,7 @@ describe('doctor on a v1 install', () => {'files/redpanda-bootstrap','compose/worker-image','compose/worker-role',+ 'compose/worker-replicas','compose/worker-healthcheck','compose/api-migrations','env/kafka-brokers',diff --git a/self-hosting/cli/test/export.test.ts b/self-hosting/cli/test/export.test.tsindex 0aa557016..3e7a2f16e 100644--- a/self-hosting/cli/test/export.test.ts+++ b/self-hosting/cli/test/export.test.ts@@ -218,3 +218,26 @@ describe('validateOptions', () => {).not.toThrow();});});++describe('credentials', () => {+ test('never appear on the docker command line', async () => {+ const { dockerPrefix } = await import('../src/export/clickhouse');+ const prefix = dockerPrefix('ch-container', {+ user: 'reader',+ password: 's3cret-value',+ });++ expect(prefix).toEqual([+ 'docker',+ 'exec',+ '-i',+ '-e',+ 'CLICKHOUSE_USER',+ '-e',+ 'CLICKHOUSE_PASSWORD',+ 'ch-container',+ 'clickhouse-client',+ ]);+ expect(prefix.join(' ')).not.toContain('s3cret-value');+ });+});diff --git a/self-hosting/cli/test/image-tag.test.ts b/self-hosting/cli/test/image-tag.test.tsindex 7d53e56ad..35bac3755 100644--- a/self-hosting/cli/test/image-tag.test.ts+++ b/self-hosting/cli/test/image-tag.test.ts@@ -27,7 +27,7 @@ const installWithImages = (images: Record<string, string>): Install => {env,caddyfile: null,files: new Map(),- hasFile: () => true,+ fileKind: () => 'file',};};@@ -66,31 +66,19 @@ describe('compose/image-tag', () => {expect(tagFinding(install)).toBeUndefined();});- test('an exact pin is reported but never rewritten', () => {+ test('exact pins are moved too, and the title says what changes', () => {const install = installWithImages({'op-api': 'lindesvard/openpanel-api:1.2.3',+ 'op-dashboard': 'lindesvard/openpanel-dashboard:1',});- const finding = tagFinding(install);-- expect(finding?.fix).toBeUndefined();- expect(finding?.manual).toContain(STACK_IMAGE_TAG);- expect(finding?.detail).toContain('op-api:1.2.3');-- applyFixes(install);- expect(install.compose.getIn(['services', 'op-api', 'image'])).toBe(- 'lindesvard/openpanel-api:1.2.3'+ expect(tagFinding(install)?.title).toContain(+ `op-api 1.2.3 → ${STACK_IMAGE_TAG}`);- });- test('a mix fixes the floating tags and leaves the pin', () => {- const install = installWithImages({- 'op-api': 'lindesvard/openpanel-api:1.2.3',- 'op-dashboard': 'lindesvard/openpanel-dashboard:1',- });applyFixes(install);const compose = install.compose.toJS();expect(compose.services['op-api'].image).toBe(- 'lindesvard/openpanel-api:1.2.3'+ `lindesvard/openpanel-api:${STACK_IMAGE_TAG}`);expect(compose.services['op-dashboard'].image).toBe(`lindesvard/openpanel-dashboard:${STACK_IMAGE_TAG}`diff --git a/self-hosting/cli/test/install-dir.test.ts b/self-hosting/cli/test/install-dir.test.tsnew file mode 100644index 000000000..2f0e71420--- /dev/null+++ b/self-hosting/cli/test/install-dir.test.ts@@ -0,0 +1,155 @@+import { afterEach, describe, expect, test } from 'bun:test';+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { EnvFile } from '../src/env-file';+import { generateSecrets } from '../src/init/generate';+import { isInstallDir } from '../src/install';+import { resolveInstallDir } from '../src/install-dir';+import { templates } from '../src/templates';++// The repo's own dev compose: same service prefix, but no app services.+const DEV_COMPOSE =+ 'services:\n op-db: { image: postgres }\n op-ch: { image: clickhouse }\n op-rp: { image: redpanda }\n';++const tempDirs: string[] = [];+afterEach(() => {+ for (const dir of tempDirs.splice(0)) {+ rmSync(dir, { recursive: true, force: true });+ }+});++const root = () => {+ const dir = mkdtempSync(join(tmpdir(), 'op-dir-'));+ tempDirs.push(dir);+ return dir;+};++const withCompose = (dir: string, compose: string) => {+ mkdirSync(dir, { recursive: true });+ writeFileSync(join(dir, 'docker-compose.yml'), compose);+ return dir;+};++const install = (dir: string) => withCompose(dir, templates.compose);++const resolve = (+ inputs: Partial<Parameters<typeof resolveInstallDir>[0]> & { cwd: string }+) =>+ resolveInstallDir({+ remembered: null,+ runningDirs: [],+ knownPaths: [],+ ...inputs,+ });++describe('isInstallDir', () => {+ test('needs op-api and op-dashboard, not just any compose file', () => {+ const base = root();+ expect(isInstallDir(install(join(base, 'real')))).toBe(true);+ expect(isInstallDir(withCompose(join(base, 'dev'), DEV_COMPOSE))).toBe(+ false+ );+ expect(+ isInstallDir(+ withCompose(join(base, 'web'), 'services:\n web: { image: nginx }\n')+ )+ ).toBe(false);+ expect(+ isInstallDir(withCompose(join(base, 'broken'), 'services: [unclosed'))+ ).toBe(false);+ expect(isInstallDir(join(base, 'missing'))).toBe(false);+ });+});++describe('resolveInstallDir', () => {+ test('an explicit --dir wins, even before it exists', () => {+ const base = root();+ install(join(base, 'cwd'));+ expect(+ resolve({ flag: join(base, 'new'), cwd: join(base, 'cwd') })+ ).toEqual({+ kind: 'found',+ dir: join(base, 'new'),+ source: '--dir',+ });+ });++ test('the current directory when it is an install', () => {+ const cwd = install(join(root(), 'here'));+ expect(resolve({ cwd })).toMatchObject({+ kind: 'found',+ dir: cwd,+ source: 'current directory',+ });+ });++ test('an old git clone: the repo root is skipped in favour of ./self-hosting', () => {+ const clone = withCompose(join(root(), 'openpanel'), DEV_COMPOSE);+ install(join(clone, 'self-hosting'));+ expect(resolve({ cwd: clone })).toMatchObject({+ kind: 'found',+ dir: join(clone, 'self-hosting'),+ source: './self-hosting',+ });+ });++ test('from anywhere: a remembered install is used while it still exists', () => {+ const base = root();+ const remembered = install(join(base, 'remembered'));+ expect(resolve({ cwd: base, remembered })).toMatchObject({+ dir: remembered,+ source: 'remembered',+ });+ rmSync(remembered, { recursive: true });+ expect(resolve({ cwd: base, remembered }).kind).toBe('none');+ });++ test('from anywhere: a single running OpenPanel stack is found, other projects ignored', () => {+ const base = root();+ const stack = install(join(base, 'stack'));+ const other = withCompose(+ join(base, 'other'),+ 'services:\n web: { image: nginx }\n'+ );+ expect(+ resolve({ cwd: base, runningDirs: [other, stack, stack] })+ ).toMatchObject({+ dir: stack,+ source: 'running stack',+ });+ });++ test('several candidates are listed instead of guessed', () => {+ const base = root();+ const one = install(join(base, 'one'));+ const two = install(join(base, 'two'));+ expect(+ resolve({ cwd: base, runningDirs: [one], knownPaths: [two] })+ ).toEqual({+ kind: 'ambiguous',+ candidates: [one, two],+ });+ });++ test('nothing found reports where it looked', () => {+ const base = root();+ const result = resolve({ cwd: base, knownPaths: [join(base, 'opt')] });+ expect(result).toEqual({+ kind: 'none',+ searched: [base, join(base, 'self-hosting'), join(base, 'opt')],+ });+ });+});++describe('generateSecrets', () => {+ test('keeps values from an existing .env and only fills the gaps', () => {+ const existing = new EnvFile(+ `ENCRYPTION_KEY="${'ab'.repeat(32)}"\nCOOKIE_SECRET="keep-me"\n`+ );+ const secrets = generateSecrets(existing);+ expect(secrets.encryptionKey).toBe('ab'.repeat(32));+ expect(secrets.cookieSecret).toBe('keep-me');+ expect(secrets.adminPassword).toMatch(/^[0-9a-f]{24}$/);+ });+});diff --git a/self-hosting/docker-compose.template.yml b/self-hosting/docker-compose.template.ymlindex ce2e6010d..e39546f7b 100644--- a/self-hosting/docker-compose.template.yml+++ b/self-hosting/docker-compose.template.yml@@ -87,12 +87,9 @@ services:max-size: "10m"max-file: "3"- # Required stateful service (ADR-004): /track always produces to Kafka, no- # fallback transport. Sizing here is a sane single-node starting point, NOT- # the --memory=1G/--mode=dev-container cap the root docker-compose.yml uses- # for local dev — that cap was never measured against real ingest traffic- # and is not a production baseline. Tune --memory to what the host can- # spare.+ # Required: every tracked event goes through Redpanda (Kafka-compatible).+ # --memory=2G is a single-node starting point; raise it if the host can+ # spare more, or lower it on small machines.op-rp:image: redpandadata/redpanda:v25.1.4restart: always@@ -127,23 +124,9 @@ services:op-api:image: lindesvard/openpanel-api:2restart: always- # P9.5 collapsed the two-Dockerfile setup onto oven/bun, and P13- # (ADR-014, M13-003) made bun the installer as well, so no second package- # manager exists in this image or in the repo it is built from.- #- # MIGRATIONS RUN HERE, in the api container's start command (Carl,- # 2026-09-08). The Prisma CLI is a devDependency of packages/db, so the- # image's production-only install correctly omits it; `bunx` fetches it at- # start instead of the image carrying the CLI plus @prisma/engines (~86 MB)- # for a command that runs once per deploy. The version is PINNED because a- # bare `bunx prisma` fetches latest, which can drift from the generated- # client and the schema this image ships. Accepted consequence: the api- # container needs npm-registry reach at start.- #- # The code migrations run through `scripts/migrate-code.ts`, the shell that- # reads the environment for them — `src/code-migrations/migrate.ts` only- # exports the runner (ADR-022 R7), and the `jiti` this line used to name is- # no longer a dependency of anything.+ # Database migrations run here, before the api starts. The Prisma CLI is+ # fetched at start (pinned to the version the image was built with), so+ # this container needs to reach the npm registry when it boots.command: >sh -c "echo 'Running migrations...'@@ -194,11 +177,8 @@ services:max-size: "20m"max-file: "3"- # ONE image, two roles. v3.0.0 deleted the separate worker image: the api- # image serves the queues, the schedulers and the Kafka consumer when it is- # started with ROLE=worker. Upgrading from v2 means changing this image line- # and adding ROLE — nothing else; queue names, scheduler ids and the Kafka- # topic are unchanged.+ # The worker is the api image started with ROLE=worker: it runs the queues,+ # the scheduled jobs and the event consumer.op-worker:image: lindesvard/openpanel-api:2restart: alwaysdiff --git a/self-hosting/install.sh b/self-hosting/install.shindex 2da39a72b..661d52c2b 100755--- a/self-hosting/install.sh+++ b/self-hosting/install.sh@@ -76,7 +76,9 @@ dir="${OPENPANEL_INSTALL_DIR:-}"if [ -z "$dir" ]; thenif [ -w /usr/local/bin ]; thendir=/usr/local/bin- elif command -v sudo >/dev/null 2>&1 && [ -t 0 ]; then+ # Under `curl | sh` stdin is the script, so ask whether a terminal exists for+ # sudo to prompt on, rather than whether stdin is one.+ elif command -v sudo >/dev/null 2>&1 && (: </dev/tty) 2>/dev/null; thendir=/usr/local/binuse_sudo=1elsediff --git a/self-hosting/redpanda/bootstrap.template.yaml b/self-hosting/redpanda/bootstrap.template.yamlindex 344d07746..515bc97d2 100644--- a/self-hosting/redpanda/bootstrap.template.yaml+++ b/self-hosting/redpanda/bootstrap.template.yaml@@ -6,7 +6,7 @@# Generated as redpanda/bootstrap.yaml by `openpanel init` from this template — do not# edit the generated file directly, it is overwritten on the next setup run.#-# FOOTGUN (ADR-004 risk 6): the producer partitions by+# Careful: the producer partitions by# murmur2(key) % numPartitions, so raising this value after the `events`# topic already exists reshuffles every key — it silently breaks per-key# ordering and mutual exclusion for events produced before the change. Set it