@aurostack/stacks 0.1.1 → 0.2.1

package/templates/nest-api/files/src/common/services/temporal.service.ts

@@ -0,0 +1,66 @@
+import { Injectable, OnApplicationShutdown } from '@nestjs/common';
+import { Client, Connection, type TLSConfig } from '@temporalio/client';
+import { CustomConfigService } from './config.service';
+import type Config from './config.service';
+
+/**
+ * A Temporal client for starting and querying workflows; a worker (node-worker
+ * or py-worker) polling the same namespace and task queue runs them.
+ *
+ * The connection is lazy: nothing is dialled until the first call, so the API
+ * boots, and serves everything else, while Temporal is unreachable.
+ *
+ * ```ts
+ * const handle = await this.temporal.client.workflow.start('example', {
+ *   taskQueue: this.temporal.taskQueue,
+ *   workflowId: `example-${user.id}`, // one run per id: a natural dedupe key
+ *   args: [{ name: user.name }]
+ * });
+ * const result = await handle.result(); // or return handle.workflowId
+ * ```
+ *
+ * Reach for Temporal over the BullMQ queue when the work spans many steps,
+ * waits (for minutes to months, or on a signal), or must resume exactly where
+ * it stopped after a crash. A fire-and-forget job is still a queue job.
+ */
+@Injectable()
+export class TemporalService implements OnApplicationShutdown {
+	readonly client: Client;
+	/** The default task queue, from TEMPORAL_TASK_QUEUE. */
+	readonly taskQueue: string;
+	private readonly connection: Connection;
+
+	constructor(config: CustomConfigService) {
+		const { address, namespace, taskQueue, tls } = config.temporal;
+		this.connection = Connection.lazy({ address, tls: temporalTls(tls) });
+		this.client = new Client({ connection: this.connection, namespace });
+		this.taskQueue = taskQueue;
+	}
+
+	async onApplicationShutdown() {
+		await this.connection.close();
+	}
+}
+
+/**
+ * mTLS settings from PEM strings; none at all means plaintext (`null`).
+ * Escaped `\n` are unescaped, so a certificate fits on one line of an env
+ * file.
+ */
+export function temporalTls({
+	ca,
+	cert,
+	key
+}: Config.Temporal['tls']): TLSConfig | null {
+	if (!ca && !cert && !key) return null;
+	if (!cert || !key) {
+		throw new Error(
+			'TEMPORAL_TLS_CERT and TEMPORAL_TLS_KEY must be set together'
+		);
+	}
+	const pem = (value: string) => Buffer.from(value.replace(/\\n/g, '\n'));
+	return {
+		...(ca && { serverRootCACertificate: pem(ca) }),
+		clientCertPair: { crt: pem(cert), key: pem(key) }
+	};
+}

package/templates/nest-api/files/src/instrumentation.ts

