From eb27ec2234a944cc9e1254315495c2ea7ada5a9b Mon Sep 17 00:00:00 2001 From: perf3ct Date: Thu, 21 Aug 2025 02:15:02 +0000 Subject: [PATCH 01/27] feat(config): fix previously documented env var formula not working asdf --- apps/server/src/services/config.spec.ts | 348 +++++++++++++ apps/server/src/services/config.ts | 628 ++++++++++++++++++++---- 2 files changed, 893 insertions(+), 83 deletions(-) create mode 100644 apps/server/src/services/config.spec.ts diff --git a/apps/server/src/services/config.spec.ts b/apps/server/src/services/config.spec.ts new file mode 100644 index 000000000..ec067fc4c --- /dev/null +++ b/apps/server/src/services/config.spec.ts @@ -0,0 +1,348 @@ +import { vi, describe, it, expect, beforeEach, afterEach } from "vitest"; +import fs from "fs"; +import ini from "ini"; + +// Mock dependencies +vi.mock("fs"); +vi.mock("./data_dir.js", () => ({ + default: { + CONFIG_INI_PATH: "/test/config.ini" + } +})); +vi.mock("./resource_dir.js", () => ({ + default: { + RESOURCE_DIR: "/test/resources" + } +})); + +describe("Config Service", () => { + let originalEnv: NodeJS.ProcessEnv; + + beforeEach(() => { + // Save original environment + originalEnv = { ...process.env }; + + // Clear all TRILIUM env vars + Object.keys(process.env).forEach(key => { + if (key.startsWith("TRILIUM_")) { + delete process.env[key]; + } + }); + + // Mock fs to return empty config + vi.mocked(fs.existsSync).mockReturnValue(true); + vi.mocked(fs.readFileSync).mockImplementation((path) => { + if (String(path).includes("config-sample.ini")) { + return "" as any; // Return string for INI parsing + } + // Return empty INI config as string + return ` +[General] +[Network] +[Session] +[Sync] +[MultiFactorAuthentication] +[Logging] + ` as any; + }); + + // Clear module cache to reload config with new env vars + vi.resetModules(); + }); + + afterEach(() => { + // Restore original environment + process.env = originalEnv; + vi.clearAllMocks(); + }); + + describe("Environment Variable Naming", () => { + it("should use standard environment variables following TRILIUM_[SECTION]_[KEY] pattern", async () => { + // Set standard env vars + process.env.TRILIUM_GENERAL_INSTANCENAME = "test-instance"; + process.env.TRILIUM_NETWORK_CORSALLOWORIGIN = "https://example.com"; + process.env.TRILIUM_SYNC_SYNCSERVERHOST = "sync.example.com"; + process.env.TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL = "https://auth.example.com"; + process.env.TRILIUM_LOGGING_RETENTIONDAYS = "30"; + + const { default: config } = await import("./config.js"); + + expect(config.General.instanceName).toBe("test-instance"); + expect(config.Network.corsAllowOrigin).toBe("https://example.com"); + expect(config.Sync.syncServerHost).toBe("sync.example.com"); + expect(config.MultiFactorAuthentication.oauthBaseUrl).toBe("https://auth.example.com"); + expect(config.Logging.retentionDays).toBe(30); + }); + + it("should maintain backward compatibility with alias environment variables", async () => { + // Set alias/legacy env vars + process.env.TRILIUM_NETWORK_CORS_ALLOW_ORIGIN = "https://legacy.com"; + process.env.TRILIUM_SYNC_SERVER_HOST = "legacy-sync.com"; + process.env.TRILIUM_OAUTH_BASE_URL = "https://legacy-auth.com"; + process.env.TRILIUM_LOGGING_RETENTION_DAYS = "60"; + + const { default: config } = await import("./config.js"); + + expect(config.Network.corsAllowOrigin).toBe("https://legacy.com"); + expect(config.Sync.syncServerHost).toBe("legacy-sync.com"); + expect(config.MultiFactorAuthentication.oauthBaseUrl).toBe("https://legacy-auth.com"); + expect(config.Logging.retentionDays).toBe(60); + }); + + it("should prioritize standard env vars over aliases when both are set", async () => { + // Set both standard and alias env vars - standard should win + process.env.TRILIUM_NETWORK_CORSALLOWORIGIN = "standard-cors.com"; + process.env.TRILIUM_NETWORK_CORS_ALLOW_ORIGIN = "alias-cors.com"; + + process.env.TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL = "standard-auth.com"; + process.env.TRILIUM_OAUTH_BASE_URL = "alias-auth.com"; + + const { default: config } = await import("./config.js"); + + expect(config.Network.corsAllowOrigin).toBe("standard-cors.com"); + expect(config.MultiFactorAuthentication.oauthBaseUrl).toBe("standard-auth.com"); + }); + + it("should handle all CORS environment variables correctly", async () => { + // Test with standard naming + process.env.TRILIUM_NETWORK_CORSALLOWORIGIN = "*"; + process.env.TRILIUM_NETWORK_CORSALLOWMETHODS = "GET,POST,PUT"; + process.env.TRILIUM_NETWORK_CORSALLOWHEADERS = "Content-Type,Authorization"; + + let { default: config } = await import("./config.js"); + + expect(config.Network.corsAllowOrigin).toBe("*"); + expect(config.Network.corsAllowMethods).toBe("GET,POST,PUT"); + expect(config.Network.corsAllowHeaders).toBe("Content-Type,Authorization"); + + // Clear and test with alias naming + delete process.env.TRILIUM_NETWORK_CORSALLOWORIGIN; + delete process.env.TRILIUM_NETWORK_CORSALLOWMETHODS; + delete process.env.TRILIUM_NETWORK_CORSALLOWHEADERS; + + process.env.TRILIUM_NETWORK_CORS_ALLOW_ORIGIN = "https://app.com"; + process.env.TRILIUM_NETWORK_CORS_ALLOW_METHODS = "GET,POST"; + process.env.TRILIUM_NETWORK_CORS_ALLOW_HEADERS = "X-Custom-Header"; + + vi.resetModules(); + config = (await import("./config.js")).default; + + expect(config.Network.corsAllowOrigin).toBe("https://app.com"); + expect(config.Network.corsAllowMethods).toBe("GET,POST"); + expect(config.Network.corsAllowHeaders).toBe("X-Custom-Header"); + }); + + it("should handle all OAuth/MFA environment variables correctly", async () => { + // Test with standard naming + process.env.TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL = "https://oauth.standard.com"; + process.env.TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTID = "standard-client-id"; + process.env.TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRET = "standard-secret"; + process.env.TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERBASEURL = "https://issuer.standard.com"; + process.env.TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERNAME = "Standard Auth"; + process.env.TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERICON = "standard-icon.png"; + + let { default: config } = await import("./config.js"); + + expect(config.MultiFactorAuthentication.oauthBaseUrl).toBe("https://oauth.standard.com"); + expect(config.MultiFactorAuthentication.oauthClientId).toBe("standard-client-id"); + expect(config.MultiFactorAuthentication.oauthClientSecret).toBe("standard-secret"); + expect(config.MultiFactorAuthentication.oauthIssuerBaseUrl).toBe("https://issuer.standard.com"); + expect(config.MultiFactorAuthentication.oauthIssuerName).toBe("Standard Auth"); + expect(config.MultiFactorAuthentication.oauthIssuerIcon).toBe("standard-icon.png"); + + // Clear and test with alias naming + Object.keys(process.env).forEach(key => { + if (key.startsWith("TRILIUM_MULTIFACTORAUTHENTICATION_")) { + delete process.env[key]; + } + }); + + process.env.TRILIUM_OAUTH_BASE_URL = "https://oauth.alias.com"; + process.env.TRILIUM_OAUTH_CLIENT_ID = "alias-client-id"; + process.env.TRILIUM_OAUTH_CLIENT_SECRET = "alias-secret"; + process.env.TRILIUM_OAUTH_ISSUER_BASE_URL = "https://issuer.alias.com"; + process.env.TRILIUM_OAUTH_ISSUER_NAME = "Alias Auth"; + process.env.TRILIUM_OAUTH_ISSUER_ICON = "alias-icon.png"; + + vi.resetModules(); + config = (await import("./config.js")).default; + + expect(config.MultiFactorAuthentication.oauthBaseUrl).toBe("https://oauth.alias.com"); + expect(config.MultiFactorAuthentication.oauthClientId).toBe("alias-client-id"); + expect(config.MultiFactorAuthentication.oauthClientSecret).toBe("alias-secret"); + expect(config.MultiFactorAuthentication.oauthIssuerBaseUrl).toBe("https://issuer.alias.com"); + expect(config.MultiFactorAuthentication.oauthIssuerName).toBe("Alias Auth"); + expect(config.MultiFactorAuthentication.oauthIssuerIcon).toBe("alias-icon.png"); + }); + + it("should handle all Sync environment variables correctly", async () => { + // Test with standard naming + process.env.TRILIUM_SYNC_SYNCSERVERHOST = "sync-standard.com"; + process.env.TRILIUM_SYNC_SYNCSERVERTIMEOUT = "60000"; + process.env.TRILIUM_SYNC_SYNCPROXY = "proxy-standard.com"; + + let { default: config } = await import("./config.js"); + + expect(config.Sync.syncServerHost).toBe("sync-standard.com"); + expect(config.Sync.syncServerTimeout).toBe("60000"); + expect(config.Sync.syncProxy).toBe("proxy-standard.com"); + + // Clear and test with alias naming + delete process.env.TRILIUM_SYNC_SYNCSERVERHOST; + delete process.env.TRILIUM_SYNC_SYNCSERVERTIMEOUT; + delete process.env.TRILIUM_SYNC_SYNCPROXY; + + process.env.TRILIUM_SYNC_SERVER_HOST = "sync-alias.com"; + process.env.TRILIUM_SYNC_SERVER_TIMEOUT = "30000"; + process.env.TRILIUM_SYNC_SERVER_PROXY = "proxy-alias.com"; + + vi.resetModules(); + config = (await import("./config.js")).default; + + expect(config.Sync.syncServerHost).toBe("sync-alias.com"); + expect(config.Sync.syncServerTimeout).toBe("30000"); + expect(config.Sync.syncProxy).toBe("proxy-alias.com"); + }); + }); + + describe("INI Config Integration", () => { + it("should fall back to INI config when no env vars are set", async () => { + // Mock INI config with values + vi.mocked(fs.readFileSync).mockImplementation((path) => { + if (String(path).includes("config-sample.ini")) { + return "" as any; + } + return ` +[General] +instanceName=ini-instance + +[Network] +corsAllowOrigin=https://ini-cors.com +port=9000 + +[Sync] +syncServerHost=ini-sync.com + +[MultiFactorAuthentication] +oauthBaseUrl=https://ini-oauth.com + +[Logging] +retentionDays=45 + ` as any; + }); + + const { default: config } = await import("./config.js"); + + expect(config.General.instanceName).toBe("ini-instance"); + expect(config.Network.corsAllowOrigin).toBe("https://ini-cors.com"); + expect(config.Network.port).toBe("9000"); + expect(config.Sync.syncServerHost).toBe("ini-sync.com"); + expect(config.MultiFactorAuthentication.oauthBaseUrl).toBe("https://ini-oauth.com"); + expect(config.Logging.retentionDays).toBe(45); + }); + + it("should prioritize env vars over INI config", async () => { + // Mock INI config with values + vi.mocked(fs.readFileSync).mockImplementation((path) => { + if (String(path).includes("config-sample.ini")) { + return "" as any; + } + return ` +[General] +instanceName=ini-instance + +[Network] +corsAllowOrigin=https://ini-cors.com + ` as any; + }); + + // Set env vars that should override INI + process.env.TRILIUM_GENERAL_INSTANCENAME = "env-instance"; + process.env.TRILIUM_NETWORK_CORS_ALLOW_ORIGIN = "https://env-cors.com"; // Using alias + + const { default: config } = await import("./config.js"); + + expect(config.General.instanceName).toBe("env-instance"); + expect(config.Network.corsAllowOrigin).toBe("https://env-cors.com"); + }); + }); + + describe("Type Transformations", () => { + it("should correctly transform boolean values", async () => { + process.env.TRILIUM_GENERAL_NOAUTHENTICATION = "true"; + process.env.TRILIUM_GENERAL_NOBACKUP = "1"; + process.env.TRILIUM_GENERAL_READONLY = "false"; + process.env.TRILIUM_NETWORK_HTTPS = "0"; + + const { default: config } = await import("./config.js"); + + expect(config.General.noAuthentication).toBe(true); + expect(config.General.noBackup).toBe(true); + expect(config.General.readOnly).toBe(false); + expect(config.Network.https).toBe(false); + }); + + it("should correctly transform integer values", async () => { + process.env.TRILIUM_SESSION_COOKIEMAXAGE = "3600"; + process.env.TRILIUM_LOGGING_RETENTIONDAYS = "7"; + + const { default: config } = await import("./config.js"); + + expect(config.Session.cookieMaxAge).toBe(3600); + expect(config.Logging.retentionDays).toBe(7); + }); + + it("should use default values for invalid integers", async () => { + process.env.TRILIUM_SESSION_COOKIEMAXAGE = "invalid"; + process.env.TRILIUM_LOGGING_RETENTION_DAYS = "not-a-number"; // Using alias + + const { default: config } = await import("./config.js"); + + expect(config.Session.cookieMaxAge).toBe(21 * 24 * 60 * 60); // Default + expect(config.Logging.retentionDays).toBe(90); // Default + }); + }); + + describe("Default Values", () => { + it("should use correct default values when no config is provided", async () => { + const { default: config } = await import("./config.js"); + + // General defaults + expect(config.General.instanceName).toBe(""); + expect(config.General.noAuthentication).toBe(false); + expect(config.General.noBackup).toBe(false); + expect(config.General.noDesktopIcon).toBe(false); + expect(config.General.readOnly).toBe(false); + + // Network defaults + expect(config.Network.host).toBe("0.0.0.0"); + expect(config.Network.port).toBe("3000"); + expect(config.Network.https).toBe(false); + expect(config.Network.certPath).toBe(""); + expect(config.Network.keyPath).toBe(""); + expect(config.Network.trustedReverseProxy).toBe(false); + expect(config.Network.corsAllowOrigin).toBe(""); + expect(config.Network.corsAllowMethods).toBe(""); + expect(config.Network.corsAllowHeaders).toBe(""); + + // Session defaults + expect(config.Session.cookieMaxAge).toBe(21 * 24 * 60 * 60); + + // Sync defaults + expect(config.Sync.syncServerHost).toBe(""); + expect(config.Sync.syncServerTimeout).toBe("120000"); + expect(config.Sync.syncProxy).toBe(""); + + // OAuth defaults + expect(config.MultiFactorAuthentication.oauthBaseUrl).toBe(""); + expect(config.MultiFactorAuthentication.oauthClientId).toBe(""); + expect(config.MultiFactorAuthentication.oauthClientSecret).toBe(""); + expect(config.MultiFactorAuthentication.oauthIssuerBaseUrl).toBe("https://accounts.google.com"); + expect(config.MultiFactorAuthentication.oauthIssuerName).toBe("Google"); + expect(config.MultiFactorAuthentication.oauthIssuerIcon).toBe(""); + + // Logging defaults + expect(config.Logging.retentionDays).toBe(90); + }); + }); +}); \ No newline at end of file diff --git a/apps/server/src/services/config.ts b/apps/server/src/services/config.ts index 84e859a68..e08b7264e 100644 --- a/apps/server/src/services/config.ts +++ b/apps/server/src/services/config.ts @@ -1,3 +1,24 @@ +/** + * ╔════════════════════════════════════════════════════════════════════════════╗ + * ║ TRILIUM CONFIGURATION RESOLUTION ORDER ║ + * ╠════════════════════════════════════════════════════════════════════════════╣ + * ║ ║ + * ║ Priority │ Source │ Example ║ + * ║ ─────────┼─────────────────────────────────┼─────────────────────────────║ + * ║ 1 │ Environment Variables │ TRILIUM_NETWORK_PORT=8080 ║ + * ║ ↓ │ (Highest Priority - Overrides all) ║ + * ║ │ ║ + * ║ 2 │ config.ini File │ [Network] ║ + * ║ ↓ │ (User Configuration) │ port=8080 ║ + * ║ │ ║ + * ║ 3 │ Default Values │ port='3000' ║ + * ║ │ (Lowest Priority - Fallback) │ (hardcoded defaults) ║ + * ║ ║ + * ╠════════════════════════════════════════════════════════════════════════════╣ + * ║ IMPORTANT: Environment variables ALWAYS override config.ini values! ║ + * ╚════════════════════════════════════════════════════════════════════════════╝ + */ + import ini from "ini"; import fs from "fs"; import dataDir from "./data_dir.js"; @@ -5,153 +26,594 @@ import path from "path"; import resourceDir from "./resource_dir.js"; import { envToBoolean, stringToInt } from "./utils.js"; +/** + * Path to the sample configuration file that serves as a template for new installations. + * This file contains all available configuration options with documentation. + */ const configSampleFilePath = path.resolve(resourceDir.RESOURCE_DIR, "config-sample.ini"); +/** + * Initialize config.ini file if it doesn't exist. + * On first run, copies the sample configuration to the data directory, + * allowing users to customize their settings. + */ if (!fs.existsSync(dataDir.CONFIG_INI_PATH)) { const configSample = fs.readFileSync(configSampleFilePath).toString("utf8"); - fs.writeFileSync(dataDir.CONFIG_INI_PATH, configSample); } -const iniConfig = ini.parse(fs.readFileSync(dataDir.CONFIG_INI_PATH, "utf-8")); +/** + * Type definition for the parsed INI configuration structure. + * The ini parser returns an object with string keys and values that can be + * strings, booleans, numbers, or nested objects. + */ +type IniConfigValue = string | number | boolean | null | undefined; +type IniConfigSection = Record; +type IniConfig = Record; +/** + * Parse the config.ini file into a JavaScript object. + * This object contains all user-defined configuration from the INI file, + * which will be merged with environment variables and defaults. + */ +const iniConfig = ini.parse(fs.readFileSync(dataDir.CONFIG_INI_PATH, "utf-8")) as IniConfig; + +/** + * Complete type-safe configuration interface for Trilium. + * This interface defines all configuration options available through + * environment variables, config.ini, or defaults. + */ export interface TriliumConfig { + /** General application settings */ General: { + /** Custom instance name for identifying this Trilium instance */ instanceName: string; + /** Whether to disable authentication (useful for local-only instances) */ noAuthentication: boolean; + /** Whether to disable automatic backups */ noBackup: boolean; + /** Whether to prevent desktop icon creation (desktop app only) */ noDesktopIcon: boolean; + /** Whether to run in read-only mode (prevents all data modifications) */ readOnly: boolean; }; + /** Network and server configuration */ Network: { + /** Host/IP address to bind the server to (e.g., '0.0.0.0' for all interfaces) */ host: string; + /** Port number for the HTTP/HTTPS server */ port: string; + /** Whether to enable HTTPS (requires certPath and keyPath) */ https: boolean; + /** Path to SSL certificate file (required when https=true) */ certPath: string; + /** Path to SSL private key file (required when https=true) */ keyPath: string; + /** Trust reverse proxy headers (boolean or specific IP/subnet string) */ trustedReverseProxy: boolean | string; + /** CORS allowed origins (comma-separated list or '*' for all) */ corsAllowOrigin: string; + /** CORS allowed methods (comma-separated HTTP methods) */ corsAllowMethods: string; + /** CORS allowed headers (comma-separated header names) */ corsAllowHeaders: string; }; + /** Session management configuration */ Session: { + /** Maximum age of session cookies in seconds (default: 21 days) */ cookieMaxAge: number; }; + /** Synchronization settings for multi-instance setups */ Sync: { + /** URL of the sync server to connect to */ syncServerHost: string; + /** Timeout for sync operations in milliseconds */ syncServerTimeout: string; + /** Proxy URL for sync connections (if behind corporate proxy) */ syncProxy: string; }; + /** Multi-factor authentication and OAuth/OpenID configuration */ MultiFactorAuthentication: { + /** Base URL for OAuth authentication endpoint */ oauthBaseUrl: string; + /** OAuth client ID from your identity provider */ oauthClientId: string; + /** OAuth client secret from your identity provider */ oauthClientSecret: string; + /** Base URL of the OAuth issuer (e.g., 'https://accounts.google.com') */ oauthIssuerBaseUrl: string; + /** Display name of the OAuth provider (shown in UI) */ oauthIssuerName: string; + /** URL to the OAuth provider's icon/logo */ oauthIssuerIcon: string; }; + /** Logging configuration */ Logging: { /** - * The number of days to keep the log files around. When rotating the logs, log files created by Trilium older than the specified amount of time will be deleted. + * The number of days to keep the log files around. When rotating the logs, + * log files created by Trilium older than the specified amount of time will be deleted. */ retentionDays: number; } } +/** + * Default retention period for log files in days. + * After this period, old log files are automatically deleted during rotation. + */ export const LOGGING_DEFAULT_RETENTION_DAYS = 90; -//prettier-ignore -const config: TriliumConfig = { +/** + * Configuration value source with precedence handling. + * This interface defines how each configuration value is resolved from multiple sources. + */ +interface ConfigValue { + /** + * Standard environment variable name following TRILIUM_[SECTION]_[KEY] pattern. + * This is the primary way to override configuration via environment. + */ + standardEnvVar?: string; + /** + * Alternative environment variable names for additional flexibility. + * These provide shorter or more intuitive names for common settings. + */ + aliasEnvVars?: string[]; + /** + * Function to retrieve the value from the parsed INI configuration. + * Returns undefined if the value is not set in config.ini. + */ + iniGetter: () => IniConfigValue | IniConfigSection; + /** + * Default value used when no environment variable or INI value is found. + * This ensures every configuration has a sensible default. + */ + defaultValue: T; + /** + * Optional transformer function to convert string values to the correct type. + * Common transformers handle boolean and integer conversions. + */ + transformer?: (value: unknown) => T; +} +/** + * Core configuration resolution function. + * + * Resolves configuration values using a clear precedence order: + * 1. Standard environment variable (highest priority) - Follows TRILIUM_[SECTION]_[KEY] pattern + * 2. Alias environment variables - Alternative names for convenience and compatibility + * 3. INI config file value - User-defined settings in config.ini + * 4. Default value (lowest priority) - Fallback to ensure valid configuration + * + * This precedence allows for flexible configuration management: + * - Environment variables for container/cloud deployments + * - config.ini for traditional installations + * - Defaults ensure the application always has valid settings + * + * @param config - Configuration value definition with sources and transformers + * @returns The resolved configuration value with appropriate type + */ +function getConfigValue(config: ConfigValue): T { + // Check standard env var first + if (config.standardEnvVar && process.env[config.standardEnvVar] !== undefined) { + const value = process.env[config.standardEnvVar]; + return config.transformer ? config.transformer(value) : value as T; + } + + // Check alternative env vars for additional flexibility + if (config.aliasEnvVars) { + for (const aliasVar of config.aliasEnvVars) { + if (process.env[aliasVar] !== undefined) { + const value = process.env[aliasVar]; + return config.transformer ? config.transformer(value) : value as T; + } + } + } + + // Check INI config + const iniValue = config.iniGetter(); + if (iniValue !== undefined && iniValue !== null && iniValue !== '') { + return config.transformer ? config.transformer(iniValue) : iniValue as T; + } + + // Return default + return config.defaultValue; +} + +/** + * Helper function to safely access INI config sections. + * The ini parser can return either a section object or a primitive value, + * so we need to check the type before accessing nested properties. + * + * @param sectionName - The name of the INI section to access + * @returns The section object or undefined if not found or not an object + */ +function getIniSection(sectionName: string): IniConfigSection | undefined { + const section = iniConfig[sectionName]; + if (section && typeof section === 'object' && !Array.isArray(section)) { + return section as IniConfigSection; + } + return undefined; +} + +/** + * Transform a value to boolean, handling various input formats. + * + * This function provides flexible boolean parsing to handle different + * configuration sources (environment variables, INI files, etc.): + * - String "true"/"false" (case-insensitive) + * - String "1"/"0" + * - Numeric 1/0 + * - Actual boolean values + * - Any other value defaults to false + * + * @param value - The value to transform (string, number, boolean, etc.) + * @returns The boolean value or false as default + */ +function transformBoolean(value: unknown): boolean { + // First try the standard envToBoolean function which handles "true"/"false" strings + const result = envToBoolean(String(value)); + if (result !== undefined) return result; + + // Handle numeric boolean values (both string and number types) + if (value === "1" || value === 1) return true; + if (value === "0" || value === 0) return false; + + // Default to false for any other value + return false; +} + +/** + * Complete configuration mapping that defines how each setting is resolved. + * + * This mapping structure: + * 1. Mirrors the INI file sections for consistency + * 2. Defines multiple sources for each configuration value + * 3. Provides type transformers where needed + * 4. Maintains compatibility with various environment variable formats + * + * Environment Variable Patterns: + * - Standard: TRILIUM_[SECTION]_[KEY] (e.g., TRILIUM_GENERAL_INSTANCENAME) + * - Aliases: Shorter alternatives (e.g., TRILIUM_OAUTH_BASE_URL) + * + * Both patterns are equally valid and can be used based on preference. + * The standard pattern provides consistency, while aliases offer convenience. + */ +const configMapping = { General: { - instanceName: - process.env.TRILIUM_GENERAL_INSTANCENAME || iniConfig.General.instanceName || "", - - noAuthentication: - envToBoolean(process.env.TRILIUM_GENERAL_NOAUTHENTICATION) || iniConfig.General.noAuthentication || false, - - noBackup: - envToBoolean(process.env.TRILIUM_GENERAL_NOBACKUP) || iniConfig.General.noBackup || false, - - noDesktopIcon: - envToBoolean(process.env.TRILIUM_GENERAL_NODESKTOPICON) || iniConfig.General.noDesktopIcon || false, - - readOnly: - envToBoolean(process.env.TRILIUM_GENERAL_READONLY) || iniConfig.General.readOnly || false + instanceName: { + standardEnvVar: 'TRILIUM_GENERAL_INSTANCENAME', + iniGetter: () => getIniSection("General")?.instanceName, + defaultValue: '' + }, + noAuthentication: { + standardEnvVar: 'TRILIUM_GENERAL_NOAUTHENTICATION', + iniGetter: () => getIniSection("General")?.noAuthentication, + defaultValue: false, + transformer: transformBoolean + }, + noBackup: { + standardEnvVar: 'TRILIUM_GENERAL_NOBACKUP', + iniGetter: () => getIniSection("General")?.noBackup, + defaultValue: false, + transformer: transformBoolean + }, + noDesktopIcon: { + standardEnvVar: 'TRILIUM_GENERAL_NODESKTOPICON', + iniGetter: () => getIniSection("General")?.noDesktopIcon, + defaultValue: false, + transformer: transformBoolean + }, + readOnly: { + standardEnvVar: 'TRILIUM_GENERAL_READONLY', + iniGetter: () => getIniSection("General")?.readOnly, + defaultValue: false, + transformer: transformBoolean + } }, - Network: { - host: - process.env.TRILIUM_NETWORK_HOST || iniConfig.Network.host || "0.0.0.0", - - port: - process.env.TRILIUM_NETWORK_PORT || iniConfig.Network.port || "3000", - - https: - envToBoolean(process.env.TRILIUM_NETWORK_HTTPS) || iniConfig.Network.https || false, - - certPath: - process.env.TRILIUM_NETWORK_CERTPATH || iniConfig.Network.certPath || "", - - keyPath: - process.env.TRILIUM_NETWORK_KEYPATH || iniConfig.Network.keyPath || "", - - trustedReverseProxy: - process.env.TRILIUM_NETWORK_TRUSTEDREVERSEPROXY || iniConfig.Network.trustedReverseProxy || false, - - corsAllowOrigin: - process.env.TRILIUM_NETWORK_CORS_ALLOW_ORIGIN || iniConfig.Network.corsAllowOrigin || "", - - corsAllowMethods: - process.env.TRILIUM_NETWORK_CORS_ALLOW_METHODS || iniConfig.Network.corsAllowMethods || "", - - corsAllowHeaders: - process.env.TRILIUM_NETWORK_CORS_ALLOW_HEADERS || iniConfig.Network.corsAllowHeaders || "" + host: { + standardEnvVar: 'TRILIUM_NETWORK_HOST', + iniGetter: () => getIniSection("Network")?.host, + defaultValue: '0.0.0.0' + }, + port: { + standardEnvVar: 'TRILIUM_NETWORK_PORT', + iniGetter: () => getIniSection("Network")?.port, + defaultValue: '3000' + }, + https: { + standardEnvVar: 'TRILIUM_NETWORK_HTTPS', + iniGetter: () => getIniSection("Network")?.https, + defaultValue: false, + transformer: transformBoolean + }, + certPath: { + standardEnvVar: 'TRILIUM_NETWORK_CERTPATH', + iniGetter: () => getIniSection("Network")?.certPath, + defaultValue: '' + }, + keyPath: { + standardEnvVar: 'TRILIUM_NETWORK_KEYPATH', + iniGetter: () => getIniSection("Network")?.keyPath, + defaultValue: '' + }, + trustedReverseProxy: { + standardEnvVar: 'TRILIUM_NETWORK_TRUSTEDREVERSEPROXY', + iniGetter: () => getIniSection("Network")?.trustedReverseProxy, + defaultValue: false as boolean | string + }, + corsAllowOrigin: { + standardEnvVar: 'TRILIUM_NETWORK_CORSALLOWORIGIN', + // alternative with underscore format + aliasEnvVars: ['TRILIUM_NETWORK_CORS_ALLOW_ORIGIN'], + iniGetter: () => getIniSection("Network")?.corsAllowOrigin, + defaultValue: '' + }, + corsAllowMethods: { + standardEnvVar: 'TRILIUM_NETWORK_CORSALLOWMETHODS', + // alternative with underscore format + aliasEnvVars: ['TRILIUM_NETWORK_CORS_ALLOW_METHODS'], + iniGetter: () => getIniSection("Network")?.corsAllowMethods, + defaultValue: '' + }, + corsAllowHeaders: { + standardEnvVar: 'TRILIUM_NETWORK_CORSALLOWHEADERS', + // alternative with underscore format + aliasEnvVars: ['TRILIUM_NETWORK_CORS_ALLOW_HEADERS'], + iniGetter: () => getIniSection("Network")?.corsAllowHeaders, + defaultValue: '' + } }, - Session: { - cookieMaxAge: - parseInt(String(process.env.TRILIUM_SESSION_COOKIEMAXAGE)) || parseInt(iniConfig?.Session?.cookieMaxAge) || 21 * 24 * 60 * 60 // 21 Days in Seconds + cookieMaxAge: { + standardEnvVar: 'TRILIUM_SESSION_COOKIEMAXAGE', + iniGetter: () => getIniSection("Session")?.cookieMaxAge, + defaultValue: 21 * 24 * 60 * 60, // 21 Days in Seconds + transformer: (value: unknown) => parseInt(String(value)) || 21 * 24 * 60 * 60 + } }, - Sync: { - syncServerHost: - process.env.TRILIUM_SYNC_SERVER_HOST || iniConfig?.Sync?.syncServerHost || "", - - syncServerTimeout: - process.env.TRILIUM_SYNC_SERVER_TIMEOUT || iniConfig?.Sync?.syncServerTimeout || "120000", - - syncProxy: - // additionally checking in iniConfig for inconsistently named syncProxy for backwards compatibility - process.env.TRILIUM_SYNC_SERVER_PROXY || iniConfig?.Sync?.syncProxy || iniConfig?.Sync?.syncServerProxy || "" + syncServerHost: { + standardEnvVar: 'TRILIUM_SYNC_SYNCSERVERHOST', + // alternative format + aliasEnvVars: ['TRILIUM_SYNC_SERVER_HOST'], + iniGetter: () => getIniSection("Sync")?.syncServerHost, + defaultValue: '' + }, + syncServerTimeout: { + standardEnvVar: 'TRILIUM_SYNC_SYNCSERVERTIMEOUT', + // alternative format + aliasEnvVars: ['TRILIUM_SYNC_SERVER_TIMEOUT'], + iniGetter: () => getIniSection("Sync")?.syncServerTimeout, + defaultValue: '120000' + }, + syncProxy: { + standardEnvVar: 'TRILIUM_SYNC_SYNCPROXY', + // alternative shorter formats + aliasEnvVars: ['TRILIUM_SYNC_SERVER_PROXY'], + // The INI config uses 'syncServerProxy' key for historical reasons (see config-sample.ini) + // We check both 'syncProxy' and 'syncServerProxy' for backward compatibility with old configs + iniGetter: () => getIniSection("Sync")?.syncProxy || getIniSection("Sync")?.syncServerProxy, + defaultValue: '' + } }, - MultiFactorAuthentication: { - oauthBaseUrl: - process.env.TRILIUM_OAUTH_BASE_URL || iniConfig?.MultiFactorAuthentication?.oauthBaseUrl || "", - - oauthClientId: - process.env.TRILIUM_OAUTH_CLIENT_ID || iniConfig?.MultiFactorAuthentication?.oauthClientId || "", - - oauthClientSecret: - process.env.TRILIUM_OAUTH_CLIENT_SECRET || iniConfig?.MultiFactorAuthentication?.oauthClientSecret || "", - - oauthIssuerBaseUrl: - process.env.TRILIUM_OAUTH_ISSUER_BASE_URL || iniConfig?.MultiFactorAuthentication?.oauthIssuerBaseUrl || "https://accounts.google.com", - - oauthIssuerName: - process.env.TRILIUM_OAUTH_ISSUER_NAME || iniConfig?.MultiFactorAuthentication?.oauthIssuerName || "Google", - - oauthIssuerIcon: - process.env.TRILIUM_OAUTH_ISSUER_ICON || iniConfig?.MultiFactorAuthentication?.oauthIssuerIcon || "" + oauthBaseUrl: { + standardEnvVar: 'TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL', + // alternative shorter format (commonly used) + aliasEnvVars: ['TRILIUM_OAUTH_BASE_URL'], + iniGetter: () => getIniSection("MultiFactorAuthentication")?.oauthBaseUrl, + defaultValue: '' + }, + oauthClientId: { + standardEnvVar: 'TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTID', + // alternative format + aliasEnvVars: ['TRILIUM_OAUTH_CLIENT_ID'], + iniGetter: () => getIniSection("MultiFactorAuthentication")?.oauthClientId, + defaultValue: '' + }, + oauthClientSecret: { + standardEnvVar: 'TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRET', + // alternative format + aliasEnvVars: ['TRILIUM_OAUTH_CLIENT_SECRET'], + iniGetter: () => getIniSection("MultiFactorAuthentication")?.oauthClientSecret, + defaultValue: '' + }, + oauthIssuerBaseUrl: { + standardEnvVar: 'TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERBASEURL', + // alternative format + aliasEnvVars: ['TRILIUM_OAUTH_ISSUER_BASE_URL'], + iniGetter: () => getIniSection("MultiFactorAuthentication")?.oauthIssuerBaseUrl, + defaultValue: 'https://accounts.google.com' + }, + oauthIssuerName: { + standardEnvVar: 'TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERNAME', + // alternative format + aliasEnvVars: ['TRILIUM_OAUTH_ISSUER_NAME'], + iniGetter: () => getIniSection("MultiFactorAuthentication")?.oauthIssuerName, + defaultValue: 'Google' + }, + oauthIssuerIcon: { + standardEnvVar: 'TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERICON', + // alternative format + aliasEnvVars: ['TRILIUM_OAUTH_ISSUER_ICON'], + iniGetter: () => getIniSection("MultiFactorAuthentication")?.oauthIssuerIcon, + defaultValue: '' + } }, - Logging: { - retentionDays: - stringToInt(process.env.TRILIUM_LOGGING_RETENTION_DAYS) ?? - stringToInt(iniConfig?.Logging?.retentionDays) ?? - LOGGING_DEFAULT_RETENTION_DAYS + retentionDays: { + standardEnvVar: 'TRILIUM_LOGGING_RETENTIONDAYS', + // alternative with underscore format + aliasEnvVars: ['TRILIUM_LOGGING_RETENTION_DAYS'], + iniGetter: () => getIniSection("Logging")?.retentionDays, + defaultValue: LOGGING_DEFAULT_RETENTION_DAYS, + transformer: (value: unknown) => stringToInt(String(value)) ?? LOGGING_DEFAULT_RETENTION_DAYS + } } }; -export default config; +/** + * Build the final configuration object by resolving all values through the mapping. + * + * This creates the runtime configuration used throughout the application by: + * 1. Iterating through each section and key in the mapping + * 2. Calling getConfigValue() to resolve each setting with proper precedence + * 3. Applying type transformers where needed (booleans, integers) + * 4. Returning a fully typed TriliumConfig object + * + * The resulting config object is immutable at runtime and represents + * the complete application configuration. + */ +const config: TriliumConfig = { + General: { + instanceName: getConfigValue(configMapping.General.instanceName), + noAuthentication: getConfigValue(configMapping.General.noAuthentication), + noBackup: getConfigValue(configMapping.General.noBackup), + noDesktopIcon: getConfigValue(configMapping.General.noDesktopIcon), + readOnly: getConfigValue(configMapping.General.readOnly) + }, + Network: { + host: getConfigValue(configMapping.Network.host), + port: getConfigValue(configMapping.Network.port), + https: getConfigValue(configMapping.Network.https), + certPath: getConfigValue(configMapping.Network.certPath), + keyPath: getConfigValue(configMapping.Network.keyPath), + trustedReverseProxy: getConfigValue(configMapping.Network.trustedReverseProxy), + corsAllowOrigin: getConfigValue(configMapping.Network.corsAllowOrigin), + corsAllowMethods: getConfigValue(configMapping.Network.corsAllowMethods), + corsAllowHeaders: getConfigValue(configMapping.Network.corsAllowHeaders) + }, + Session: { + cookieMaxAge: getConfigValue(configMapping.Session.cookieMaxAge) + }, + Sync: { + syncServerHost: getConfigValue(configMapping.Sync.syncServerHost), + syncServerTimeout: getConfigValue(configMapping.Sync.syncServerTimeout), + syncProxy: getConfigValue(configMapping.Sync.syncProxy) + }, + MultiFactorAuthentication: { + oauthBaseUrl: getConfigValue(configMapping.MultiFactorAuthentication.oauthBaseUrl), + oauthClientId: getConfigValue(configMapping.MultiFactorAuthentication.oauthClientId), + oauthClientSecret: getConfigValue(configMapping.MultiFactorAuthentication.oauthClientSecret), + oauthIssuerBaseUrl: getConfigValue(configMapping.MultiFactorAuthentication.oauthIssuerBaseUrl), + oauthIssuerName: getConfigValue(configMapping.MultiFactorAuthentication.oauthIssuerName), + oauthIssuerIcon: getConfigValue(configMapping.MultiFactorAuthentication.oauthIssuerIcon) + }, + Logging: { + retentionDays: getConfigValue(configMapping.Logging.retentionDays) + } +}; + +/** + * ===================================================================== + * ENVIRONMENT VARIABLE REFERENCE + * ===================================================================== + * + * Trilium supports flexible environment variable configuration with multiple + * naming patterns. Both formats below are equally valid and can be used + * based on your preference. + * + * CONFIGURATION PRECEDENCE: + * 1. Environment variables (highest priority) + * 2. config.ini file values + * 3. Default values (lowest priority) + * + * FULL FORMAT VARIABLES (following TRILIUM_[SECTION]_[KEY] pattern): + * ==================================================================== + * + * General Section: + * - TRILIUM_GENERAL_INSTANCENAME : Custom instance identifier + * - TRILIUM_GENERAL_NOAUTHENTICATION : Disable auth (true/false) + * - TRILIUM_GENERAL_NOBACKUP : Disable backups (true/false) + * - TRILIUM_GENERAL_NODESKTOPICON : No desktop icon (true/false) + * - TRILIUM_GENERAL_READONLY : Read-only mode (true/false) + * + * Network Section: + * - TRILIUM_NETWORK_HOST : Bind address (e.g., "0.0.0.0") + * - TRILIUM_NETWORK_PORT : Server port (e.g., "8080") + * - TRILIUM_NETWORK_HTTPS : Enable HTTPS (true/false) + * - TRILIUM_NETWORK_CERTPATH : SSL certificate file path + * - TRILIUM_NETWORK_KEYPATH : SSL private key file path + * - TRILIUM_NETWORK_TRUSTEDREVERSEPROXY : Trust proxy headers (true/false/IP) + * - TRILIUM_NETWORK_CORSALLOWORIGIN : CORS allowed origins + * - TRILIUM_NETWORK_CORSALLOWMETHODS : CORS allowed HTTP methods + * - TRILIUM_NETWORK_CORSALLOWHEADERS : CORS allowed headers + * + * Session Section: + * - TRILIUM_SESSION_COOKIEMAXAGE : Cookie lifetime in seconds + * + * Sync Section: + * - TRILIUM_SYNC_SYNCSERVERHOST : Sync server URL + * - TRILIUM_SYNC_SYNCSERVERTIMEOUT : Sync timeout in milliseconds + * - TRILIUM_SYNC_SYNCPROXY : Proxy URL for sync + * + * Multi-Factor Authentication Section: + * - TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL : OAuth base URL + * - TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTID : OAuth client ID + * - TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRET : OAuth client secret + * - TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERBASEURL : OAuth issuer URL + * - TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERNAME : OAuth provider name + * - TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERICON : OAuth provider icon + * + * Logging Section: + * - TRILIUM_LOGGING_RETENTIONDAYS : Log retention period in days + * + * SHORTER ALTERNATIVE VARIABLES (equally valid, for convenience): + * ================================================================ + * + * Network CORS (with underscores): + * - TRILIUM_NETWORK_CORS_ALLOW_ORIGIN : Same as TRILIUM_NETWORK_CORSALLOWORIGIN + * - TRILIUM_NETWORK_CORS_ALLOW_METHODS : Same as TRILIUM_NETWORK_CORSALLOWMETHODS + * - TRILIUM_NETWORK_CORS_ALLOW_HEADERS : Same as TRILIUM_NETWORK_CORSALLOWHEADERS + * + * Sync (with SERVER prefix): + * - TRILIUM_SYNC_SERVER_HOST : Same as TRILIUM_SYNC_SYNCSERVERHOST + * - TRILIUM_SYNC_SERVER_TIMEOUT : Same as TRILIUM_SYNC_SYNCSERVERTIMEOUT + * - TRILIUM_SYNC_SERVER_PROXY : Same as TRILIUM_SYNC_SYNCPROXY + * + * OAuth (simplified without section name): + * - TRILIUM_OAUTH_BASE_URL : Same as TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL + * - TRILIUM_OAUTH_CLIENT_ID : Same as TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTID + * - TRILIUM_OAUTH_CLIENT_SECRET : Same as TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRET + * - TRILIUM_OAUTH_ISSUER_BASE_URL : Same as TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERBASEURL + * - TRILIUM_OAUTH_ISSUER_NAME : Same as TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERNAME + * - TRILIUM_OAUTH_ISSUER_ICON : Same as TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERICON + * + * Logging (with underscore): + * - TRILIUM_LOGGING_RETENTION_DAYS : Same as TRILIUM_LOGGING_RETENTIONDAYS + * + * BOOLEAN VALUES: + * - Accept: "true", "false", "1", "0", 1, 0 + * - Default to false for invalid values + * + * EXAMPLES: + * export TRILIUM_NETWORK_PORT="8080" # Using full format + * export TRILIUM_OAUTH_CLIENT_ID="my-client-id" # Using shorter alternative + * export TRILIUM_GENERAL_NOAUTHENTICATION="true" # Boolean value + * export TRILIUM_SYNC_SERVER_HOST="https://sync.example.com" # Using alternative with SERVER + */ + +/** + * The exported configuration object used throughout the Trilium application. + * This object is resolved once at startup and remains immutable during runtime. + * + * To override any setting: + * 1. Set an environment variable (see documentation above) + * 2. Edit config.ini in your data directory + * 3. Defaults will be used if neither is provided + * + * @example + * // Accessing configuration in other modules: + * import config from './services/config.js'; + * + * if (config.General.noAuthentication) { + * // Skip authentication checks + * } + * + * const server = https.createServer({ + * cert: fs.readFileSync(config.Network.certPath), + * key: fs.readFileSync(config.Network.keyPath) + * }); + */ +export default config; \ No newline at end of file From 4ce9102f93ae95c7f61d84a55e6ad3be8aab276f Mon Sep 17 00:00:00 2001 From: perf3ct Date: Thu, 21 Aug 2025 02:21:00 +0000 Subject: [PATCH 02/27] feat(docs): try to also improve how environment variables are shown in docs --- .../Configuration (config.ini or e.html | 358 ++++++++++++++++-- .../Using Docker.html | 1 + .../Multi-Factor Authentication.html | 15 +- .../TLS Configuration.html | 5 +- .../Configuration (config.ini or e.md | 163 +++++++- .../1. Installing the server/Using Docker.md | 2 + .../Multi-Factor Authentication.md | 10 +- .../Server Installation/TLS Configuration.md | 8 +- 8 files changed, 511 insertions(+), 51 deletions(-) diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.html index 46abd1e24..c5d9d47b3 100644 --- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.html +++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.html @@ -1,27 +1,335 @@ -

