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: fix what the CLI review found

Carl-Gerhard Lindesvärde8740887677a
diff --git a/self-hosting/.env.template b/self-hosting/.env.template
index 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 in
diff --git a/self-hosting/caddy/Caddyfile.template b/self-hosting/caddy/Caddyfile.template
index 5a6d86635..9ad915b38 100644
--- a/self-hosting/caddy/Caddyfile.template
+++ b/self-hosting/caddy/Caddyfile.template
@@ -15,10 +15,8 @@ worker.$DOMAIN_NAME {$SSL_CONFIG
admin $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:3000
diff --git a/self-hosting/cli/src/commands/doctor.ts b/self-hosting/cli/src/commands/doctor.ts
index 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.ts
index 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 = matches
diff --git a/self-hosting/cli/src/commands/init.ts b/self-hosting/cli/src/commands/init.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 OpenPanel
Usage: openpanel <command> [options]
@@ -29,21 +31,56 @@ Commands:
status Show running services
Options:
- --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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.yml
index 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.4
restart: always
@@ -127,23 +124,9 @@ services:
op-api:
image: lindesvard/openpanel-api:2
restart: 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:2
restart: always
diff --git a/self-hosting/install.sh b/self-hosting/install.sh
index 2da39a72b..661d52c2b 100755
--- a/self-hosting/install.sh
+++ b/self-hosting/install.sh
@@ -76,7 +76,9 @@ dir="${OPENPANEL_INSTALL_DIR:-}"
if [ -z "$dir" ]; then
if [ -w /usr/local/bin ]; then
dir=/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; then
dir=/usr/local/bin
use_sudo=1
else
diff --git a/self-hosting/redpanda/bootstrap.template.yaml b/self-hosting/redpanda/bootstrap.template.yaml
index 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