@@ -0,0 +1,117 @@
+/**
+ * OpenTelemetry bootstrap: traces, logs and metrics over OTLP. main.ts imports
+ * this first, because instrumentation has to patch modules before anything
+ * requires them. Connection settings are in src/telemetry/config.ts; without
+ * them this file does nothing.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { register } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { resolveTelemetry } from './telemetry/config';
+
+// Nest reads .env later, through ConfigModule; the connection settings are
+// needed now. Already-set variables (Docker, the shell) are never overridden.
+try {
+	process.loadEnvFile();
+} catch {
+	// no .env — the environment is configured some other way
+}
+
+const telemetry = resolveTelemetry();
+
+if (telemetry.enabled) {
+	// Nest 12 and many of its dependencies load as ESM, which require-hooks do
+	// not see; import-in-the-middle lets instrumentations patch those too.
+	register('import-in-the-middle/hook.mjs', pathToFileURL(__filename));
+	start();
+}
+
+function start() {
+	/* eslint-disable @typescript-eslint/no-require-imports */
+	// Required lazily so a project with telemetry off never loads the SDK, and
+	// typed so the compiler still checks every constructor call below.
+	const { NodeSDK } =
+		require('@opentelemetry/sdk-node') as typeof import('@opentelemetry/sdk-node');
+	const { getNodeAutoInstrumentations } =
+		require('@opentelemetry/auto-instrumentations-node') as typeof import('@opentelemetry/auto-instrumentations-node');
+	const { OTLPTraceExporter } =
+		require('@opentelemetry/exporter-trace-otlp-proto') as typeof import('@opentelemetry/exporter-trace-otlp-proto');
+	const { OTLPLogExporter } =
+		require('@opentelemetry/exporter-logs-otlp-proto') as typeof import('@opentelemetry/exporter-logs-otlp-proto');
+	const { OTLPMetricExporter } =
+		require('@opentelemetry/exporter-metrics-otlp-proto') as typeof import('@opentelemetry/exporter-metrics-otlp-proto');
+	const { BatchLogRecordProcessor } =
+		require('@opentelemetry/sdk-logs') as typeof import('@opentelemetry/sdk-logs');
+	const { PeriodicExportingMetricReader } =
+		require('@opentelemetry/sdk-metrics') as typeof import('@opentelemetry/sdk-metrics');
+	const { resourceFromAttributes } =
+		require('@opentelemetry/resources') as typeof import('@opentelemetry/resources');
+	const { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } =
+		require('@opentelemetry/semantic-conventions') as typeof import('@opentelemetry/semantic-conventions');
+	const { ExpressLayerType } =
+		require('@opentelemetry/instrumentation-express') as typeof import('@opentelemetry/instrumentation-express');
+	const { PrismaInstrumentation } =
+		require('@prisma/instrumentation') as typeof import('@prisma/instrumentation');
+	/* eslint-enable @typescript-eslint/no-require-imports */
+
+	const { urls, headers } = telemetry;
+	// Explicit URLs always come with their headers; without them the SDK reads
+	// OTEL_EXPORTER_OTLP_* itself.
+	const exporter = (url?: string) => (url && headers ? { url, headers } : {});
+
+	const sdk = new NodeSDK({
+		resource: resourceFromAttributes({
+			[ATTR_SERVICE_NAME]: telemetry.serviceName,
+			[ATTR_SERVICE_VERSION]: packageVersion(),
+			'deployment.environment.name': telemetry.environment
+		}),
+		traceExporter: new OTLPTraceExporter(exporter(urls?.traces)),
+		logRecordProcessors: [
+			new BatchLogRecordProcessor({
+				exporter: new OTLPLogExporter(exporter(urls?.logs))
+			})
+		],
+		metricReaders: [
+			new PeriodicExportingMetricReader({
+				exporter: new OTLPMetricExporter(exporter(urls?.metrics)),
+				exportIntervalMillis:
+					Number(process.env.OTEL_METRIC_EXPORT_INTERVAL) || 60_000
+			})
+		],
+		instrumentations: [
+			getNodeAutoInstrumentations({
+				// Every file read and DNS lookup as a span is noise, not signal.
+				'@opentelemetry/instrumentation-fs': { enabled: false },
+				'@opentelemetry/instrumentation-dns': { enabled: false },
+				'@opentelemetry/instrumentation-net': { enabled: false },
+				// One span per request handler, not one per middleware layer. Express
+				// 5 routes through the `router` package, whose own instrumentation
+				// would add a span for every layer again.
+				'@opentelemetry/instrumentation-express': {
+					ignoreLayersType: [ExpressLayerType.MIDDLEWARE]
+				},
+				'@opentelemetry/instrumentation-router': { enabled: false }
+			}),
+			new PrismaInstrumentation()
+		]
+	});
+	sdk.start();
+
+	// Flush what is buffered on the way out, then let the signal do what it
+	// would have done without a handler.
+	for (const signal of ['SIGTERM', 'SIGINT'] as const) {
+		process.once(signal, () => {
+			sdk.shutdown().finally(() => process.kill(process.pid, signal));
+		});
+	}
+}
+
+function packageVersion(): string | undefined {
+	try {
+		const file = path.join(process.cwd(), 'package.json');
+		return JSON.parse(fs.readFileSync(file, 'utf8')).version;
+	} catch {
+		return undefined;
+	}
+}