Trilium supports configuration via a file named config.ini and - environment variables. Please review the file named config-sample.ini in - the Trilium repository - to see what values are supported.

-

You can provide the same values via environment variables instead of the config.ini file, - and these environment variables use the following format:

+

Trilium supports configuration via a file named config.ini and environment variables. This document provides a comprehensive reference for all configuration options.

+ +

Configuration Precedence

+

Configuration values are loaded in the following order of precedence (highest to lowest):

    -
  1. Environment variables should be prefixed with TRILIUM_ and - use underscores to represent the INI section structure.
    2. -
  2. The format is: TRILIUM_<SECTION>_<KEY>=<VALUE> -
    3. -
  3. The environment variables will override any matching values from config.ini
    4. +
  4. Environment variables (checked first)
    5. +
  5. config.ini file values
    6. +
  6. Default values
-

For example, if you have this in your config.ini:

[Network]
-host=localhost
-port=8080
-

You can override these values using environment variables:

TRILIUM_NETWORK_HOST=0.0.0.0
-TRILIUM_NETWORK_PORT=9000
-

The code will:

-
    -
  1. First load the config.ini file as before
    2. -
  2. Then scan all environment variables for ones starting with TRILIUM_ -
    3. -
  3. Parse these variables into section/key pairs
    4. -
  4. Merge them with the config from the file, with environment variables taking - precedence
    5. -
