fix: resolve storage healthcheck path via LOCAL_STORAGE_PATH env var (#3004)

* fix: resolve local data directory to /app/data in production Docker

In the official Docker image, cwd is /app/apps/web (set via WORKDIR), but
the data volume is mounted at /app/data. Without pnpm-workspace.yaml present
in the runtime image, findWorkspaceRoot() returns null, so getLocalDataDirectory()
fell back to <cwd>/data = /app/apps/web/data, which the node user has no
permission to create. This caused the storage healthcheck to fail with
EACCES.

Add a production fallback: when cwd ends in apps/web, resolve the data
directory to two levels up (matching /app/data in the official image).

Re-resolves #2990.

https://claude.ai/code/session_015pSTtukxf7mFTty2Y6PHZf

* fix: replace apps/web heuristic with LOCAL_STORAGE_PATH env var

The previous fix special-cased a cwd ending in apps/web to land on /app/data,
but the heuristic could false-positive on any path with that suffix and was
fragile to Dockerfile changes. pnpm-workspace.yaml is never copied into the
runtime image, so the workspace-root walk was also dead code in production.

Replace the heuristic with an explicit LOCAL_STORAGE_PATH env var:
- Set LOCAL_STORAGE_PATH=/app/data in the Dockerfile (single source of truth).
- Add LOCAL_STORAGE_PATH to the env schema; storage and statistics services
  pass it through to getLocalDataDirectory.
- getLocalDataDirectory now uses the override when set, else workspace root
  (dev), else cwd/data.
- New Nitro plugin validates the resolved local data directory at startup
  and refuses to boot with a clear error if it isn't writable, surfacing
  permission issues immediately instead of at first upload/healthcheck.
- Document the new variable in .env.example and the Docker self-hosting docs.

https://claude.ai/code/session_015pSTtukxf7mFTty2Y6PHZf

* fix: address review feedback on storage path handling

- apps/web/plugins/2.storage.ts: use the default-import style for
  node:fs/promises (matches the rest of the repo, sidesteps any
  named-export concerns for fs.constants).
- packages/env/src/server.ts: reject relative LOCAL_STORAGE_PATH values
  via a zod refinement. Relative paths would be resolved against cwd,
  which differs between dev and Docker — exactly the same surprise the
  original bug had. Failing fast at config validation time gives a
  clear error before the server boots.

https://claude.ai/code/session_015pSTtukxf7mFTty2Y6PHZf

* fix: update data volume configuration in Docker Compose and enhance Nitro plugin

* fix: remove "Can I customize the templates?" FAQ entry from multiple language files

---------

Co-authored-by: Claude <noreply@anthropic.com>

packages/api/src/services/statistics.ts

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { count } from "drizzle-orm";
 import { db } from "@reactive-resume/db/client";
 import * as schema from "@reactive-resume/db/schema";
+import { env } from "@reactive-resume/env/server";
 import { getLocalDataDirectory } from "@reactive-resume/utils/monorepo.node";
 
 const CACHE_DURATION_MS = 6 * 60 * 60 * 1000; // 6 hours
@@ -16,7 +17,7 @@ const LAST_KNOWN = {
 	stars: 34_073,
 } as const;
 
-const getCachePath = (key: string) => join(getLocalDataDirectory(), "statistics", `${key}.txt`);
+const getCachePath = (key: string) => join(getLocalDataDirectory(env.LOCAL_STORAGE_PATH), "statistics", `${key}.txt`);
 
 const readCache = async (key: string): Promise<number | null> => {
 	try {

packages/api/src/services/storage.ts

@@ -115,7 +115,7 @@ class LocalStorageService implements StorageService {
 	private rootDirectory: string;
 
 	constructor() {
-		this.rootDirectory = getLocalDataDirectory();
+		this.rootDirectory = getLocalDataDirectory(env.LOCAL_STORAGE_PATH);
 	}
 
 	async list(prefix: string): Promise<string[]> {

packages/env/src/server.ts

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 import { createEnv } from "@t3-oss/env-core";
 import { config } from "dotenv";
 import { z } from "zod";
@@ -58,6 +58,7 @@ export const env = createEnv({
 		SMTP_SECURE: z.stringbool().default(false),
 
 		// Storage (Optional)
+		LOCAL_STORAGE_PATH: z.string().min(1).refine(isAbsolute, "LOCAL_STORAGE_PATH must be an absolute path").optional(),
 		S3_ACCESS_KEY_ID: z.string().min(1).optional(),
 		S3_SECRET_ACCESS_KEY: z.string().min(1).optional(),
 		S3_REGION: z.string().default("us-east-1"),

packages/utils/src/monorepo.node.ts

@@ -15,8 +15,9 @@ export const findWorkspaceRoot = (cwd = process.cwd()) => {
 	}
 };
 
-export const getLocalDataDirectory = (cwd = process.cwd()) => {
-	const workspaceRoot = findWorkspaceRoot(cwd);
+export const getLocalDataDirectory = (overridePath?: string, cwd = process.cwd()) => {
+	if (overridePath) return overridePath;
 
+	const workspaceRoot = findWorkspaceRoot(cwd);
 	return join(workspaceRoot ?? realpathSync(cwd), "data");
 };