package/templates/nest-api/files/src/main.ts

@@ -1,3 +1,5 @@
+// Must stay first: instrumentation patches modules before anything loads them.
+import './instrumentation'; // @feature observability
 import { NestFactory } from '@nestjs/core';
 import { AppModule } from 'app.module';
 import * as setup from './app.setup';
@@ -11,7 +13,7 @@ import * as setup from './app.setup';
 		bufferLogs: true
 	});
 	setup.usePinoLogger(app);
-	setup.enableBasicAuth(app); // @feature openapi, queue, observability
+	setup.enableBasicAuth(app); // @feature openapi, queue
 	setup.enableVersioning(app);
 	setup.setStatic(app);
 	setup.enableJsonBodyParser(app);

package/templates/nest-api/files/src/notifications/services/notifications.service.ts

@@ -2,7 +2,7 @@ import { Injectable, NotFoundException } from '@nestjs/common';
 import { NotificationType, Prisma } from '@db/client';
 import { PrismaService, LoggerService } from 'common/services';
 import { ok } from 'common/entity';
-import { RealtimeService } from 'realtime/services/realtime.service';
+import { RealtimeService } from 'realtime/services/realtime.service'; // @feature realtime
 import {
 	NotificationEntity,
 	PaginatedNotificationEntity,
@@ -14,7 +14,7 @@ import { NotificationFilters } from '../dto';
 export class NotificationsService {
 	constructor(
 		private readonly db: PrismaService,
-		private readonly realtime: RealtimeService,
+		private readonly realtime: RealtimeService, // @feature realtime
 		private readonly logger: LoggerService
 	) {}
 
@@ -36,9 +36,11 @@ export class NotificationsService {
 			const notification = await this.db.notification.create({
 				data: { userId, type, data }
 			});
+			// @feature:start realtime
 			// Sockets bypass the HTTP serializer; encode through the same schema so
 			// the event has exactly the shape the REST endpoints return.
 			this.realtime.notifyUser(userId, NotificationEntity.parse(notification));
+			// @feature:end
 			return notification;
 		} catch (err) {
 			this.logger.warn(

package/templates/nest-api/files/src/telemetry/__tests__/config.spec.ts

@@ -0,0 +1,67 @@
+import { resolveTelemetry } from '../config';
+
+describe('resolveTelemetry', () => {
+	const openobserve = {
+		OPENOBSERVE_URL: 'https://o2.example.com/',
+		OPENOBSERVE_ORG: 'acme',
+		OPENOBSERVE_TOKEN: 'o2oi_secret'
+	};
+
+	it('stays off without connection settings', () => {
+		expect(resolveTelemetry({}).enabled).toBe(false);
+	});
+
+	it.each(['OPENOBSERVE_URL', 'OPENOBSERVE_ORG', 'OPENOBSERVE_TOKEN'])(
+		'stays off when %s is missing',
+		(key) => {
+			const env: Record<string, string | undefined> = { ...openobserve };
+			delete env[key];
+			expect(resolveTelemetry(env).enabled).toBe(false);
+		}
+	);
+
+	it('builds the OpenObserve endpoints and org-token auth', () => {
+		const config = resolveTelemetry(openobserve, 'acme-api');
+
+		expect(config.enabled).toBe(true);
+		expect(config.urls).toEqual({
+			traces: 'https://o2.example.com/api/acme/v1/traces',
+			logs: 'https://o2.example.com/api/acme/v1/logs',
+			metrics: 'https://o2.example.com/api/acme/v1/metrics'
+		});
+		expect(config.headers).toEqual({
+			Authorization: `Basic ${Buffer.from('acme:o2oi_secret').toString('base64')}`,
+			'stream-name': 'acme-api'
+		});
+	});
+
+	it('uses OTEL_SERVICE_NAME, APP_ENV and OPENOBSERVE_STREAM', () => {
+		const config = resolveTelemetry({
+			...openobserve,
+			OTEL_SERVICE_NAME: 'billing-api',
+			APP_ENV: 'production',
+			OPENOBSERVE_STREAM: 'api'
+		});
+
+		expect(config.serviceName).toBe('billing-api');
+		expect(config.environment).toBe('production');
+		expect(config.headers?.['stream-name']).toBe('api');
+	});
+
+	it('defers to the standard OTEL_* variables when they are set', () => {
+		const config = resolveTelemetry({
+			...openobserve,
+			OTEL_EXPORTER_OTLP_ENDPOINT: 'https://collector.example.com'
+		});
+
+		expect(config.enabled).toBe(true);
+		expect(config.urls).toBeUndefined();
+		expect(config.headers).toBeUndefined();
+	});
+
+	it('honours OTEL_SDK_DISABLED over everything', () => {
+		expect(
+			resolveTelemetry({ ...openobserve, OTEL_SDK_DISABLED: 'true' }).enabled
+		).toBe(false);
+	});
+});

package/templates/nest-api/files/src/telemetry/config.ts

@@ -0,0 +1,62 @@
+/**
+ * Where telemetry goes, resolved from the environment before anything else
+ * loads (instrumentation runs ahead of Nest, so it cannot use
+ * CustomConfigService — this is the one place that reads process.env for it).
+ *
+ * Two ways to connect, in order of precedence:
+ * - standard OpenTelemetry variables (OTEL_EXPORTER_OTLP_ENDPOINT and friends),
+ *   which the SDK reads itself, for any OTLP backend;
+ * - OPENOBSERVE_URL + OPENOBSERVE_ORG + OPENOBSERVE_TOKEN, from which the
+ *   OpenObserve endpoint and auth header are built.
+ * With neither, telemetry stays off and the SDK is never started.
+ */
+export interface TelemetryConfig {
+	enabled: boolean;
+	serviceName: string;
+	environment: string;
+	/** Signal URLs; undefined means the SDK resolves them from OTEL_* vars. */
+	urls?: { traces: string; logs: string; metrics: string };
+	headers?: Record<string, string>;
+}
+
+type Env = Record<string, string | undefined>;
+
+export function resolveTelemetry(
+	env: Env = process.env,
+	defaultServiceName = 'acme-api'
+): TelemetryConfig {
+	const serviceName = env.OTEL_SERVICE_NAME || defaultServiceName;
+	const environment = env.APP_ENV || 'development';
+	const off = { enabled: false, serviceName, environment };
+
+	if (env.OTEL_SDK_DISABLED === 'true') return off;
+	if (env.OTEL_EXPORTER_OTLP_ENDPOINT) {
+		return { enabled: true, serviceName, environment };
+	}
+
+	const {
+		OPENOBSERVE_URL: url,
+		OPENOBSERVE_ORG: org,
+		OPENOBSERVE_TOKEN: token
+	} = env;
+	if (!url || !org || !token) return off;
+
+	// OTLP/HTTP endpoints live under /api/<org>; an org ingestion token
+	// authenticates as `<org>:<token>`. Logs and traces land in the stream
+	// named here — one per service keeps an API and its workers apart.
+	const base = `${url.replace(/\/+$/, '')}/api/${org}`;
+	return {
+		enabled: true,
+		serviceName,
+		environment,
+		urls: {
+			traces: `${base}/v1/traces`,
+			logs: `${base}/v1/logs`,
+			metrics: `${base}/v1/metrics`
+		},
+		headers: {
+			Authorization: `Basic ${Buffer.from(`${org}:${token}`).toString('base64')}`,
+			'stream-name': env.OPENOBSERVE_STREAM || serviceName
+		}
+	};
+}

package/templates/nest-api/template.json

@@ -47,6 +47,12 @@
 			"regex": true,
 			"flags": "gm"
 		},
+		{
+			"from": "^(SERVER_HOST|BETTER_AUTH_URL)='http://localhost:5000'$",
+			"to": "$1='http://localhost:{{port}}'",
+			"regex": true,
+			"flags": "gm"
+		},
 		{
 			"from": "^EXPOSE 5000$",
 			"to": "EXPOSE {{port}}",
@@ -104,7 +110,8 @@
 					"bullmq",
 					"@bull-board/api",
 					"@bull-board/express",
-					"@bull-board/nestjs"
+					"@bull-board/nestjs",
+					"bullmq-otel"
 				]
 			}
 		},
@@ -168,23 +175,38 @@
 			"core": true
 		},
 		"observability": {
-			"title": "Metrics and health checks",
-			"description": "A Prometheus /metrics endpoint and Terminus health checks, including a Prisma indicator. Structured pino logging is always included.",
+			"title": "Observability: OpenTelemetry and health checks",
+			"description": "OpenTelemetry traces, logs and metrics pushed over OTLP (built for OpenObserve; set OPENOBSERVE_URL/ORG/TOKEN, or any OTEL_* backend), plus Terminus health checks with a Prisma indicator. Off at runtime until connected.",
+			"requires": [
+				"http-client"
+			],
 			"default": true,
 			"files": [
-				"src/common/modules/metrics.module.ts",
-				"src/common/controllers/metrics.controller.ts",
 				"src/common/controllers/health.controller.ts",
-				"src/common/interceptors/metrics.interceptor.ts",
 				"src/common/misc/prisma.indicator.ts",
 				"src/common/__tests__/health.controller.spec.ts",
-				"src/common/__tests__/prisma.indicator.spec.ts"
+				"src/common/__tests__/prisma.indicator.spec.ts",
+				"src/instrumentation.ts",
+				"src/telemetry/**"
 			],
 			"packageJson": {
 				"dependencies": [
-					"prom-client",
-					"@willsoto/nestjs-prometheus",
-					"@nestjs/terminus"
+					"@nestjs/terminus",
+					"@opentelemetry/api",
+					"@opentelemetry/core",
+					"@opentelemetry/sdk-node",
+					"@opentelemetry/auto-instrumentations-node",
+					"@opentelemetry/exporter-trace-otlp-proto",
+					"@opentelemetry/exporter-logs-otlp-proto",
+					"@opentelemetry/exporter-metrics-otlp-proto",
+					"@opentelemetry/sdk-logs",
+					"@opentelemetry/sdk-metrics",
+					"@opentelemetry/resources",
+					"@opentelemetry/semantic-conventions",
+					"@opentelemetry/instrumentation",
+					"@opentelemetry/instrumentation-express",
+					"import-in-the-middle",
+					"@prisma/instrumentation"
 				]
 			}
 		},