\ No newline at end of file + +

Environment Variable Patterns

+

Trilium supports multiple environment variable patterns for flexibility. The primary pattern is: TRILIUM_[SECTION]_[KEY]

+

Where:

+
    +
  • SECTION is the INI section name in UPPERCASE
    • +
  • KEY is the camelCase configuration key converted to UPPERCASE (e.g., instanceName → INSTANCENAME)
    • +
+

Additionally, shorter aliases are available for common configurations (see Alternative Variables section below).

+ +

Environment Variable Reference

+ +

General Section

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Environment VariableTypeDefaultDescription
TRILIUM_GENERAL_INSTANCENAMEstring""Instance name for API identification
TRILIUM_GENERAL_NOAUTHENTICATIONbooleanfalseDisable authentication (server only)
TRILIUM_GENERAL_NOBACKUPbooleanfalseDisable automatic backups
TRILIUM_GENERAL_NODESKTOPICONbooleanfalseDisable desktop icon creation
TRILIUM_GENERAL_READONLYbooleanfalseEnable read-only mode
+ +

Network Section

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Environment VariableTypeDefaultDescription
TRILIUM_NETWORK_HOSTstring"0.0.0.0"Server host binding
TRILIUM_NETWORK_PORTstring"3000"Server port
TRILIUM_NETWORK_HTTPSbooleanfalseEnable HTTPS
TRILIUM_NETWORK_CERTPATHstring""SSL certificate path
TRILIUM_NETWORK_KEYPATHstring""SSL key path
TRILIUM_NETWORK_TRUSTEDREVERSEPROXYboolean/stringfalseReverse proxy trust settings
TRILIUM_NETWORK_CORSALLOWORIGINstring""CORS allowed origins
TRILIUM_NETWORK_CORSALLOWMETHODSstring""CORS allowed methods
TRILIUM_NETWORK_CORSALLOWHEADERSstring""CORS allowed headers
+ +

