Dockery/Trilium
1
0
Fork 0
mirror of https://github.com/zadam/trilium.git synced 2025-11-01 19:05:59 +01:00
Code Issues Packages Projects Releases Activity

feat(docs): also improve how environment variables are shown in docs (#6727)

Browse Source
This commit is contained in:
Elian Doran
2025-08-25 19:29:40 +03:00
committed by GitHub
parent 70d7ad0b1a 4ce9102f93
commit 3c25cda4c0
8 changed files with 511 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

358
apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.html generated vendored
View File

@@ -1,27 +1,335 @@
<p>Trilium supports configuration via a file named <code>config.ini</code> and
environment variables. Please review the file named <a href="https://github.com/TriliumNext/Trilium/blob/main/apps/server/src/assets/config-sample.ini">config-sample.ini</a> in
the <a href="https://github.com/TriliumNext/Trilium">Trilium</a> repository
to see what values are supported.</p>
<p>You can provide the same values via environment variables instead of the <code>config.ini</code> file,
and these environment variables use the following format:</p>
<p>Trilium supports configuration via a file named <code>config.ini</code> and environment variables. This document provides a comprehensive reference for all configuration options.</p>
<h2>Configuration Precedence</h2>
<p>Configuration values are loaded in the following order of precedence (highest to lowest):</p>
<ol>
<li>Environment variables should be prefixed with <code>TRILIUM_</code> and
use underscores to represent the INI section structure.</li>
<li>The format is: <code>TRILIUM_&lt;SECTION&gt;_&lt;KEY&gt;=&lt;VALUE&gt;</code>
</li>
<li>The environment variables will override any matching values from config.ini</li>
<li><strong>Environment variables</strong> (checked first)</li>
<li><strong>config.ini file values</strong></li>
<li><strong>Default values</strong></li>
</ol>
<p>For example, if you have this in your config.ini:</p><pre><code class="language-text-x-trilium-auto">[Network]
host=localhost
port=8080</code></pre>
<p>You can override these values using environment variables:</p><pre><code class="language-text-x-trilium-auto">TRILIUM_NETWORK_HOST=0.0.0.0
TRILIUM_NETWORK_PORT=9000</code></pre>
<p>The code will:</p>
<ol>
<li>First load the <code>config.ini</code> file as before</li>
<li>Then scan all environment variables for ones starting with <code>TRILIUM_</code>
</li>
<li>Parse these variables into section/key pairs</li>
<li>Merge them with the config from the file, with environment variables taking
precedence</li>
</ol>
<h2>Environment Variable Patterns</h2>
<p>Trilium supports multiple environment variable patterns for flexibility. The primary pattern is: <code>TRILIUM_[SECTION]_[KEY]</code></p>
<p>Where:</p>
<ul>
<li><code>SECTION</code> is the INI section name in UPPERCASE</li>
<li><code>KEY</code> is the camelCase configuration key converted to UPPERCASE (e.g., <code>instanceName</code> → <code>INSTANCENAME</code>)</li>
</ul>
<p>Additionally, shorter aliases are available for common configurations (see Alternative Variables section below).</p>
<h2>Environment Variable Reference</h2>
<h3>General Section</h3>
<table>
<thead>
<tr>
<th>Environment Variable</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>TRILIUM_GENERAL_INSTANCENAME</code></td>
<td>string</td>
<td>""</td>
<td>Instance name for API identification</td>
</tr>
<tr>
<td><code>TRILIUM_GENERAL_NOAUTHENTICATION</code></td>
<td>boolean</td>
<td>false</td>
<td>Disable authentication (server only)</td>
</tr>
<tr>
<td><code>TRILIUM_GENERAL_NOBACKUP</code></td>
<td>boolean</td>
<td>false</td>
<td>Disable automatic backups</td>
</tr>
<tr>
<td><code>TRILIUM_GENERAL_NODESKTOPICON</code></td>
<td>boolean</td>
<td>false</td>
<td>Disable desktop icon creation</td>
</tr>
<tr>
<td><code>TRILIUM_GENERAL_READONLY</code></td>
<td>boolean</td>
<td>false</td>
<td>Enable read-only mode</td>
</tr>
</tbody>
</table>
<h3>Network Section</h3>
<table>
<thead>
<tr>
<th>Environment Variable</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>TRILIUM_NETWORK_HOST</code></td>
<td>string</td>
<td>"0.0.0.0"</td>
<td>Server host binding</td>
</tr>
<tr>
<td><code>TRILIUM_NETWORK_PORT</code></td>
<td>string</td>
<td>"3000"</td>
<td>Server port</td>
</tr>
<tr>
<td><code>TRILIUM_NETWORK_HTTPS</code></td>
<td>boolean</td>
<td>false</td>
<td>Enable HTTPS</td>
</tr>
<tr>
<td><code>TRILIUM_NETWORK_CERTPATH</code></td>
<td>string</td>
<td>""</td>
<td>SSL certificate path</td>
</tr>
<tr>
<td><code>TRILIUM_NETWORK_KEYPATH</code></td>
<td>string</td>
<td>""</td>
<td>SSL key path</td>
</tr>
<tr>
<td><code>TRILIUM_NETWORK_TRUSTEDREVERSEPROXY</code></td>
<td>boolean/string</td>
<td>false</td>
<td>Reverse proxy trust settings</td>
</tr>
<tr>
<td><code>TRILIUM_NETWORK_CORSALLOWORIGIN</code></td>
<td>string</td>
<td>""</td>
<td>CORS allowed origins</td>
</tr>
<tr>
<td><code>TRILIUM_NETWORK_CORSALLOWMETHODS</code></td>
<td>string</td>
<td>""</td>
<td>CORS allowed methods</td>
</tr>
<tr>
<td><code>TRILIUM_NETWORK_CORSALLOWHEADERS</code></td>
<td>string</td>
<td>""</td>
<td>CORS allowed headers</td>
</tr>
</tbody>
</table>
<h3>Session Section</h3>
<table>
<thead>
<tr>
<th>Environment Variable</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>TRILIUM_SESSION_COOKIEMAXAGE</code></td>
<td>integer</td>
<td>1814400</td>
<td>Session cookie max age in seconds (21 days)</td>
</tr>
</tbody>
</table>
<h3>Sync Section</h3>
<table>
<thead>
<tr>
<th>Environment Variable</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>TRILIUM_SYNC_SYNCSERVERHOST</code></td>
<td>string</td>
<td>""</td>
<td>Sync server host URL</td>
</tr>
<tr>
<td><code>TRILIUM_SYNC_SYNCSERVERTIMEOUT</code></td>
<td>string</td>
<td>"120000"</td>
<td>Sync server timeout in milliseconds</td>
</tr>
<tr>
<td><code>TRILIUM_SYNC_SYNCPROXY</code></td>
<td>string</td>
<td>""</td>
<td>Sync proxy URL</td>
</tr>
</tbody>
</table>
<h3>MultiFactorAuthentication Section</h3>
<table>
<thead>
<tr>
<th>Environment Variable</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL</code></td>
<td>string</td>
<td>""</td>
<td>OAuth/OpenID base URL</td>
</tr>
<tr>
<td><code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTID</code></td>
<td>string</td>
<td>""</td>
<td>OAuth client ID</td>
</tr>
<tr>
<td><code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRET</code></td>
<td>string</td>
<td>""</td>
<td>OAuth client secret</td>
</tr>
<tr>
<td><code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERBASEURL</code></td>
<td>string</td>
<td>"https://accounts.google.com"</td>
<td>OAuth issuer base URL</td>
</tr>
<tr>
<td><code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERNAME</code></td>
<td>string</td>
<td>"Google"</td>
<td>OAuth issuer display name</td>
</tr>
<tr>
<td><code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERICON</code></td>
<td>string</td>
<td>""</td>
<td>OAuth issuer icon URL</td>
</tr>
</tbody>
</table>
<h3>Logging Section</h3>
<table>
<thead>
<tr>
<th>Environment Variable</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>TRILIUM_LOGGING_RETENTIONDAYS</code></td>
<td>integer</td>
<td>90</td>
<td>Number of days to retain log files</td>
</tr>
</tbody>
</table>
<h2>Alternative Environment Variables</h2>
<p>The following alternative environment variable names are also supported and work identically to their longer counterparts:</p>
<h3>Network CORS Variables</h3>
<ul>
<li><code>TRILIUM_NETWORK_CORS_ALLOW_ORIGIN</code> (alternative to <code>TRILIUM_NETWORK_CORSALLOWORIGIN</code>)</li>
<li><code>TRILIUM_NETWORK_CORS_ALLOW_METHODS</code> (alternative to <code>TRILIUM_NETWORK_CORSALLOWMETHODS</code>)</li>
<li><code>TRILIUM_NETWORK_CORS_ALLOW_HEADERS</code> (alternative to <code>TRILIUM_NETWORK_CORSALLOWHEADERS</code>)</li>
</ul>
<h3>Sync Variables</h3>
<ul>
<li><code>TRILIUM_SYNC_SERVER_HOST</code> (alternative to <code>TRILIUM_SYNC_SYNCSERVERHOST</code>)</li>
<li><code>TRILIUM_SYNC_SERVER_TIMEOUT</code> (alternative to <code>TRILIUM_SYNC_SYNCSERVERTIMEOUT</code>)</li>
<li><code>TRILIUM_SYNC_SERVER_PROXY</code> (alternative to <code>TRILIUM_SYNC_SYNCPROXY</code>)</li>
</ul>
<h3>OAuth/MFA Variables</h3>
<ul>
<li><code>TRILIUM_OAUTH_BASE_URL</code> (alternative to <code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL</code>)</li>
<li><code>TRILIUM_OAUTH_CLIENT_ID</code> (alternative to <code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTID</code>)</li>
<li><code>TRILIUM_OAUTH_CLIENT_SECRET</code> (alternative to <code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRET</code>)</li>
<li><code>TRILIUM_OAUTH_ISSUER_BASE_URL</code> (alternative to <code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERBASEURL</code>)</li>
<li><code>TRILIUM_OAUTH_ISSUER_NAME</code> (alternative to <code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERNAME</code>)</li>
<li><code>TRILIUM_OAUTH_ISSUER_ICON</code> (alternative to <code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERICON</code>)</li>
</ul>
<h3>Logging Variables</h3>
<ul>
<li><code>TRILIUM_LOGGING_RETENTION_DAYS</code> (alternative to <code>TRILIUM_LOGGING_RETENTIONDAYS</code>)</li>
</ul>
<h2>Boolean Values</h2>
<p>Boolean environment variables accept the following values:</p>
<ul>
<li><strong>True</strong>: <code>"true"</code>, <code>"1"</code>, <code>1</code></li>
<li><strong>False</strong>: <code>"false"</code>, <code>"0"</code>, <code>0</code></li>
<li>Any other value defaults to <code>false</code></li>
</ul>
<h2>Using Environment Variables</h2>
<p>Both naming patterns are fully supported and can be used interchangeably:</p>
<ul>
<li>The longer format follows the section/key pattern for consistency with the INI file structure</li>
<li>The shorter alternatives provide convenience for common configurations</li>
<li>You can use whichever format you prefer - both are equally valid</li>
</ul>
<h2>Examples</h2>
<h3>Docker Compose Example</h3>
<pre><code class="language-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"</code></pre>
<h3>Shell Export Example</h3>
<pre><code class="language-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
# Start Trilium
npm start</code></pre>
<h2>config.ini Reference</h2>
<p>For the complete list of configuration options and their INI file format, please review the <a href="https://github.com/TriliumNext/Trilium/blob/main/apps/server/src/assets/config-sample.ini">config-sample.ini</a> file in the Trilium repository.</p>

1
apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/1. Installing the server/Using Docker.html generated vendored
View File

@@ -134,6 +134,7 @@ docker run -d --name trilium -p 8080:8080 --user $(id -u):$(id -g) -v ~/trilium-
<li><code>TRILIUM_DATA_DIR</code>: Path to the data directory inside the container
(default: <code>/home/node/trilium-data</code>)</li>
</ul>
<p>For a complete list of configuration environment variables (network settings, authentication, sync, etc.), see <a class="reference-link" href="#root/_help_Gzjqa934BdH4">Configuration (config.ini or environment variables)</a>.</p>
<h3>Volume Permissions</h3>
<p>If you encounter permission issues with the data volume, ensure that:</p>
<ol>

15
apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/Multi-Factor Authentication.html generated vendored
View File

@@ -49,7 +49,12 @@ class="admonition warning">
the <code>config.ini</code> file (check&nbsp;<a class="reference-link" href="#root/_help_Gzjqa934BdH4">Configuration (config.ini or environment variables)</a>&nbsp;for
more information).
<ol>
<li>You can also setup through environment variables (<code>TRILIUM_OAUTH_BASE_URL</code>, <code>TRILIUM_OAUTH_CLIENT_ID</code> and <code>TRILIUM_OAUTH_CLIENT_SECRET</code>).</li>
<li>You can also setup through environment variables:
<ul>
<li>Standard: <code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL</code>, <code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTID</code>, <code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRET</code></li>
<li>Legacy (still supported): <code>TRILIUM_OAUTH_BASE_URL</code>, <code>TRILIUM_OAUTH_CLIENT_ID</code>, <code>TRILIUM_OAUTH_CLIENT_SECRET</code></li>
</ul>
</li>
<li><code>oauthBaseUrl</code> should be the link of your Trilium instance server,
for example, <code>https://&lt;your-trilium-domain&gt;</code>.</li>
</ol>
@@ -64,8 +69,12 @@ class="admonition warning">
<p>The default OAuth issuer is Google. To use other services such as Authentik
or Auth0, you can configure the settings via <code>oauthIssuerBaseUrl</code>, <code>oauthIssuerName</code>,
and <code>oauthIssuerIcon</code> in the <code>config.ini</code> file. Alternatively,
these values can be set using environment variables: <code>TRILIUM_OAUTH_ISSUER_BASE_URL</code>, <code>TRILIUM_OAUTH_ISSUER_NAME</code>,
and <code>TRILIUM_OAUTH_ISSUER_ICON</code>. <code>oauthIssuerName</code> and <code>oauthIssuerIcon</code> are
these values can be set using environment variables:
<ul>
<li>Standard: <code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERBASEURL</code>, <code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERNAME</code>, <code>TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHISSUERICON</code></li>
<li>Legacy (still supported): <code>TRILIUM_OAUTH_ISSUER_BASE_URL</code>, <code>TRILIUM_OAUTH_ISSUER_NAME</code>, <code>TRILIUM_OAUTH_ISSUER_ICON</code></li>
</ul>
<code>oauthIssuerName</code> and <code>oauthIssuerIcon</code> are
required for displaying correct issuer information at the Login page.</p>
</aside>
<h4>Authentik</h4>

5
apps/server/src/assets/doc_notes/en/User Guide/User Guide/Installation & Setup/Server Installation/TLS Configuration.html generated vendored
View File

@@ -26,7 +26,10 @@ https=true
certPath=/[username]/.acme.sh/[hostname]/fullchain.cer
keyPath=/[username]/.acme.sh/[hostname]/example.com.key</code></pre>
<p>You can also review the <a href="#root/_help_Gzjqa934BdH4">configuration</a> file
to provide all <code>config.ini</code> values as environment variables instead.</p>
to provide all <code>config.ini</code> values as environment variables instead. For example, you can configure TLS using environment variables:</p>
<pre><code class="language-bash">export TRILIUM_NETWORK_HTTPS=true
export TRILIUM_NETWORK_CERTPATH=/path/to/cert.pem
export TRILIUM_NETWORK_KEYPATH=/path/to/key.pem</code></pre>
<p>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