@primafuture/telemetry-stack 0.1.0

package/bin/telemetry-stack.mjs

@@ -0,0 +1,654 @@
+#!/usr/bin/env node
+
+// This CLI is the thin wrapper around the packaged Docker Compose stack.
+// It keeps project-specific state outside the npm package by requiring a data directory.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+// Resolve paths from the installed package, not from the user's current directory.
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const composeFile = path.join(packageRoot, 'stack', 'docker-compose.yaml');
+const instanceConfigFileName = 'telemetry-stack.env';
+const generatedConfigDirectoryName = 'generated-configs';
+
+const generatedConfigTemplates = [
+	['loki.yaml', path.join(packageRoot, 'stack', 'templates', 'loki.yaml')],
+	['mimir.yaml', path.join(packageRoot, 'stack', 'templates', 'mimir.yaml')],
+	['tempo.yaml', path.join(packageRoot, 'stack', 'templates', 'tempo.yaml')],
+];
+
+const instanceConfigKeys = [
+	'TELEMETRY_MODE',
+	'TELEMETRY_BIND_ADDRESS',
+	'TELEMETRY_MINIO_ACCESS_KEY',
+	'TELEMETRY_MINIO_SECRET_KEY',
+	'GRAFANA_ANONYMOUS_ENABLED',
+	'GRAFANA_ANONYMOUS_ORG_ROLE',
+	'GRAFANA_DISABLE_LOGIN_FORM',
+	'GRAFANA_ADMIN_USER',
+	'GRAFANA_ADMIN_PASSWORD',
+];
+
+const validModes = new Set(['dev', 'prod']);
+
+// These host directories back Docker bind mounts used by the stack services.
+const dataSubdirectories = [
+	'tempo',
+	'minio',
+	'redpanda',
+	'loki',
+	'mimir',
+	'prometheus',
+	'grafana',
+];
+
+// Each CLI port option maps to the environment variable consumed by docker-compose.yaml.
+const portOptions = {
+	'--grafana-port': ['GRAFANA_PORT', '3000'],
+	'--otlp-grpc-port': ['OTLP_GRPC_PORT', '4317'],
+	'--otlp-http-port': ['OTLP_HTTP_PORT', '4318'],
+	'--tempo-port': ['TEMPO_PORT', '3200'],
+	'--loki-port': ['LOKI_PORT', '3100'],
+	'--prometheus-port': ['PROMETHEUS_PORT', '9090'],
+	'--mimir-port': ['MIMIR_PORT', '9009'],
+	'--minio-console-port': ['MINIO_CONSOLE_PORT', '9001'],
+	'--redpanda-port': ['REDPANDA_PORT', '9092'],
+	'--redpanda-console-port': ['REDPANDA_CONSOLE_PORT', '8080'],
+	'--alloy-port': ['ALLOY_PORT', '12345'],
+};
+
+// The open command uses these service targets to build local browser URLs.
+const urlTargets = {
+	grafana: ['GRAFANA_PORT', '3000', '/'],
+	minio: ['MINIO_CONSOLE_PORT', '9001', '/'],
+	prometheus: ['PROMETHEUS_PORT', '9090', '/'],
+	tempo: ['TEMPO_PORT', '3200', '/'],
+	loki: ['LOKI_PORT', '3100', '/ready'],
+	mimir: ['MIMIR_PORT', '9009', '/'],
+	redpanda: ['REDPANDA_CONSOLE_PORT', '8080', '/'],
+};
+
+function printUsage() {
+	console.log(`Usage:
+  telemetry-stack init <data-dir> [options]
+  telemetry-stack up <data-dir> [options]
+  telemetry-stack down <data-dir> [options]
+  telemetry-stack restart <data-dir> [options]
+  telemetry-stack ps <data-dir> [options]
+  telemetry-stack logs <data-dir> [service] [options]
+  telemetry-stack open <data-dir> [target] [options]
+  telemetry-stack config <data-dir> [options]
+  telemetry-stack doctor
+
+Options:
+  --name <name>                  Override Docker Compose project name.
+  --mode <dev|prod>              Instance mode for newly created config. Default: dev
+
+Port options:
+  --grafana-port <port>          Default: 3000
+  --otlp-grpc-port <port>        Default: 4317
+  --otlp-http-port <port>        Default: 4318
+  --tempo-port <port>            Default: 3200
+  --loki-port <port>             Default: 3100
+  --prometheus-port <port>       Default: 9090
+  --mimir-port <port>            Default: 9009
+  --minio-console-port <port>    Default: 9001
+  --redpanda-port <port>         Default: 9092
+  --redpanda-console-port <port> Default: 8080
+  --alloy-port <port>            Default: 12345
+
+Logs options:
+  --follow, -f                   Follow log output. Only for logs.
+  --tail <lines>                 Number of log lines to show. Only for logs.
+
+Examples:
+  telemetry-stack init ./data/telemetry --mode prod
+  telemetry-stack up ./data/telemetry
+  telemetry-stack up ./data/telemetry --grafana-port 3300 --otlp-http-port 14318
+  telemetry-stack logs ./data/telemetry alloy --follow --tail 100
+  telemetry-stack open ./data/telemetry grafana`);
+}
+
+function fail(message, exitCode = 1) {
+	console.error(`[!] ${message}`);
+	process.exit(exitCode);
+}
+
+function isIntegerPort(value) {
+	const port = Number(value);
+	return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+
+function validatePort(flag, value) {
+	if (!isIntegerPort(value)) {
+		fail(`${flag} must be a TCP port number in the range 1-65535.`);
+	}
+}
+
+function validateProjectName(name) {
+	// Docker Compose project names have strict rules, so validate early and
+	// return a clearer message than the raw docker compose error.
+	if (!/^[a-z0-9][a-z0-9_-]*$/.test(name)) {
+		fail('--name must start with a lowercase letter or number and may contain only lowercase letters, numbers, _ and -.');
+	}
+}
+
+function validateMode(mode) {
+	if (!validModes.has(mode)) {
+		fail('--mode must be either dev or prod.');
+	}
+}
+
+function parseArguments(argv) {
+	// Keep parsing dependency-free so the package can run directly through npx.
+	const command = argv[2];
+
+	if (!command || command === '-h' || command === '--help') {
+		printUsage();
+		process.exit(command ? 0 : 1);
+	}
+
+	const options = {
+		name: undefined,
+		mode: undefined,
+		ports: {},
+		follow: false,
+		tail: undefined,
+	};
+	const positionals = [];
+	const args = argv.slice(3);
+
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+
+		if (arg === '-h' || arg === '--help') {
+			printUsage();
+			process.exit(0);
+		}
+
+		if (arg === '--name') {
+			const value = args[++i];
+			if (!value) {
+				fail('--name requires a value.');
+			}
+			validateProjectName(value);
+			options.name = value;
+			continue;
+		}
+
+		if (arg === '--mode') {
+			const value = args[++i];
+			if (!value) {
+				fail('--mode requires a value.');
+			}
+			validateMode(value);
+			options.mode = value;
+			continue;
+		}
+
+		if (arg in portOptions) {
+			const value = args[++i];
+			if (!value) {
+				fail(`${arg} requires a value.`);
+			}
+			validatePort(arg, value);
+			options.ports[portOptions[arg][0]] = value;
+			continue;
+		}
+
+		if (arg === '--follow' || arg === '-f') {
+			options.follow = true;
+			continue;
+		}
+
+		if (arg === '--tail') {
+			const value = args[++i];
+			if (!value || !/^[0-9]+$/.test(value)) {
+				fail('--tail requires a non-negative integer.');
+			}
+			options.tail = value;
+			continue;
+		}
+
+		if (arg.startsWith('-')) {
+			fail(`Unknown option: ${arg}`);
+		}
+
+		positionals.push(arg);
+	}
+
+	return {
+		command,
+		positionals,
+		options,
+	};
+}
+
+function validateCommandOptions(command, options) {
+	if (command !== 'logs' && (options.follow || options.tail !== undefined)) {
+		fail('--follow, -f and --tail can be used only with the logs command.');
+	}
+}
+
+function resolveDataDir(rawDataDir) {
+	if (!rawDataDir) {
+		fail('Missing <data-dir>. This directory is where telemetry stack data will be stored.');
+	}
+
+	return path.resolve(process.cwd(), rawDataDir);
+}
+
+function deriveProjectName(dataDir, explicitName) {
+	if (explicitName) {
+		return explicitName;
+	}
+
+	// A stable hash of the absolute data directory makes the same data directory
+	// control the same Docker Compose project without requiring --name.
+	const hash = crypto.createHash('sha1').update(dataDir).digest('hex').slice(0, 8);
+	return `telemetry-stack-${hash}`;
+}
+
+function instanceConfigPath(dataDir) {
+	return path.join(dataDir, instanceConfigFileName);
+}
+
+function generatedConfigDirectory(dataDir) {
+	return path.join(dataDir, generatedConfigDirectoryName);
+}
+
+function randomToken(bytes = 32) {
+	return crypto.randomBytes(bytes)
+		.toString('base64')
+		.replace(/\+/g, '-')
+		.replace(/\//g, '_')
+		.replace(/=+$/g, '');
+}
+
+function makeDefaultInstanceConfig(mode) {
+	validateMode(mode);
+
+	if (mode === 'prod') {
+		return {
+			TELEMETRY_MODE: 'prod',
+			TELEMETRY_BIND_ADDRESS: '127.0.0.1',
+			TELEMETRY_MINIO_ACCESS_KEY: `telemetry_${randomToken(12)}`,
+			TELEMETRY_MINIO_SECRET_KEY: randomToken(32),
+			GRAFANA_ANONYMOUS_ENABLED: 'false',
+			GRAFANA_ANONYMOUS_ORG_ROLE: 'Viewer',
+			GRAFANA_DISABLE_LOGIN_FORM: 'false',
+			GRAFANA_ADMIN_USER: 'admin',
+			GRAFANA_ADMIN_PASSWORD: randomToken(32),
+		};
+	}
+
+	return {
+		TELEMETRY_MODE: 'dev',
+		TELEMETRY_BIND_ADDRESS: '0.0.0.0',
+		TELEMETRY_MINIO_ACCESS_KEY: 'telemetry',
+		TELEMETRY_MINIO_SECRET_KEY: 'supersecret',
+		GRAFANA_ANONYMOUS_ENABLED: 'true',
+		GRAFANA_ANONYMOUS_ORG_ROLE: 'Admin',
+		GRAFANA_DISABLE_LOGIN_FORM: 'true',
+		GRAFANA_ADMIN_USER: 'admin',
+		GRAFANA_ADMIN_PASSWORD: 'admin',
+	};
+}
+
+function formatInstanceConfig(values) {
+	const lines = [
+		'# Generated by @primafuture/telemetry-stack.',
+		'# This file belongs to one telemetry stack data directory.',
+		'# Do not commit production secrets.',
+		'',
+	];
+
+	for (const key of instanceConfigKeys) {
+		lines.push(`${key}=${values[key]}`);
+	}
+
+	return `${lines.join('\n')}\n`;
+}
+
+function parseInstanceConfig(content, configPath) {
+	const values = {};
+
+	for (const [index, rawLine] of content.split(/\r?\n/).entries()) {
+		const line = rawLine.trim();
+		if (!line || line.startsWith('#')) {
+			continue;
+		}
+
+		const separatorIndex = line.indexOf('=');
+		if (separatorIndex === -1) {
+			fail(`Invalid line ${index + 1} in ${configPath}: expected KEY=value.`);
+		}
+
+		const key = line.slice(0, separatorIndex).trim();
+		const value = line.slice(separatorIndex + 1).trim();
+		values[key] = value;
+	}
+
+	return values;
+}
+
+function validateInstanceConfig(values, configPath) {
+	for (const key of instanceConfigKeys) {
+		if (!values[key]) {
+			fail(`Missing ${key} in ${configPath}.`);
+		}
+	}
+
+	validateMode(values.TELEMETRY_MODE);
+}
+
+function readInstanceConfig(configPath) {
+	const values = parseInstanceConfig(fs.readFileSync(configPath, 'utf8'), configPath);
+	validateInstanceConfig(values, configPath);
+	return values;
+}
+
+function writeInstanceConfig(configPath, values) {
+	fs.mkdirSync(path.dirname(configPath), { recursive: true });
+	fs.writeFileSync(configPath, formatInstanceConfig(values), {
+		flag: 'wx',
+		mode: 0o600,
+	});
+	fs.chmodSync(configPath, 0o600);
+}
+
+function resolveInstanceConfig(dataDir, requestedMode, createIfMissing) {
+	const configPath = instanceConfigPath(dataDir);
+
+	if (fs.existsSync(configPath)) {
+		const values = readInstanceConfig(configPath);
+		if (requestedMode && requestedMode !== values.TELEMETRY_MODE) {
+			fail(`Instance config already uses mode ${values.TELEMETRY_MODE}. Remove ${configPath} or use --mode ${values.TELEMETRY_MODE}.`);
+		}
+		return {
+			configPath,
+			values,
+			created: false,
+			persisted: true,
+		};
+	}
+
+	const values = makeDefaultInstanceConfig(requestedMode || 'dev');
+
+	if (!createIfMissing) {
+		return {
+			configPath,
+			values,
+			created: false,
+			persisted: false,
+		};
+	}
+
+	writeInstanceConfig(configPath, values);
+
+	return {
+		configPath,
+		values,
+		created: true,
+		persisted: true,
+	};
+}
+
+function yamlDoubleQuoted(value) {
+	return String(value)
+		.replace(/\\/g, '\\\\')
+		.replace(/"/g, '\\"');
+}
+
+function renderTemplate(template, values, templatePath) {
+	return template.replace(/\{\{([A-Z0-9_]+)\}\}/g, (match, key) => {
+		if (!(key in values)) {
+			fail(`Template ${templatePath} references missing value ${key}.`);
+		}
+		return yamlDoubleQuoted(values[key]);
+	});
+}
+
+function renderGeneratedConfigs(dataDir, instanceConfig) {
+	const targetDirectory = generatedConfigDirectory(dataDir);
+	fs.mkdirSync(targetDirectory, {
+		recursive: true,
+		mode: 0o700,
+	});
+	fs.chmodSync(targetDirectory, 0o700);
+
+	for (const [targetFileName, templatePath] of generatedConfigTemplates) {
+		const rendered = renderTemplate(fs.readFileSync(templatePath, 'utf8'), instanceConfig, templatePath);
+		const targetPath = path.join(targetDirectory, targetFileName);
+		fs.writeFileSync(targetPath, rendered, { mode: 0o644 });
+		fs.chmodSync(targetPath, 0o644);
+	}
+
+	return targetDirectory;
+}
+
+function makeEnvironment(dataDir, options, instanceConfig) {
+	// Docker Compose reads this environment to choose bind mounts and host ports.
+	const env = {
+		...process.env,
+		...instanceConfig,
+		TELEMETRY_DATA_DIR: dataDir,
+		TELEMETRY_GENERATED_CONFIG_DIR: generatedConfigDirectory(dataDir),
+	};
+
+	for (const [envName, value] of Object.entries(options.ports)) {
+		env[envName] = value;
+	}
+
+	return env;
+}
+
+function makeContext(rawDataDir, options, createConfig) {
+	// The context bundles all values every Docker Compose-backed command needs.
+	const dataDir = resolveDataDir(rawDataDir);
+	const projectName = deriveProjectName(dataDir, options.name);
+	const instance = resolveInstanceConfig(dataDir, options.mode, createConfig);
+	const generatedConfigDir = instance.persisted
+		? renderGeneratedConfigs(dataDir, instance.values)
+		: generatedConfigDirectory(dataDir);
+	const env = makeEnvironment(dataDir, options, instance.values);
+
+	return {
+		dataDir,
+		projectName,
+		env,
+		options,
+		instance,
+		generatedConfigDir,
+	};
+}
+
+function ensureDataDirectories(dataDir) {
+	// Docker could create missing bind-mount directories itself, often as root.
+	// Creating them first keeps ownership predictable for the current user.
+	fs.mkdirSync(dataDir, { recursive: true });
+
+	for (const directory of dataSubdirectories) {
+		fs.mkdirSync(path.join(dataDir, directory), { recursive: true });
+	}
+}
+
+function dockerComposeArgs(context, args) {
+	// Always call the compose file from inside the package and isolate instances by project name.
+	return [
+		'compose',
+		'-f',
+		composeFile,
+		'-p',
+		context.projectName,
+		...args,
+	];
+}
+
+function runDockerCompose(context, args, stdio = 'inherit') {
+	// The CLI delegates lifecycle operations to Docker Compose and only prepares arguments/env.
+	const result = spawnSync('docker', dockerComposeArgs(context, args), {
+		env: context.env,
+		stdio,
+	});
+
+	if (result.error) {
+		fail(`Unable to start docker: ${result.error.message}`);
+	}
+
+	return result.status ?? 1;
+}
+
+function getPort(env, envName, fallback) {
+	return env[envName] || fallback;
+}
+
+function openUrl(url) {
+	console.log(url);
+
+	if (process.platform !== 'linux') {
+		return;
+	}
+
+	// xdg-open is a convenience for Linux desktops. If it is unavailable, the
+	// command still succeeds because the URL was already printed above.
+	const result = spawnSync('xdg-open', [url], {
+		stdio: 'ignore',
+	});
+
+	if (result.error) {
+		return;
+	}
+}
+
+function runDoctor() {
+	// Doctor checks local prerequisites without starting or changing the stack.
+	let failed = false;
+
+	const checks = [
+		['node', ['--version']],
+		['docker', ['--version']],
+		['docker', ['compose', 'version']],
+		['docker', ['info']],
+	];
+
+	for (const [command, args] of checks) {
+		const result = spawnSync(command, args, {
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'pipe'],
+		});
+
+		if (result.error || result.status !== 0) {
+			failed = true;
+			console.log(`[FAIL] ${command} ${args.join(' ')}`);
+			if (result.error) {
+				console.log(`       ${result.error.message}`);
+			} else if (result.stderr.trim()) {
+				console.log(`       ${result.stderr.trim().split('\n')[0]}`);
+			}
+			continue;
+		}
+
+		const output = `${result.stdout}${result.stderr}`.trim().split('\n')[0];
+		console.log(`[OK] ${command} ${args.join(' ')}${output ? ` -> ${output}` : ''}`);
+	}
+
+	if (!fs.existsSync(composeFile)) {
+		failed = true;
+		console.log(`[FAIL] compose file missing: ${composeFile}`);
+	} else {
+		console.log(`[OK] compose file -> ${composeFile}`);
+	}
+
+	process.exit(failed ? 1 : 0);
+}
+
+function printInitResult(context) {
+	const action = context.instance.created ? 'Created' : 'Using existing';
+	console.log(`${action} config: ${context.instance.configPath}`);
+	console.log(`Generated service configs: ${context.generatedConfigDir}`);
+	console.log(`Mode: ${context.instance.values.TELEMETRY_MODE}`);
+	console.log(`Grafana user: ${context.instance.values.GRAFANA_ADMIN_USER}`);
+	console.log(`Grafana password: stored in ${context.instance.configPath}`);
+}
+
+function run() {
+	// Command dispatch stays explicit so the public CLI surface is easy to audit.
+	const { command, positionals, options } = parseArguments(process.argv);
+	validateCommandOptions(command, options);
+
+	if (command === 'doctor') {
+		runDoctor();
+		return;
+	}
+
+	const createConfig = command === 'init' || command === 'up' || command === 'restart' || command === 'config';
+	const context = makeContext(positionals[0], options, createConfig);
+
+	if (command === 'init') {
+		ensureDataDirectories(context.dataDir);
+		printInitResult(context);
+		return;
+	}
+
+	if (command === 'up') {
+		ensureDataDirectories(context.dataDir);
+		process.exit(runDockerCompose(context, ['up', '-d']));
+	}
+
+	if (command === 'down') {
+		process.exit(runDockerCompose(context, ['down']));
+	}
+
+	if (command === 'restart') {
+		ensureDataDirectories(context.dataDir);
+		const downStatus = runDockerCompose(context, ['down']);
+		if (downStatus !== 0) {
+			process.exit(downStatus);
+		}
+		process.exit(runDockerCompose(context, ['up', '-d']));
+	}
+
+	if (command === 'ps') {
+		process.exit(runDockerCompose(context, ['ps']));
+	}
+
+	if (command === 'logs') {
+		const service = positionals[1];
+		const args = ['logs'];
+		if (options.follow) {
+			args.push('--follow');
+		}
+		if (options.tail !== undefined) {
+			args.push('--tail', options.tail);
+		}
+		if (service) {
+			args.push(service);
+		}
+		process.exit(runDockerCompose(context, args));
+	}
+
+	if (command === 'open') {
+		const target = positionals[1] || 'grafana';
+		const targetConfig = urlTargets[target];
+		if (!targetConfig) {
+			fail(`Unknown open target: ${target}`);
+		}
+		const [envName, fallbackPort, urlPath] = targetConfig;
+		const port = getPort(context.env, envName, fallbackPort);
+		openUrl(`http://localhost:${port}${urlPath}`);
+		return;
+	}
+
+	if (command === 'config') {
+		process.exit(runDockerCompose(context, ['config']));
+	}
+
+	fail(`Unknown command: ${command}`);
+}
+
+run();

package/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "@primafuture/telemetry-stack",
+	"version": "0.1.0",
+	"type": "module",
+	"description": "Reusable PrimaFuture telemetry stack launcher powered by Docker Compose.",
+	"author": "PrimaFuture.cz s.r.o. <dev@primafuture.cz>",
+	"license": "ISC",
+	"publishConfig": {
+		"access": "public"
+	},
+	"bin": {
+		"telemetry-stack": "bin/telemetry-stack.mjs"
+	},
+	"files": [
+		"bin",
+		"stack",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"scripts": {
+		"check": "node --check ./bin/telemetry-stack.mjs",
+		"test:package": "npm pack --dry-run"
+	}
+}