Session Section

+ + + + + + + + + + + + + + + + + +
Environment VariableTypeDefaultDescription
TRILIUM_SESSION_COOKIEMAXAGEinteger1814400Session cookie max age in seconds (21 days)
+ +

Sync Section

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Environment VariableTypeDefaultDescription
TRILIUM_SYNC_SYNCSERVERHOSTstring""Sync server host URL
TRILIUM_SYNC_SYNCSERVERTIMEOUTstring"120000"Sync server timeout in milliseconds
TRILIUM_SYNC_SYNCPROXYstring""Sync proxy URL
+ +

MultiFactorAuthentication Section

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Environment VariableTypeDefaultDescription
TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURLstring""OAuth/OpenID base URL
TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTIDstring""OAuth client ID
TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRETstring""OAuth client secret
TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERBASEURLstring"https://accounts.google.com"OAuth issuer base URL
TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERNAMEstring"Google"OAuth issuer display name
TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERICONstring""OAuth issuer icon URL
+ +

Logging Section

+ + + + + + + + + + + + + + + + + +
Environment VariableTypeDefaultDescription
TRILIUM_LOGGING_RETENTIONDAYSinteger90Number of days to retain log files
+ +

Alternative Environment Variables

+

The following alternative environment variable names are also supported and work identically to their longer counterparts:

