Document and tighten environment defaults

Author: marcusschiesser

docker-compose.yml

@@ -39,7 +39,7 @@ services:
       AWS_SECRET_ACCESS_KEY: minio123
       AWS_REGION: us-east-1
     ports:
-      - "3030:3000"
+      - "4318:3000"
 
 volumes:
   minio-data:

packages/core/src/config.ts

@@ -49,10 +49,8 @@ export function configFromEnv(
 		environment.storeType;
 	const dbPath = overrides.dbPath ?? join(environment.envDir, "cache.duckdb");
 	const projectId = env("AGENTPOND_PROJECT_ID") ?? "default-project";
-	const publicKey =
-		env("LANGFUSE_PUBLIC_KEY") ?? env("AGENTPOND_PUBLIC_KEY") ?? "pk-agentpond";
-	const secretKey =
-		env("LANGFUSE_SECRET_KEY") ?? env("AGENTPOND_SECRET_KEY") ?? "sk-agentpond";
+	const publicKey = env("LANGFUSE_PUBLIC_KEY") ?? "pk-agentpond";
+	const secretKey = env("LANGFUSE_SECRET_KEY") ?? "sk-agentpond";
 
 	return {
 		projectId,
@@ -68,13 +66,15 @@ export function configFromEnv(
 			),
 			endpoint:
 				overrides.s3Endpoint ??
-				env("AGENTPOND_S3_ENDPOINT") ??
-				env("S3_ENDPOINT"),
+				nonEmpty(env("AGENTPOND_S3_ENDPOINT")) ??
+				nonEmpty(env("S3_ENDPOINT")),
 			region: env("AWS_REGION") ?? env("AGENTPOND_S3_REGION") ?? "us-east-1",
 			accessKeyId:
-				env("AWS_ACCESS_KEY_ID") ?? env("AGENTPOND_S3_ACCESS_KEY_ID"),
+				nonEmpty(env("AWS_ACCESS_KEY_ID")) ??
+				nonEmpty(env("AGENTPOND_S3_ACCESS_KEY_ID")),
 			secretAccessKey:
-				env("AWS_SECRET_ACCESS_KEY") ?? env("AGENTPOND_S3_SECRET_ACCESS_KEY"),
+				nonEmpty(env("AWS_SECRET_ACCESS_KEY")) ??
+				nonEmpty(env("AGENTPOND_S3_SECRET_ACCESS_KEY")),
 			forcePathStyle:
 				(env("AGENTPOND_S3_FORCE_PATH_STYLE") ?? "true") !== "false",
 		},
@@ -102,6 +102,10 @@ function envValue(
 	return (name) => process.env[name] ?? fileEnv[name];
 }
 
+function nonEmpty(value: string | undefined): string | undefined {
+	return value === undefined || value === "" ? undefined : value;
+}
+
 function storeTypeFromValue(
 	value: string | undefined,
 ): AgentPondStoreType | undefined {

packages/core/src/environment.ts

@@ -132,12 +132,40 @@ function normalizeEnvironmentName(name: string): string {
 }
 
 function defaultEnvironmentFile(name: string): string {
+	const isDev = name === "dev";
+	if (isDev) return "";
 	const lines = [
+		"# Project id used to share the same object store across different projects.",
 		"AGENTPOND_PROJECT_ID=default-project",
+		"",
+		"# Langfuse-compatible base URL used by SDKs.",
+		"LANGFUSE_BASE_URL=http://localhost:4318",
+		"",
+		"# Langfuse-compatible public key accepted by the ingestion server.",
 		"LANGFUSE_PUBLIC_KEY=pk-agentpond",
+		"# Langfuse-compatible secret key accepted by the ingestion server.",
 		"LANGFUSE_SECRET_KEY=sk-agentpond",
 		"",
 	];
-	if (name !== "dev") lines.unshift("AGENTPOND_STORE=s3");
+	lines.unshift(
+		"# Storage backend for this environment. S3-backed environments sync from object storage.",
+		"AGENTPOND_STORE=s3",
+		"",
+		"# S3 bucket containing AgentPond ingestion objects.",
+		"AGENTPOND_S3_BUCKET=agentpond",
+		"# Optional key prefix inside the S3 bucket.",
+		"AGENTPOND_S3_PREFIX=",
+		"# Local MinIO endpoint from docker-compose.yml. Leave empty for Amazon S3.",
+		"AGENTPOND_S3_ENDPOINT=http://localhost:9000",
+		"# AWS/S3 region used by the object-store client.",
+		"AGENTPOND_S3_REGION=us-east-1",
+		"# Local MinIO access key from docker-compose.yml. Leave empty to use the AWS SDK credential chain.",
+		"AGENTPOND_S3_ACCESS_KEY_ID=minio",
+		"# Local MinIO secret key from docker-compose.yml. Leave empty to use the AWS SDK credential chain.",
+		"AGENTPOND_S3_SECRET_ACCESS_KEY=minio123",
+		"# Use true for MinIO. Use false for Amazon S3 virtual-hosted buckets.",
+		"AGENTPOND_S3_FORCE_PATH_STYLE=true",
+		"",
+	);
 	return lines.join("\n");
 }

tests/cli.test.ts

@@ -630,9 +630,12 @@ test("CLI scores create writes directly to the dev DuckDB", async () => {
 });
 
 test("CLI dev env prints shell exports for SDK configuration", async () => {
+	const cwd = process.cwd();
+	const root = mkdtempSync(join(tmpdir(), "agentpond-cli-dev-env-"));
 	const originalExitCode = process.exitCode;
 	process.exitCode = undefined;
 	try {
+		process.chdir(root);
 		const output = await captureStdout(() =>
 			main(["node", "agentpond", "dev", "env"]),
 		);
@@ -648,14 +651,18 @@ test("CLI dev env prints shell exports for SDK configuration", async () => {
 			].join("\n"),
 		);
 	} finally {
+		process.chdir(cwd);
 		process.exitCode = originalExitCode;
 	}
 });
 
 test("CLI dev env honors custom host and port", async () => {
+	const cwd = process.cwd();
+	const root = mkdtempSync(join(tmpdir(), "agentpond-cli-dev-env-override-"));
 	const originalExitCode = process.exitCode;
 	process.exitCode = undefined;
 	try {
+		process.chdir(root);
 		const output = await captureStdout(() =>
 			main([
 				"node",
@@ -671,7 +678,9 @@ test("CLI dev env honors custom host and port", async () => {
 
 		assert.equal(process.exitCode, undefined);
 		assert.match(output, /export LANGFUSE_BASE_URL=http:\/\/0\.0\.0\.0:9999/);
+		assert.match(output, /export LANGFUSE_PUBLIC_KEY=pk-agentpond-dev/);
 	} finally {
+		process.chdir(cwd);
 		process.exitCode = originalExitCode;
 	}
 });

tests/config.test.ts

@@ -44,21 +44,54 @@ test("config keeps explicit path override precedence", () => {
 	);
 });
 
-test("dev environment file does not include a store override", () => {
+test("generated environment files document defaults and S3 settings", () => {
 	const originalCwd = process.cwd();
 	const cwd = mkdtempSync(join(tmpdir(), "agentpond-config-"));
 	try {
 		process.chdir(cwd);
 		const dev = initAgentPondEnvironment("dev");
 		const production = initAgentPondEnvironment("production");
+		const devFile = readFileSync(dev.envFilePath, "utf8");
+		const productionFile = readFileSync(production.envFilePath, "utf8");
 
-		assert.doesNotMatch(
-			readFileSync(dev.envFilePath, "utf8"),
-			/AGENTPOND_STORE=/,
+		assert.equal(devFile, "");
+		assert.doesNotMatch(devFile, /AGENTPOND_PROJECT_ID=/);
+		assert.doesNotMatch(devFile, /AGENTPOND_STORE=/);
+		assert.doesNotMatch(devFile, /AGENTPOND_S3_BUCKET=/);
+		assert.doesNotMatch(devFile, /LANGFUSE_BASE_URL=/);
+		assert.doesNotMatch(devFile, /LANGFUSE_PUBLIC_KEY=/);
+		assert.doesNotMatch(devFile, /LANGFUSE_SECRET_KEY=/);
+
+		assert.match(productionFile, /# Storage backend/);
+		assert.match(productionFile, /LANGFUSE_BASE_URL=http:\/\/localhost:4318/);
+		assert.match(productionFile, /AGENTPOND_STORE=s3/);
+		assert.match(productionFile, /# S3 bucket/);
+		assert.match(productionFile, /AGENTPOND_S3_BUCKET=agentpond/);
+		assert.match(productionFile, /AGENTPOND_S3_PREFIX=/);
+		assert.match(
+			productionFile,
+			/Local MinIO endpoint from docker-compose\.yml/,
 		);
 		assert.match(
-			readFileSync(production.envFilePath, "utf8"),
-			/AGENTPOND_STORE=s3/,
+			productionFile,
+			/AGENTPOND_S3_ENDPOINT=http:\/\/localhost:9000/,
+		);
+		assert.match(productionFile, /AGENTPOND_S3_REGION=us-east-1/);
+		assert.match(productionFile, /AGENTPOND_S3_ACCESS_KEY_ID=minio/);
+		assert.match(productionFile, /AGENTPOND_S3_SECRET_ACCESS_KEY=minio123/);
+		assert.match(productionFile, /Use true for MinIO/);
+		assert.match(productionFile, /AGENTPOND_S3_FORCE_PATH_STYLE=true/);
+		assert.equal(
+			configFromEnv({ envName: "production" }).s3.endpoint,
+			"http://localhost:9000",
+		);
+		assert.equal(
+			configFromEnv({ envName: "production" }).s3.accessKeyId,
+			"minio",
+		);
+		assert.equal(
+			configFromEnv({ envName: "production" }).s3.secretAccessKey,
+			"minio123",
 		);
 	} finally {
 		process.chdir(originalCwd);