Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
fix(server): give each data directory error one cause and one fix
Elian Dorana153589e12d4
diff --git a/apps/server/src/services/data_dir.spec.ts b/apps/server/src/services/data_dir.spec.tsindex 3346e9ce9c..2fdf7ae91b 100644--- a/apps/server/src/services/data_dir.spec.ts+++ b/apps/server/src/services/data_dir.spec.ts@@ -68,6 +68,41 @@ describe("data_dir.ts unit tests", () => {});};+ type ProcessWithIds = NodeJS.Process & { getuid?: () => number; getgid?: () => number };+ const proc = process as ProcessWithIds;+ const originalIds = { getuid: proc.getuid, getgid: proc.getgid };++ // Sets the UID and GID process.getuid()/getgid() report, or removes both as on Windows (null).+ const stubUser = (id: number | null) => {+ if (id === null) {+ delete proc.getuid;+ delete proc.getgid;+ } else {+ proc.getuid = () => id;+ proc.getgid = () => id;+ }+ };++ const restoreUser = () => {+ if (originalIds.getuid && originalIds.getgid) {+ proc.getuid = originalIds.getuid;+ proc.getgid = originalIds.getgid;+ } else {+ stubUser(null);+ }+ };++ // Runs `run` with process.exit stubbed and returns what was printed before exiting.+ const runUntilExit = (run: () => unknown) => {+ const exit = vi.spyOn(process, "exit").mockImplementation(() => {+ throw new Error("process.exit");+ });+ expect(run).toThrow("process.exit");+ expect(exit).toHaveBeenCalledWith(1);+ expect(console.error).toHaveBeenCalledTimes(1);+ return String(vi.mocked(console.error).mock.calls[0][0]);+ };+// helper to set mocked Platformconst setMockPlatform = (osPlatform: string, homedir: string, pathJoin: string) => {mockFn.osPlatformMock.mockImplementation(() => osPlatform);@@ -368,8 +403,13 @@ describe("data_dir.ts unit tests", () => {describe("w/ existing entries", () => {const W_OK = 2;- const proc = process as NodeJS.Process & { getuid?: () => number; getgid?: () => number };- let hadGetuid = false;+ const blockWrites = (...paths: string[]) => {+ mockFn.accessSyncMock.mockImplementation((path: string, mode: number) => {+ if (paths.includes(path) && (mode & W_OK)) {+ throw new Error("EACCES");+ }+ });+ };beforeEach(() => {resetAllMocks();@@ -377,19 +417,17 @@ describe("data_dir.ts unit tests", () => {mockFn.pathJoinMock.mockImplementation((...parts: string[]) => parts.join("/"));mockFn.existsSyncMock.mockReturnValue(true);mockFn.statSyncMock.mockImplementation((path: string) => ({- uid: 1000, gid: 1000, mode: path === "/data/log" ? 0o40700 : 0o100644+ uid: 1000,+ gid: 1000,+ mode: path === "/data/log" ? 0o40700 : 0o100644,+ isFile: () => path !== "/data/log"}));vi.spyOn(console, "error").mockImplementation(() => {});- hadGetuid = "getuid" in proc;- proc.getuid = () => 1234;- proc.getgid = () => 1234;+ stubUser(1234);});afterEach(() => {- if (!hadGetuid) {- delete proc.getuid;- delete proc.getgid;- }+ restoreUser();vi.restoreAllMocks();resetAllMocks();});@@ -400,28 +438,34 @@ describe("data_dir.ts unit tests", () => {expect(console.error).not.toHaveBeenCalled();});- it("that the user cannot write – lists them and exits", () => {- const blocked = new Set([ "/data/document.db", "/data/log", "/data/config.ini" ]);- mockFn.accessSyncMock.mockImplementation((path: string, mode: number) => {- if (blocked.has(path) && (mode & W_OK)) {- throw new Error("EACCES");- }- });- const exit = vi.spyOn(process, "exit").mockImplementation(() => {- throw new Error("process.exit");- });-- expect(() => getDataDirs("/data")).toThrow("process.exit");- expect(exit).toHaveBeenCalledWith(1);- const message = String(vi.mocked(console.error).mock.calls[0][0]);- expect(message).toContain("Trilium cannot start: the user running it cannot use these files in its data directory.");- expect(message).toContain("Running as UID:GID 1234:1234.");- expect(message).toContain("/data/document.db is owned by UID:GID 1000:1000 with permissions 644.");- expect(message).toContain("/data/log is owned by UID:GID 1000:1000 with permissions 700.");- expect(message).toContain("for example: sudo chown -R 1234:1234 /data");+ it("that the user cannot write – lists them with the chown that fixes them and exits", () => {+ blockWrites("/data/document.db", "/data/log", "/data/config.ini");++ const message = runUntilExit(() => getDataDirs("/data"));+ expect(message).toContain("Trilium cannot start because it cannot use some of the files in its data directory, /data.");+ expect(message).toContain([+ "Trilium runs as UID:GID 1234:1234, but:",+ " - document.db is owned by UID:GID 1000:1000 with permissions 644",+ " - log is owned by UID:GID 1000:1000 with permissions 700",+ ""+ ].join("\n"));+ expect(message).toContain(" sudo chown -R 1234:1234 /data");+ expect(message).toContain("In Docker, the paths above are inside the container.");// config.ini is only read, so a denied write must not flag it.expect(message).not.toContain("config.ini");});++ it("on Windows – says which files are read-only, without UIDs or a chown", () => {+ stubUser(null);+ blockWrites("/data/document.db");+ mockFn.statSyncMock.mockImplementation(() => ({ uid: 0, gid: 0, mode: 0o100444, isFile: () => true }));++ const message = runUntilExit(() => getDataDirs("/data"));+ expect(message).toContain("The user running Trilium cannot use them:\n - document.db is read-only\n");+ expect(message).toContain("give the user running Trilium full control of the data directory");+ expect(message).not.toContain("UID:GID");+ expect(message).not.toContain("sudo");+ });});});@@ -430,10 +474,12 @@ describe("data_dir.ts unit tests", () => {resetAllMocks();process.env.TRILIUM_DATA_DIR = "/home/mock/trilium-data-ERR";vi.spyOn(console, "error").mockImplementation(() => {});+ stubUser(1000);});afterEach(() => {delete process.env.TRILIUM_DATA_DIR;+ restoreUser();vi.restoreAllMocks();});@@ -444,65 +490,62 @@ describe("data_dir.ts unit tests", () => {return err;};- // Runs getTriliumDataDir with process.exit stubbed and returns what was printed.- const runUntilExit = () => {- const exit = vi.spyOn(process, "exit").mockImplementation(() => {- throw new Error("process.exit");- });- expect(() => getTriliumDataDir("trilium-data")).toThrow("process.exit");- expect(exit).toHaveBeenCalledWith(1);- expect(console.error).toHaveBeenCalledTimes(1);- return String(vi.mocked(console.error).mock.calls[0][0]);- };+ const ownedByRoot = () => ({ uid: 0, gid: 0, mode: 0o40755, isFile: () => false });- it("EACCES – prints why the directory cannot be created and exits", () => {+ it("EACCES creating the data directory – suggests creating it for the user and exits", () => {mkdirThrows("EACCES");- mockFn.statSyncMock.mockImplementation(() => ({ uid: 1000, gid: 1000, mode: 0o755 }));- // Provide getuid/getgid (absent on Windows) so the UID:GID line is printed.- const proc = process as NodeJS.Process & { getuid?: () => number; getgid?: () => number };- const hadGetuid = "getuid" in proc;- proc.getuid = () => 1000;- proc.getgid = () => 1000;+ mockFn.statSyncMock.mockImplementation(ownedByRoot);++ const message = runUntilExit(() => getTriliumDataDir("trilium-data"));+ expect(message).toContain("Trilium cannot start because it cannot create /home/mock/trilium-data-ERR.");+ expect(message).toContain("Trilium runs as UID:GID 1000:1000, which cannot write to /home/mock: it is owned by UID:GID 0:0 with permissions 755.");+ expect(message).toContain(" sudo mkdir -p /home/mock/trilium-data-ERR && sudo chown 1000:1000 /home/mock/trilium-data-ERR");+ expect(message).toContain("Or set TRILIUM_DATA_DIR to a directory that user owns.");+ expect(message).toContain("In Docker, the paths above are inside the container.");+ expect(message).not.toContain("chown -R");+ });- try {- const message = runUntilExit();- expect(message).toContain("Trilium cannot start: permission denied while creating /home/mock/trilium-data-ERR.");- expect(message).toContain("Running as UID:GID 1000:1000.");- expect(message).toContain("/home/mock is owned by UID:GID 1000:1000 with permissions 755.");- expect(message).toContain("in Docker, set USER_UID and USER_GID to the owner of the mounted directory");- expect(mockFn.statSyncMock).toHaveBeenCalledWith("/home/mock");- } finally {- if (!hadGetuid) {- delete proc.getuid;- delete proc.getgid;- }- }+ it("EACCES creating a directory inside the data directory – suggests a chown of the data directory and exits", () => {+ delete process.env.TRILIUM_TMP_DIR;+ mockFn.pathJoinMock.mockImplementation((...parts: string[]) => parts.join("/"));+ mkdirThrows("EACCES");+ mockFn.statSyncMock.mockImplementation(ownedByRoot);++ const message = runUntilExit(() => getDataDirs("/data"));+ expect(message).toContain("Trilium cannot start because it cannot create /data/tmp.");+ expect(message).toContain("Trilium runs as UID:GID 1000:1000, which cannot write to its data directory, /data: it is owned by UID:GID 0:0 with permissions 755.");+ expect(message).toContain(" sudo chown -R 1000:1000 /data");+ expect(message).not.toContain("mkdir");});it("EACCES – names the ancestor that cannot be entered and exits", () => {+ stubUser(1234);mkdirThrows("EACCES");mockFn.accessSyncMock.mockImplementation((path: string) => {if (path === "/home/mock") {throw new Error("EACCES");}});- mockFn.statSyncMock.mockImplementation(() => ({ uid: 1000, gid: 1000, mode: 0o700 }));+ mockFn.statSyncMock.mockImplementation(() => ({ uid: 1000, gid: 1000, mode: 0o40700, isFile: () => false }));- const message = runUntilExit();- expect(message).toContain("Trilium cannot start: /home/mock/trilium-data-ERR cannot be reached.");- expect(message).toContain("/home/mock cannot be entered; it is owned by UID:GID 1000:1000 with permissions 700.");+ const message = runUntilExit(() => getTriliumDataDir("trilium-data"));+ expect(message).toContain("Trilium cannot start because it cannot reach /home/mock/trilium-data-ERR.");+ expect(message).toContain("Trilium runs as UID:GID 1234:1234, which cannot enter /home/mock: it is owned by UID:GID 1000:1000 with permissions 700.");+ expect(message).toContain(" sudo chmod o+x /home/mock");+ expect(mockFn.statSyncMock).toHaveBeenCalledWith("/home/mock");});it("EACCES – reports a parent that cannot be inspected and exits", () => {mkdirThrows("EACCES");mockFn.statSyncMock.mockImplementation(() => { throw new Error("no access"); });- expect(runUntilExit()).toContain("/home/mock cannot be inspected.");+ expect(runUntilExit(() => getTriliumDataDir("trilium-data")))+ .toContain("which cannot write to /home/mock: it cannot be inspected.");});it("EACCES under Electron – throws the explanation for the main-process error dialog", () => {const err = mkdirThrows("EACCES");- mockFn.statSyncMock.mockImplementation(() => ({ uid: 1000, gid: 1000, mode: 0o755 }));+ mockFn.statSyncMock.mockImplementation(ownedByRoot);const exit = vi.spyOn(process, "exit");Object.defineProperty(process.versions, "electron", { value: "1.0.0", configurable: true });@@ -514,7 +557,9 @@ describe("data_dir.ts unit tests", () => {thrown = e;}expect(thrown).toBeInstanceOf(Error);- expect((thrown as Error).message).toContain("Trilium cannot start: permission denied while creating /home/mock/trilium-data-ERR.");+ const message = (thrown as Error).message;+ expect(message).toContain("Trilium cannot start because it cannot create /home/mock/trilium-data-ERR.");+ expect(message).not.toContain("In Docker");expect((thrown as Error).cause).toBe(err);expect(exit).not.toHaveBeenCalled();} finally {diff --git a/apps/server/src/services/data_dir.ts b/apps/server/src/services/data_dir.tsindex b49555a0fa..b2051f525e 100644--- a/apps/server/src/services/data_dir.ts+++ b/apps/server/src/services/data_dir.ts@@ -53,7 +53,7 @@ export function getDataDirs(TRILIUM_DATA_DIR: string) {OCR_CACHE_DIR: process.env.TRILIUM_OCR_CACHE_DIR || pathJoin(TRILIUM_DATA_DIR, "ocr-cache")} as const;- createDirIfNotExisting(dataDirs.TMP_DIR);+ createDirIfNotExisting(dataDirs.TMP_DIR, TRILIUM_DATA_DIR);checkExistingEntries(dataDirs);Object.freeze(dataDirs);@@ -98,26 +98,19 @@ function checkExistingEntries(dataDirs: ReturnType<typeof getDataDirs>) {return;}+ const dataDir = dataDirs.TRILIUM_DATA_DIR;const user = getProcessUser();- const lines = [- "Trilium cannot start: the user running it cannot use these files in its data directory.",- ""- ];- if (user) {- lines.push(`Running as UID:GID ${user}.`);- }- for (const [ path ] of unusable) {- lines.push(`${path} ${describeOwnership(path)}.`);- }- lines.push("", "To fix this, give the data directory and everything in it to the user running Trilium,");- if (user) {- lines.push(`for example: sudo chown -R ${user} ${dataDirs.TRILIUM_DATA_DIR}`);- }- lines.push(- "In Docker, run that on the host directory mounted as the data directory, or start the",- "container without --user."- );- stopStartup(lines.join("\n"));+ stopStartup([+ `Trilium cannot start because it cannot use some of the files in its data directory, ${dataDir}.`,+ "",+ user ? `Trilium runs as UID:GID ${user}, but:` : "The user running Trilium cannot use them:",+ ...unusable.map(([ path ]) => ` - ${relativeToDir(path, dataDir)} ${describeOwnership(path)}`),+ "",+ ...(user+ ? [ "To fix this, give the data directory and everything in it to that user:", ` sudo chown -R ${user} ${dataDir}` ]+ : [ "To fix this, give the user running Trilium full control of the data directory and everything in it." ]),+ ...containerHint()+ ].join("\n"));}export function getPlatformAppDataDir(platform: ReturnType<typeof os.platform>, ENV_APPDATA_DIR: string | undefined = process.env.APPDATA) {@@ -157,47 +150,94 @@ function getProcessUser() {}}-/** Completes a sentence about `path`: "is owned by UID:GID 1000:1000 with permissions 700". */+/**+ * Completes a sentence about `path`: "is owned by UID:GID 1000:1000 with permissions 700". Windows+ * has no UIDs, and `fs.statSync()` reports 0 there, so it only says whether a file is read-only.+ */function describeOwnership(path: string) {try {const stats = fs.statSync(path);+ if (!getProcessUser()) {+ return stats.isFile() && !(stats.mode & 0o200) ? "is read-only" : "cannot be accessed";+ }return `is owned by UID:GID ${stats.uid}:${stats.gid} with permissions ${(stats.mode & 0o777).toString(8)}`;} catch {return "cannot be inspected";}}-function failWithPermissionError(targetPath: fs.PathLike, cause: unknown): never {- stopStartup(describePermissionError(targetPath.toString()), cause);+/**+ * The paths in a message are the ones Trilium sees, which in a container are not the host paths a+ * fix has to be applied to. Desktop never runs in a container, so its dialog leaves this out.+ */+function containerHint() {+ if (process.versions.electron) {+ return [];+ }+ return [+ "",+ "In Docker, the paths above are inside the container. Apply the fix to the directory mounted",+ "there from the host, or start the container without --user."+ ];+}++function relativeToDir(path: string, dir: string) {+ const separator = path.charAt(dir.length);+ return path.startsWith(dir) && (separator === "/" || separator === "\\") ? path.slice(dir.length + 1) : path;}-function describePermissionError(path: string) {- const blockedDir = findUnreachableAncestor(dirname(path));- const shownDir = blockedDir ?? dirname(path);+function failWithPermissionError(targetPath: fs.PathLike, dataDir: string | undefined, cause: unknown): never {+ stopStartup(describePermissionError(targetPath.toString(), dataDir), cause);+}++/**+ * Explains why `path` cannot be created. `dataDir` is the data directory `path` belongs in, or+ * `undefined` when `path` is the data directory itself.+ */+function describePermissionError(path: string, dataDir: string | undefined) {+ const parent = dirname(path);+ const blockedDir = findUnreachableAncestor(parent);const user = getProcessUser();- const lines = [- blockedDir- ? `Trilium cannot start: ${path} cannot be reached.`- : `Trilium cannot start: permission denied while creating ${path}.`,- ""- ];- if (user) {- lines.push(`Running as UID:GID ${user}.`);- }- lines.push(blockedDir- ? `${shownDir} cannot be entered; it ${describeOwnership(shownDir)}.`- : `${shownDir} ${describeOwnership(shownDir)}.`);+ const subject = user ? `Trilium runs as UID:GID ${user}, which` : "The user running Trilium";- lines.push(- "",- "To fix this, either:",- " - make sure the user running Trilium can enter every directory above the data directory",- " and write to the data directory itself",- " - set TRILIUM_DATA_DIR to a directory owned by that user",- " - in Docker, set USER_UID and USER_GID to the owner of the mounted directory, or, if the",- " container runs with --user, give the mounted directory to that user"- );- return lines.join("\n");+ let lines: string[];+ if (blockedDir) {+ lines = [+ `Trilium cannot start because it cannot reach ${path}.`,+ "",+ `${subject} cannot enter ${blockedDir}: it ${describeOwnership(blockedDir)}.`,+ "",+ ...(user+ ? [ "To fix this, let that user enter it:", ` sudo chmod o+x ${blockedDir}` ]+ : [ `To fix this, let the user running Trilium enter ${blockedDir}.` ]),+ "Or set TRILIUM_DATA_DIR to a directory that user can reach."+ ];+ } else if (parent === dataDir) {+ lines = [+ `Trilium cannot start because it cannot create ${path}.`,+ "",+ `${subject} cannot write to its data directory, ${parent}: it ${describeOwnership(parent)}.`,+ "",+ ...(user+ ? [ "To fix this, give the data directory and everything in it to that user:", ` sudo chown -R ${user} ${parent}` ]+ : [ "To fix this, give the user running Trilium full control of the data directory." ]),+ "Or set TRILIUM_DATA_DIR to a directory that user owns."+ ];+ } else {+ lines = [+ `Trilium cannot start because it cannot create ${path}.`,+ "",+ `${subject} cannot write to ${parent}: it ${describeOwnership(parent)}.`,+ "",+ ...(user+ ? [ "To fix this, create the directory for that user:", ` sudo mkdir -p ${path} && sudo chown ${user} ${path}` ]+ : [ "To fix this, create the directory and give the user running Trilium full control of it." ])+ ];+ if (!dataDir) {+ lines.push("Or set TRILIUM_DATA_DIR to a directory that user owns.");+ }+ }+ return [ ...lines, ...containerHint() ].join("\n");}/**@@ -218,15 +258,16 @@ function findUnreachableAncestor(dir: string) {}}-function createDirIfNotExisting(path: fs.PathLike, permissionMode: fs.Mode = FOLDER_PERMISSIONS) {+/** `dataDir` is the data directory `path` belongs in, or `undefined` when `path` is the data directory. */+function createDirIfNotExisting(path: fs.PathLike, dataDir?: string) {try {- fs.mkdirSync(path, permissionMode);+ fs.mkdirSync(path, FOLDER_PERMISSIONS);} catch (err: unknown) {if (err && typeof err === "object" && "code" in err) {const code = (err as { code: string }).code;if (code === "EACCES") {- failWithPermissionError(path, err);+ failWithPermissionError(path, dataDir, err);} else if (code === "EEXIST") {// Directory already exists - verify it's actually a directorytry {