+ +

Network CORS Variables

+
    +
  • TRILIUM_NETWORK_CORS_ALLOW_ORIGIN (alternative to TRILIUM_NETWORK_CORSALLOWORIGIN)
    • +
  • TRILIUM_NETWORK_CORS_ALLOW_METHODS (alternative to TRILIUM_NETWORK_CORSALLOWMETHODS)
    • +
  • TRILIUM_NETWORK_CORS_ALLOW_HEADERS (alternative to TRILIUM_NETWORK_CORSALLOWHEADERS)
    • +
+ +

Sync Variables

+
    +
  • TRILIUM_SYNC_SERVER_HOST (alternative to TRILIUM_SYNC_SYNCSERVERHOST)
    • +
  • TRILIUM_SYNC_SERVER_TIMEOUT (alternative to TRILIUM_SYNC_SYNCSERVERTIMEOUT)
    • +
  • TRILIUM_SYNC_SERVER_PROXY (alternative to TRILIUM_SYNC_SYNCPROXY)
    • +
+ +

OAuth/MFA Variables

+
    +
  • TRILIUM_OAUTH_BASE_URL (alternative to TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL)
    • +
  • TRILIUM_OAUTH_CLIENT_ID (alternative to TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTID)
    • +
  • TRILIUM_OAUTH_CLIENT_SECRET (alternative to TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRET)
    • +
  • TRILIUM_OAUTH_ISSUER_BASE_URL (alternative to TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERBASEURL)
    • +
  • TRILIUM_OAUTH_ISSUER_NAME (alternative to TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERNAME)
    • +
  • TRILIUM_OAUTH_ISSUER_ICON (alternative to TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERICON)
    • +