@@ -204,10 +226,11 @@
 		"media": {
 			"title": "File uploads (S3)",
 			"description": "MediaService and S3Service for public and private uploads, with multipart decorators.",
-			"default": true,
 			"requires": [
-				"auth"
+				"auth",
+				"queue"
 			],
+			"default": true,
 			"files": [
 				"src/media/**",
 				"src/users/dto/avatar.dto.ts"
@@ -263,7 +286,7 @@
 		},
 		"notifications": {
 			"title": "Persistent user notifications",
-			"description": "A Notification model plus dispatch/read endpoints. Emits over the realtime layer when that feature is also on, and persists either way.",
+			"description": "A Notification model plus dispatch/read endpoints. Pushes each new notification over the realtime layer when that feature is also on, and persists either way.",
 			"requires": [
 				"auth"
 			],
@@ -278,7 +301,8 @@
 			"description": "A session-aware FeatureFlagGuard and FeatureFlagService for gating routes on flags.",
 			"requires": [
 				"cache",
-				"auth"
+				"auth",
+				"scheduler"
 			],
 			"files": [
 				"src/common/services/feature-flag.service.ts",
@@ -290,6 +314,19 @@
 				]
 			}
 		},
+		"temporal": {
+			"title": "Temporal client",
+			"description": "A TemporalService for starting and querying durable workflows (multi-step, long-waiting or crash-resumable work; BullMQ stays for fire-and-forget jobs), plus Temporal's dev server in compose.yml. Pair it with node-worker or py-worker built --with temporal to run the workflows. Connects lazily, so the API runs while Temporal is down.",
+			"files": [
+				"src/common/services/temporal.service.ts",
+				"src/common/__tests__/temporal.service.spec.ts"
+			],
+			"packageJson": {
+				"dependencies": [
+					"@temporalio/client"
+				]
+			}
+		},
 		"graphql": {
 			"title": "GraphQL endpoint",
 			"description": "Code-first GraphQL via Apollo, registered alongside the REST controllers. Resolvers in any feature module are picked up automatically.",
@@ -382,6 +419,9 @@
 		"ci": {
 			"title": "Forgejo Actions CI",
 			"description": "A workflow that spins up the test stack and runs both Vitest projects on pull requests.",
+			"requires": [
+				"secrets"
+			],
 			"default": true,
 			"files": [
 				".forgejo/**"

package/templates/node-worker/files/.bin/secrets.ts

@@ -1,3 +1,4 @@
+import fs from 'node:fs';
 import shell from 'shelljs';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
@@ -52,9 +53,7 @@ const getCmd = (env: string) => {
 	if (!PROJECT_ID) {
 		throw new Error('INFISICAL_PROJECT_ID is not set — nothing to fetch from.');
 	}
-	return `infisical export --projectId="${PROJECT_ID}" --path=${SECRET_PATH} --env=${env} > ${getEnvFile(
-		env
-	)}`;
+	return `infisical export --projectId="${PROJECT_ID}" --path=${SECRET_PATH} --env=${env}`;
 };
 
 const log = (env: string) => console.log(`Fetching secrets for '${env}'...`);
@@ -62,7 +61,17 @@ const log = (env: string) => console.log(`Fetching secrets for '${env}'...`);
 (async () => {
 	const env = await getArg();
 	const command = getCmd(env);
+	const file = getEnvFile(env);
 	log(env);
-	shell.exec(command);
-	process.exit(0);
-})().catch(console.error);
+	// Export first and write only on success: a shell `>` redirect would empty
+	// the existing file before infisical had the chance to fail.
+	const result = shell.exec(command, { silent: true });
+	if (result.code !== 0) {
+		throw new Error(result.stderr.trim() || `infisical exited with ${result.code}`);
+	}
+	fs.writeFileSync(file, result.stdout);
+	console.log(`Wrote ${file}`);
+})().catch((err: unknown) => {
+	console.error(err instanceof Error ? err.message : err);
+	process.exit(1);
+});

package/templates/node-worker/files/.env.example

@@ -13,6 +13,33 @@ REDIS_HOST='localhost'
 REDIS_PORT='6379'
 REDIS_USER=''
 REDIS_PASSWORD=''
+# @feature:start telemetry
+
+# OpenTelemetry → OpenObserve: traces, logs and metrics. Leave empty and
+# telemetry stays off. Per project: OPENOBSERVE_ORG is the organization
+# identifier, OPENOBSERVE_TOKEN its ingestion token (IAM → Ingestion Tokens).
+# Any other OTLP backend: set OTEL_EXPORTER_OTLP_ENDPOINT/HEADERS instead.
+OPENOBSERVE_URL='https://o2.aurostack.co'
+OPENOBSERVE_ORG=''
+OPENOBSERVE_TOKEN=''
+OTEL_SERVICE_NAME='collector'
+# @feature:end
+
+# @feature:start temporal
+# Temporal: this process also runs the workflows in src/temporal. Locally, the
+# API's dev server (its compose.yml; UI on http://localhost:8233), no TLS. In
+# production, the server address, the project's namespace and its mTLS client
+# certificate (plus the CA that signed the server's), as PEM. Escaped \n are
+# accepted, so each fits on one line.
+TEMPORAL_ADDRESS='localhost:7233'
+TEMPORAL_NAMESPACE='default'
+# The queue this worker polls; must match where the API starts workflows (its
+# TEMPORAL_TASK_QUEUE). A mismatch is silent: workflows just sit waiting.
+TEMPORAL_TASK_QUEUE='main'
+TEMPORAL_TLS_CA=''
+TEMPORAL_TLS_CERT=''
+TEMPORAL_TLS_KEY=''
+# @feature:end
 
 # @feature:start browser
 # Empty = use Puppeteer's bundled Chromium. Set this in a slim container image

package/templates/node-worker/files/Dockerfile

@@ -1,5 +1,11 @@
 # Stage 1: Build
+# @feature:start temporal
+# Temporal's native core ships glibc builds only (it fails to load on Alpine,
+# even with gcompat), so a Temporal worker builds and runs on Debian.
+FROM node:24-bookworm-slim AS build
+# @feature:else
 FROM aurostack.dev/wesnetech/nodejs:24 AS build
+# @feature:end
 
 # @feature:start browser
 # Chromium comes from apk in the runtime stage; don't download a second copy.
@@ -31,10 +37,25 @@ RUN yarn build
 RUN yarn workspaces focus --all --production
 
 # Stage 2: Production
+# @feature:start temporal
+FROM node:24-bookworm-slim
+# @feature:else
 FROM aurostack.dev/wesnetech/nodejs:24
+# @feature:end
 WORKDIR /app
 
 # @feature:start browser
+# @feature:start temporal
+RUN apt-get update \
+	&& apt-get install -y --no-install-recommends \
+		chromium \
+		ca-certificates \
+		fonts-freefont-ttf \
+	&& rm -rf /var/lib/apt/lists/*
+
+ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
+	PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
+# @feature:else
 RUN apk add --no-cache \
 	chromium \
 	nss \
@@ -47,6 +68,7 @@ RUN apk add --no-cache \
 ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
 	PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
 # @feature:end
+# @feature:end
 
 COPY package.json ./
 # @feature:start pm2
@@ -56,8 +78,9 @@ COPY --from=build /app/node_modules ./node_modules
 COPY --from=build /app/dist ./dist
 
 # @feature:start pm2
-# pm2-runtime ships in the base image.
+# pm2-runtime ships in the house base image; Debian's needs it installed.
+RUN npm install -g pm2@7 # @feature temporal
 CMD [ "pm2-runtime", "start", "ecosystem.config.cjs" ]
 # @feature:else
-CMD [ "node", "dist/src/index.js" ]
+CMD [ "node", "--import", "./dist/src/instrumentation.js", "dist/src/index.js" ]
 # @feature:end

package/templates/node-worker/files/Dockerfile.dev

@@ -1,5 +1,11 @@
 # Stage 1: Build
+# @feature:start temporal
+# Temporal's native core ships glibc builds only (it fails to load on Alpine,
+# even with gcompat), so a Temporal worker builds and runs on Debian.
+FROM node:24-bookworm-slim AS build
+# @feature:else
 FROM aurostack.dev/wesnetech/nodejs:24 AS build
+# @feature:end
 
 # @feature:start browser
 # Chromium comes from apk in the runtime stage; don't download a second copy.
@@ -27,10 +33,25 @@ COPY src ./src
 RUN yarn build
 
 # Stage 2: Production
+# @feature:start temporal
+FROM node:24-bookworm-slim
+# @feature:else
 FROM aurostack.dev/wesnetech/nodejs:24
+# @feature:end
 WORKDIR /app
 
 # @feature:start browser
+# @feature:start temporal
+RUN apt-get update \
+	&& apt-get install -y --no-install-recommends \
+		chromium \
+		ca-certificates \
+		fonts-freefont-ttf \
+	&& rm -rf /var/lib/apt/lists/*
+
+ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
+	PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
+# @feature:else
 RUN apk add --no-cache \
 	chromium \
 	nss \
@@ -43,6 +64,7 @@ RUN apk add --no-cache \
 ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
 	PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
 # @feature:end
+# @feature:end
 
 COPY package.json ./
 # @feature:start pm2
@@ -52,8 +74,9 @@ COPY --from=build /app/node_modules ./node_modules
 COPY --from=build /app/dist ./dist
 
 # @feature:start pm2
-# pm2-runtime ships in the base image.
+# pm2-runtime ships in the house base image; Debian's needs it installed.
+RUN npm install -g pm2@7 # @feature temporal
 CMD [ "pm2-runtime", "start", "ecosystem.config.cjs" ]
 # @feature:else
-CMD [ "node", "dist/src/index.js" ]
+CMD [ "node", "--import", "./dist/src/instrumentation.js", "dist/src/index.js" ]
 # @feature:end