+ +

Logging Variables

+
    +
  • TRILIUM_LOGGING_RETENTION_DAYS (alternative to TRILIUM_LOGGING_RETENTIONDAYS)
    • +
+ +

Boolean Values

+

Boolean environment variables accept the following values:

+
    +
  • True: "true", "1", 1
    • +
  • False: "false", "0", 0
    • +
  • Any other value defaults to false
    • +
+ +

Using Environment Variables

+

Both naming patterns are fully supported and can be used interchangeably:

+
    +
  • The longer format follows the section/key pattern for consistency with the INI file structure
    • +
  • The shorter alternatives provide convenience for common configurations
    • +
  • You can use whichever format you prefer - both are equally valid
    • +
+ +

Examples

+ +

Docker Compose Example

+
services:
+  trilium:
+    image: triliumnext/notes
+    environment:
+      # Using full format
+      TRILIUM_GENERAL_INSTANCENAME: "My Trilium Instance"
+      TRILIUM_NETWORK_PORT: "8080"
+      TRILIUM_NETWORK_CORSALLOWORIGIN: "https://myapp.com"
+      TRILIUM_SYNC_SYNCSERVERHOST: "https://sync.example.com"
+      TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL: "https://auth.example.com"
+      
+      # Or using shorter alternatives (equally valid)
+      # TRILIUM_NETWORK_CORS_ALLOW_ORIGIN: "https://myapp.com"
+      # TRILIUM_SYNC_SERVER_HOST: "https://sync.example.com"
+      # TRILIUM_OAUTH_BASE_URL: "https://auth.example.com"
+ +

Shell Export Example

+
# Using either format
+export TRILIUM_GENERAL_NOAUTHENTICATION=false
+export TRILIUM_NETWORK_HTTPS=true
+export TRILIUM_NETWORK_CERTPATH=/path/to/cert.pem
+export TRILIUM_NETWORK_KEYPATH=/path/to/key.pem
+export TRILIUM_LOGGING_RETENTIONDAYS=30
+
+# Start Trilium
+npm start
+ +

config.ini Reference

+

For the complete list of configuration options and their INI file format, please review the config-sample.ini file in the Trilium repository.

\ No newline at end of file diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/1. Installing the server/Using Docker.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/1. Installing the server/Using Docker.html index 53b131799..79c565cea 100644 --- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/1. Installing the server/Using Docker.html +++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/1. Installing the server/Using Docker.html @@ -134,6 +134,7 @@ docker run -d --name trilium -p 8080:8080 --user $(id -u):$(id -g) -v ~/trilium-
  • TRILIUM_DATA_DIR: Path to the data directory inside the container (default: /home/node/trilium-data)
    • +

    For a complete list of configuration environment variables (network settings, authentication, sync, etc.), see Configuration (config.ini or environment variables).

    Volume Permissions

    If you encounter permission issues with the data volume, ensure that:

      diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/Multi-Factor Authentication.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/Multi-Factor Authentication.html index 7840255d3..93eba27c0 100644 --- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/Multi-Factor Authentication.html +++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/Multi-Factor Authentication.html @@ -49,7 +49,12 @@ class="admonition warning"> the config.ini file (check Configuration (config.ini or environment variables) for more information).
        -
      1. You can also setup through environment variables (TRILIUM_OAUTH_BASE_URL, TRILIUM_OAUTH_CLIENT_ID and TRILIUM_OAUTH_CLIENT_SECRET).
        2. +
      2. You can also setup through environment variables: +
          +
        • Standard: TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL, TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTID, TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRET
          • +
        • Legacy (still supported): TRILIUM_OAUTH_BASE_URL, TRILIUM_OAUTH_CLIENT_ID, TRILIUM_OAUTH_CLIENT_SECRET
          • +
        +
      3. oauthBaseUrl should be the link of your Trilium instance server, for example, https://<your-trilium-domain>.
      @@ -64,8 +69,12 @@ class="admonition warning">

      The default OAuth issuer is Google. To use other services such as Authentik or Auth0, you can configure the settings via oauthIssuerBaseUrl, oauthIssuerName, and oauthIssuerIcon in the config.ini file. Alternatively, - these values can be set using environment variables: TRILIUM_OAUTH_ISSUER_BASE_URL, TRILIUM_OAUTH_ISSUER_NAME, - and TRILIUM_OAUTH_ISSUER_ICON. oauthIssuerName and oauthIssuerIcon are + these values can be set using environment variables: +

        +
      • Standard: TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERBASEURL, TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERNAME, TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERICON
        • +
      • Legacy (still supported): TRILIUM_OAUTH_ISSUER_BASE_URL, TRILIUM_OAUTH_ISSUER_NAME, TRILIUM_OAUTH_ISSUER_ICON
        • +
      + oauthIssuerName and oauthIssuerIcon are required for displaying correct issuer information at the Login page.

      Authentik

      diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/TLS Configuration.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/TLS Configuration.html index ead34359c..3bd1f0cf2 100644 --- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/TLS Configuration.html +++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/TLS Configuration.html @@ -26,7 +26,10 @@ https=true certPath=/[username]/.acme.sh/[hostname]/fullchain.cer keyPath=/[username]/.acme.sh/[hostname]/example.com.key

      You can also review the configuration file - to provide all config.ini values as environment variables instead.

      + to provide all config.ini values as environment variables instead. For example, you can configure TLS using environment variables:

      +
      export TRILIUM_NETWORK_HTTPS=true
+export TRILIUM_NETWORK_CERTPATH=/path/to/cert.pem
+export TRILIUM_NETWORK_KEYPATH=/path/to/key.pem

      The above example shows how this is set up in an environment where the certificate was generated using Let's Encrypt's ACME utility. Your paths may differ. For Docker installations, ensure these paths are within a volume diff --git a/docs/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.md b/docs/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.md index 6361cd6e1..292451913 100644 --- a/docs/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.md +++ b/docs/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.md @@ -1,30 +1,155 @@ # Configuration (config.ini or environment variables) -Trilium supports configuration via a file named `config.ini` and environment variables. Please review the file named [config-sample.ini](https://github.com/TriliumNext/Trilium/blob/main/apps/server/src/assets/config-sample.ini) in the [Trilium](https://github.com/TriliumNext/Trilium) repository to see what values are supported. -You can provide the same values via environment variables instead of the `config.ini` file, and these environment variables use the following format: +Trilium supports configuration via a file named `config.ini` and environment variables. This document provides a comprehensive reference for all configuration options. -1. Environment variables should be prefixed with `TRILIUM_` and use underscores to represent the INI section structure. -2. The format is: `TRILIUM_

      _=` -3. The environment variables will override any matching values from config.ini +## Configuration Precedence -For example, if you have this in your config.ini: +Configuration values are loaded in the following order of precedence (highest to lowest): +1. **Environment variables** (checked first) +2. **config.ini file values** +3. **Default values** -``` -[Network] -host=localhost -port=8080 +## Environment Variable Patterns + +Trilium supports multiple environment variable patterns for flexibility. The primary pattern is: `TRILIUM_[SECTION]_[KEY]` + +Where: +- `SECTION` is the INI section name in UPPERCASE +- `KEY` is the camelCase configuration key converted to UPPERCASE (e.g., `instanceName` → `INSTANCENAME`) + +Additionally, shorter aliases are available for common configurations (see Alternative Variables section below). + +## Environment Variable Reference + +### General Section + +| Environment Variable | Type | Default | Description | +|------------------|------|---------|-------------| +| `TRILIUM_GENERAL_INSTANCENAME` | string | "" | Instance name for API identification | +| `TRILIUM_GENERAL_NOAUTHENTICATION` | boolean | false | Disable authentication (server only) | +| `TRILIUM_GENERAL_NOBACKUP` | boolean | false | Disable automatic backups | +| `TRILIUM_GENERAL_NODESKTOPICON` | boolean | false | Disable desktop icon creation | +| `TRILIUM_GENERAL_READONLY` | boolean | false | Enable read-only mode | + +### Network Section + +| Environment Variable | Type | Default | Description | +|------------------|------|---------|-------------| +| `TRILIUM_NETWORK_HOST` | string | "0.0.0.0" | Server host binding | +| `TRILIUM_NETWORK_PORT` | string | "3000" | Server port | +| `TRILIUM_NETWORK_HTTPS` | boolean | false | Enable HTTPS | +| `TRILIUM_NETWORK_CERTPATH` | string | "" | SSL certificate path | +| `TRILIUM_NETWORK_KEYPATH` | string | "" | SSL key path | +| `TRILIUM_NETWORK_TRUSTEDREVERSEPROXY` | boolean/string | false | Reverse proxy trust settings | +| `TRILIUM_NETWORK_CORSALLOWORIGIN` | string | "" | CORS allowed origins | +| `TRILIUM_NETWORK_CORSALLOWMETHODS` | string | "" | CORS allowed methods | +| `TRILIUM_NETWORK_CORSALLOWHEADERS` | string | "" | CORS allowed headers | + +### Session Section + +| Environment Variable | Type | Default | Description | +|------------------|------|---------|-------------| +| `TRILIUM_SESSION_COOKIEMAXAGE` | integer | 1814400 | Session cookie max age in seconds (21 days) | + +### Sync Section + +| Environment Variable | Type | Default | Description | +|------------------|------|---------|-------------| +| `TRILIUM_SYNC_SYNCSERVERHOST` | string | "" | Sync server host URL | +| `TRILIUM_SYNC_SYNCSERVERTIMEOUT` | string | "120000" | Sync server timeout in milliseconds | +| `TRILIUM_SYNC_SYNCPROXY` | string | "" | Sync proxy URL | + +### MultiFactorAuthentication Section + +| Environment Variable | Type | Default | Description | +|------------------|------|---------|-------------| +| `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL` | string | "" | OAuth/OpenID base URL | +| `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTID` | string | "" | OAuth client ID | +| `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRET` | string | "" | OAuth client secret | +| `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERBASEURL` | string | "https://accounts.google.com" | OAuth issuer base URL | +| `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERNAME` | string | "Google" | OAuth issuer display name | +| `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERICON` | string | "" | OAuth issuer icon URL | + +### Logging Section + +| Environment Variable | Type | Default | Description | +|------------------|------|---------|-------------| +| `TRILIUM_LOGGING_RETENTIONDAYS` | integer | 90 | Number of days to retain log files | + +## Alternative Environment Variables + +The following alternative environment variable names are also supported and work identically to their longer counterparts: + +### Network CORS Variables +- `TRILIUM_NETWORK_CORS_ALLOW_ORIGIN` (alternative to `TRILIUM_NETWORK_CORSALLOWORIGIN`) +- `TRILIUM_NETWORK_CORS_ALLOW_METHODS` (alternative to `TRILIUM_NETWORK_CORSALLOWMETHODS`) +- `TRILIUM_NETWORK_CORS_ALLOW_HEADERS` (alternative to `TRILIUM_NETWORK_CORSALLOWHEADERS`) + +### Sync Variables +- `TRILIUM_SYNC_SERVER_HOST` (alternative to `TRILIUM_SYNC_SYNCSERVERHOST`) +- `TRILIUM_SYNC_SERVER_TIMEOUT` (alternative to `TRILIUM_SYNC_SYNCSERVERTIMEOUT`) +- `TRILIUM_SYNC_SERVER_PROXY` (alternative to `TRILIUM_SYNC_SYNCPROXY`) + +### OAuth/MFA Variables +- `TRILIUM_OAUTH_BASE_URL` (alternative to `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL`) +- `TRILIUM_OAUTH_CLIENT_ID` (alternative to `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTID`) +- `TRILIUM_OAUTH_CLIENT_SECRET` (alternative to `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRET`) +- `TRILIUM_OAUTH_ISSUER_BASE_URL` (alternative to `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERBASEURL`) +- `TRILIUM_OAUTH_ISSUER_NAME` (alternative to `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERNAME`) +- `TRILIUM_OAUTH_ISSUER_ICON` (alternative to `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERICON`) + +### Logging Variables +- `TRILIUM_LOGGING_RETENTION_DAYS` (alternative to `TRILIUM_LOGGING_RETENTIONDAYS`) + +## Boolean Values + +Boolean environment variables accept the following values: +- **True**: `"true"`, `"1"`, `1` +- **False**: `"false"`, `"0"`, `0` +- Any other value defaults to `false` + +## Using Environment Variables + +Both naming patterns are fully supported and can be used interchangeably: + +- The longer format follows the section/key pattern for consistency with the INI file structure +- The shorter alternatives provide convenience for common configurations +- You can use whichever format you prefer - both are equally valid + +## Examples + +### Docker Compose Example +```yaml +services: + trilium: + image: triliumnext/notes + environment: + # Using full format + TRILIUM_GENERAL_INSTANCENAME: "My Trilium Instance" + TRILIUM_NETWORK_PORT: "8080" + TRILIUM_NETWORK_CORSALLOWORIGIN: "https://myapp.com" + TRILIUM_SYNC_SYNCSERVERHOST: "https://sync.example.com" + TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL: "https://auth.example.com" + + # Or using shorter alternatives (equally valid) + # TRILIUM_NETWORK_CORS_ALLOW_ORIGIN: "https://myapp.com" + # TRILIUM_SYNC_SERVER_HOST: "https://sync.example.com" + # TRILIUM_OAUTH_BASE_URL: "https://auth.example.com" ``` -You can override these values using environment variables: +### Shell Export Example +```bash +# Using either format +export TRILIUM_GENERAL_NOAUTHENTICATION=false +export TRILIUM_NETWORK_HTTPS=true +export TRILIUM_NETWORK_CERTPATH=/path/to/cert.pem +export TRILIUM_NETWORK_KEYPATH=/path/to/key.pem +export TRILIUM_LOGGING_RETENTIONDAYS=30 -``` -TRILIUM_NETWORK_HOST=0.0.0.0 -TRILIUM_NETWORK_PORT=9000 +# Start Trilium +npm start ``` -The code will: +## config.ini Reference -1. First load the `config.ini` file as before -2. Then scan all environment variables for ones starting with `TRILIUM_` -3. Parse these variables into section/key pairs -4. Merge them with the config from the file, with environment variables taking precedence \ No newline at end of file +For the complete list of configuration options and their INI file format, please review the [config-sample.ini](https://github.com/TriliumNext/Trilium/blob/main/apps/server/src/assets/config-sample.ini) file in the Trilium repository \ No newline at end of file diff --git a/docs/User Guide/User Guide/Installation & Setup/Server Installation/1. Installing the server/Using Docker.md b/docs/User Guide/User Guide/Installation & Setup/Server Installation/1. Installing the server/Using Docker.md index 0b4fa5055..b11c079a2 100644 --- a/docs/User Guide/User Guide/Installation & Setup/Server Installation/1. Installing the server/Using Docker.md +++ b/docs/User Guide/User Guide/Installation & Setup/Server Installation/1. Installing the server/Using Docker.md @@ -187,6 +187,8 @@ docker run -d --name trilium -p 8080:8080 --user $(id -u):$(id -g) -v ~/trilium- * `TRILIUM_GID`: GID to use for the container process (passed to Docker's `--user` flag) * `TRILIUM_DATA_DIR`: Path to the data directory inside the container (default: `/home/node/trilium-data`) +For a complete list of configuration environment variables (network settings, authentication, sync, etc.), see Configuration (config.ini or environment variables). + ### Volume Permissions If you encounter permission issues with the data volume, ensure that: diff --git a/docs/User Guide/User Guide/Installation & Setup/Server Installation/Multi-Factor Authentication.md b/docs/User Guide/User Guide/Installation & Setup/Server Installation/Multi-Factor Authentication.md index d90c19434..ee6e93363 100644 --- a/docs/User Guide/User Guide/Installation & Setup/Server Installation/Multi-Factor Authentication.md +++ b/docs/User Guide/User Guide/Installation & Setup/Server Installation/Multi-Factor Authentication.md @@ -37,7 +37,9 @@ MFA can only be set up on a server instance. In order to setup OpenID, you will need to setup a authentication provider. This requires a bit of extra setup. Follow [these instructions](https://developers.google.com/identity/openid-connect/openid-connect) to setup an OpenID service through google. The Redirect URL of Trilium is `https:///callback`. 1. Set the `oauthBaseUrl`, `oauthClientId` and `oauthClientSecret` in the `config.ini` file (check Configuration (config.ini or environment variables) for more information). - 1. You can also setup through environment variables (`TRILIUM_OAUTH_BASE_URL`, `TRILIUM_OAUTH_CLIENT_ID` and `TRILIUM_OAUTH_CLIENT_SECRET`). + 1. You can also setup through environment variables: + - Standard: `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL`, `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTID`, `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRET` + - Legacy (still supported): `TRILIUM_OAUTH_BASE_URL`, `TRILIUM_OAUTH_CLIENT_ID`, `TRILIUM_OAUTH_CLIENT_SECRET` 2. `oauthBaseUrl` should be the link of your Trilium instance server, for example, `https://`. 2. Restart the server 3. Go to "Menu" -> "Options" -> "MFA" @@ -46,7 +48,11 @@ In order to setup OpenID, you will need to setup a authentication provider. This 6. Refresh the page and login through OpenID provider > [!NOTE] -> The default OAuth issuer is Google. To use other services such as Authentik or Auth0, you can configure the settings via `oauthIssuerBaseUrl`, `oauthIssuerName`, and `oauthIssuerIcon` in the `config.ini` file. Alternatively, these values can be set using environment variables: `TRILIUM_OAUTH_ISSUER_BASE_URL`, `TRILIUM_OAUTH_ISSUER_NAME`, and `TRILIUM_OAUTH_ISSUER_ICON`. `oauthIssuerName` and `oauthIssuerIcon` are required for displaying correct issuer information at the Login page. +> The default OAuth issuer is Google. To use other services such as Authentik or Auth0, you can configure the settings via `oauthIssuerBaseUrl`, `oauthIssuerName`, and `oauthIssuerIcon` in the `config.ini` file. Alternatively, these values can be set using environment variables: +> - Standard: `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERBASEURL`, `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERNAME`, `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERICON` +> - Legacy (still supported): `TRILIUM_OAUTH_ISSUER_BASE_URL`, `TRILIUM_OAUTH_ISSUER_NAME`, `TRILIUM_OAUTH_ISSUER_ICON` +> +> `oauthIssuerName` and `oauthIssuerIcon` are required for displaying correct issuer information at the Login page. #### Authentik diff --git a/docs/User Guide/User Guide/Installation & Setup/Server Installation/TLS Configuration.md b/docs/User Guide/User Guide/Installation & Setup/Server Installation/TLS Configuration.md index 67551f115..d4004a8cb 100644 --- a/docs/User Guide/User Guide/Installation & Setup/Server Installation/TLS Configuration.md +++ b/docs/User Guide/User Guide/Installation & Setup/Server Installation/TLS Configuration.md @@ -25,7 +25,13 @@ certPath=/[username]/.acme.sh/[hostname]/fullchain.cer keyPath=/[username]/.acme.sh/[hostname]/example.com.key ``` -You can also review the [configuration](../../Advanced%20Usage/Configuration%20\(config.ini%20or%20e.md) file to provide all `config.ini` values as environment variables instead. +You can also review the [configuration](../../Advanced%20Usage/Configuration%20\(config.ini%20or%20e.md) file to provide all `config.ini` values as environment variables instead. For example, you can configure TLS using environment variables: + +```bash +export TRILIUM_NETWORK_HTTPS=true +export TRILIUM_NETWORK_CERTPATH=/path/to/cert.pem +export TRILIUM_NETWORK_KEYPATH=/path/to/key.pem +``` The above example shows how this is set up in an environment where the certificate was generated using Let's Encrypt's ACME utility. Your paths may differ. For Docker installations, ensure these paths are within a volume or another directory accessible by the Docker container, such as `/home/node/trilium-data/[DIR IN DATA DIRECTORY]`. From 753d5529b22b2a02e7d01882982affe9e7412d2a Mon Sep 17 00:00:00 2001 From: perf3ct Date: Sat, 23 Aug 2025 18:40:11 +0000 Subject: [PATCH 03/27] feat(jump_to): get the styling very close to what we want it to look like... --- apps/client/src/services/note_autocomplete.ts | 30 +++++++- apps/client/src/stylesheets/style.css | 76 +++++++++++++++++-- .../src/stylesheets/theme-next/base.css | 4 +- .../src/widgets/dialogs/jump_to_note.tsx | 29 ++++++- 4 files changed, 130 insertions(+), 9 deletions(-) diff --git a/apps/client/src/services/note_autocomplete.ts b/apps/client/src/services/note_autocomplete.ts index 1138b191e..66031f482 100644 --- a/apps/client/src/services/note_autocomplete.ts +++ b/apps/client/src/services/note_autocomplete.ts @@ -36,6 +36,8 @@ export interface Suggestion { commandId?: string; commandDescription?: string; commandShortcut?: string; + attributeSnippet?: string; + highlightedAttributeSnippet?: string; } export interface Options { @@ -323,7 +325,33 @@ function initNoteAutocomplete($el: JQuery, options?: Options) { html += ''; return html; } - return ` ${suggestion.highlightedNotePathTitle}`; + // Add special class for search-notes action + const actionClass = suggestion.action === "search-notes" ? "search-notes-action" : ""; + + // Choose appropriate icon based on action + let iconClass = suggestion.icon ?? "bx bx-note"; + if (suggestion.action === "search-notes") { + iconClass = "bx bx-search"; + } else if (suggestion.action === "create-note") { + iconClass = "bx bx-plus"; + } else if (suggestion.action === "external-link") { + iconClass = "bx bx-link-external"; + } + + // Simplified HTML structure without nested divs + let html = `
      `; + html += ``; + html += ``; + html += `${suggestion.highlightedNotePathTitle}`; + + // Add attribute snippet inline if available + if (suggestion.highlightedAttributeSnippet) { + html += `${suggestion.highlightedAttributeSnippet}`; + } + + html += ``; + html += `
      `; + return html; } }, // we can't cache identical searches because notes can be created / renamed, new recent notes can be added diff --git a/apps/client/src/stylesheets/style.css b/apps/client/src/stylesheets/style.css index c5b24f88e..915c99afe 100644 --- a/apps/client/src/stylesheets/style.css +++ b/apps/client/src/stylesheets/style.css @@ -1773,20 +1773,69 @@ textarea { font-size: 1em; } +.jump-to-note-dialog .modal-dialog { + max-width: 900px; + width: 90%; +} + .jump-to-note-dialog .modal-header { align-items: center; } .jump-to-note-dialog .modal-body { padding: 0; + min-height: 200px; } .jump-to-note-results .aa-dropdown-menu { - max-height: 40vh; + max-height: calc(80vh - 200px); + width: 100%; + max-width: none; + overflow-y: auto; + overflow-x: hidden; + text-overflow: ellipsis; + box-shadow: -30px 50px 93px -50px black; +} + +.jump-to-note-results { + width: 100%; } .jump-to-note-results .aa-suggestions { - padding: 1rem; + padding: 0; + width: 100%; +} + +.jump-to-note-results .aa-dropdown-menu .aa-suggestion { + white-space: normal; + padding: 2px 12px !important; + line-height: 1.1; + position: relative; + border-radius: 0; + margin: 0 !important; +} + +.jump-to-note-results .note-suggestion { + margin: 0; + padding: 0; + line-height: 1; +} + +.jump-to-note-results .aa-suggestion:not(:last-child)::after { + display: none; /* Remove dividers for more compact look */ +} + +.jump-to-note-results .aa-suggestion:last-child::after { + display: none; +} + +.jump-to-note-results .aa-suggestion.disabled::after { + display: none; +} + +.jump-to-note-results .aa-dropdown-menu .aa-suggestion:hover, +.jump-to-note-results .aa-dropdown-menu .aa-cursor { + background-color: var(--hover-item-background-color, #f8f9fa); } /* Command palette styling */ @@ -1804,8 +1853,24 @@ textarea { .jump-to-note-dialog .aa-cursor .command-suggestion, .jump-to-note-dialog .aa-suggestion:hover .command-suggestion { - border-left-color: var(--link-color); - background-color: var(--hover-background-color); + background-color: transparent; +} + +.jump-to-note-dialog .show-in-full-search, +.jump-to-note-results .show-in-full-search { + border-top: 1px solid var(--main-border-color); + padding-top: 12px; + margin-top: 12px; +} + +.jump-to-note-results .aa-suggestion .search-notes-action { + border-top: 1px solid var(--main-border-color); + margin-top: 8px; + padding-top: 8px; +} + +.jump-to-note-results .aa-suggestion:has(.search-notes-action)::after { + display: none; } .jump-to-note-dialog .command-icon { @@ -2262,7 +2327,8 @@ footer.webview-footer button { /* Search result highlighting */ .search-result-title b, -.search-result-content b { +.search-result-content b, +.search-result-attributes b { font-weight: 900; color: var(--admonition-warning-accent-color); } diff --git a/apps/client/src/stylesheets/theme-next/base.css b/apps/client/src/stylesheets/theme-next/base.css index c992f7ecb..f8cdc1c98 100644 --- a/apps/client/src/stylesheets/theme-next/base.css +++ b/apps/client/src/stylesheets/theme-next/base.css @@ -532,8 +532,8 @@ body.mobile .dropdown-menu .dropdown-item.submenu-open .dropdown-toggle::after { /* List item */ .jump-to-note-dialog .aa-suggestions div, .note-detail-empty .aa-suggestions div { - border-radius: 6px; - padding: 6px 12px; + border-radius: 0; + padding: 12px 16px; color: var(--menu-text-color); cursor: default; } diff --git a/apps/client/src/widgets/dialogs/jump_to_note.tsx b/apps/client/src/widgets/dialogs/jump_to_note.tsx index 3af1b1aba..c3185585f 100644 --- a/apps/client/src/widgets/dialogs/jump_to_note.tsx +++ b/apps/client/src/widgets/dialogs/jump_to_note.tsx @@ -9,6 +9,7 @@ import appContext from "../../components/app_context"; import commandRegistry from "../../services/command_registry"; import { refToJQuerySelector } from "../react/react_utils"; import useTriliumEvent from "../react/hooks"; +import shortcutService from "../../services/shortcuts"; const KEEP_LAST_SEARCH_FOR_X_SECONDS = 120; @@ -83,6 +84,27 @@ function JumpToNoteDialogComponent() { $autoComplete .trigger("focus") .trigger("select"); + + // Add keyboard shortcut for full search + shortcutService.bindElShortcut($autoComplete, "ctrl+return", () => { + if (!isCommandMode) { + showInFullSearch(); + } + }); + } + + async function showInFullSearch() { + try { + setShown(false); + const searchString = actualText.current?.trim(); + if (searchString && !searchString.startsWith(">")) { + await appContext.triggerCommand("searchNotes", { + searchString + }); + } + } catch (error) { + console.error("Failed to trigger full search:", error); + } } return ( @@ -108,7 +130,12 @@ function JumpToNoteDialogComponent() { />} onShown={onShown} onHidden={() => setShown(false)} - footer={!isCommandMode &&