criticalbasics https://criticalbasics.xyz Retro is now! Zola en Mon, 04 May 2026 00:00:00 +0000 Dark/Light-Mode Switcher for Arch Linux + i3wm Mon, 04 May 2026 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/i3-dark-light-mode-switcher/ https://criticalbasics.xyz/posts/i3-dark-light-mode-switcher/ <p>Welcome to this detailed guide showing you how to set up an effective Dark/Light-Mode switcher for your Arch Linux system with i3wm. In a world where most applications have their own theming logic, we will build an orchestration solution that controls many components simultaneously to create a consistent experience.</p> <p>We will integrate GTK, Qt, terminal, and even CLI applications into our theme switcher, all controlled by a single keypress.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2026-05-04</td><td><strong>Initial Version:</strong> Comprehensive guide for Dark/Light-Mode switching on Arch Linux and i3wm.</td></tr> </tbody></table> </div> <hr /> <h2 id="architectural-overview">Architectural Overview</h2> <p>i3wm itself does not provide global theme management. Styling is handled by various components such as GTK, Qt, Xresources, and individual applications. Our solution is based on an <strong>orchestrator architecture</strong> that uses <code>darkman</code> as the central control unit.</p> <p><code>darkman</code> performs two main tasks:</p> <ol> <li>It executes your customized hook scripts, which adapt specific applications and environments.</li> <li>It propagates the dark mode status via the XDG-Desktop-Portal to modern applications (e.g., Firefox, Thunderbird), which then switch their theme without needing a restart.</li> </ol> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>$mod+Shift+d → darkman toggle → Hook Scripts → Individual Apps</span></span> <span class="giallo-l"><span> │</span></span> <span class="giallo-l"><span> └──► XDG-Portal (Firefox, Thunderbird, etc. via Signal)</span></span></code></pre><h2 id="quickstart-copy-paste">Quickstart (Copy &amp; Paste)</h2> <p>If you just want a minimal, working setup — GTK + Firefox + i3 + Alacritty controlled by <code>$mod+Shift+d</code> — follow this Quickstart. You can extend with Polybar, VSCodium, neomutt, and Qt apps later by following the full guide below.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># 1. Install prerequisites</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> darkman xdg-desktop-portal xdg-desktop-portal-gtk</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> jq libnotify alacritty</span></span> <span class="giallo-l"><span style="color: #B392F0;">yay</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> dracula-gtk-theme</span><span style="color: #6A737D;"> # or fall back to Adwaita-dark (handled by hook)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 2. Create directory layout</span></span> <span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.local/share/dark-mode.d</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ~/.local/share/light-mode.d</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ~/.config/themes/{dracula,solarized-light}</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ~/.config/alacritty</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ~/.config/xdg-desktop-portal</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 3. Tell xdg-desktop-portal to use darkman as the Settings backend.</span></span> <span class="giallo-l"><span style="color: #6A737D;"># REQUIRED since xdg-desktop-portal 1.17.0 — without this, Firefox &amp;</span></span> <span class="giallo-l"><span style="color: #6A737D;"># other portal-aware apps will not see darkman&#39;s color-scheme.</span></span> <span class="giallo-l"><span style="color: #B392F0;">cat</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> ~/.config/xdg-desktop-portal/portals.conf</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;">&#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">[preferred]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">org.freedesktop.impl.portal.Settings=darkman</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 4. Pull terminal theme files</span></span> <span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -fsSL</span><span style="color: #9ECBFF;"> https://raw.githubusercontent.com/dracula/alacritty/master/dracula.toml</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -o</span><span style="color: #9ECBFF;"> ~/.config/themes/dracula/alacritty.toml</span></span> <span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -fsSL</span><span style="color: #9ECBFF;"> https://raw.githubusercontent.com/alacritty/alacritty-theme/master/themes/solarized_light.toml</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -o</span><span style="color: #9ECBFF;"> ~/.config/themes/solarized-light/alacritty.toml</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 5. Wire up i3 (idempotent — safe to run twice)</span></span> <span class="giallo-l"><span style="color: #B392F0;">grep</span><span style="color: #79B8FF;"> -q</span><span style="color: #9ECBFF;"> &quot;bindsym </span><span style="color: #79B8FF;">\$</span><span style="color: #9ECBFF;">mod+Shift+d exec --no-startup-id darkman toggle&quot; ~/.config/i3/config</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &#39;bindsym $mod+Shift+d exec --no-startup-id darkman toggle&#39;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;"> ~/.config/i3/config</span></span> <span class="giallo-l"><span style="color: #B392F0;">grep</span><span style="color: #79B8FF;"> -q</span><span style="color: #9ECBFF;"> &quot;include ~/.config/i3/theme.conf&quot; ~/.config/i3/config</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &#39;include ~/.config/i3/theme.conf&#39;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;"> ~/.config/i3/config</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 6. Enable the service</span></span> <span class="giallo-l"><span style="color: #B392F0;">systemctl</span><span style="color: #79B8FF;"> --user</span><span style="color: #9ECBFF;"> enable</span><span style="color: #79B8FF;"> --now</span><span style="color: #9ECBFF;"> darkman.service</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 7. Quick smoke test</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Note: these only have a *visible* effect after you create the</span></span> <span class="giallo-l"><span style="color: #6A737D;"># hook scripts in Steps 7 &amp; 8. Until then darkman just flips an</span></span> <span class="giallo-l"><span style="color: #6A737D;"># internal flag — nothing recolors yet.</span></span> <span class="giallo-l"><span style="color: #B392F0;">darkman</span><span style="color: #9ECBFF;"> get</span><span style="color: #6A737D;"> # current mode</span></span> <span class="giallo-l"><span style="color: #B392F0;">darkman</span><span style="color: #9ECBFF;"> toggle</span><span style="color: #6A737D;"> # switch without using the keybinding</span></span></code></pre> <p>Then create the i3 theme stubs and the hook scripts as described in <a href="https://criticalbasics.xyz/posts/i3-dark-light-mode-switcher/#step-7-the-dark-mode-hook-script">Step 7</a> and <a href="https://criticalbasics.xyz/posts/i3-dark-light-mode-switcher/#step-8-the-light-mode-hook-script">Step 8</a>. After that, <code>$mod+Shift+d</code> should already give you a working basic switch.</p> <blockquote> <p><strong>Expected result after the Quickstart + minimal hooks:</strong> Pressing <code>$mod+Shift+d</code> (or running <code>darkman toggle</code>) should immediately recolor i3 borders, switch the Alacritty theme without restarting the terminal, and — if Firefox is open with <code>widget.use-xdg-desktop-portal.settings = 1</code> set in <code>about:config</code> — flip Firefox’s UI between light and dark. If any of these don’t react, see the <a href="https://criticalbasics.xyz/posts/i3-dark-light-mode-switcher/#reality-check-verify-persistence">Reality Check</a> section.</p> </blockquote> <h2 id="recommended-approach-set-up-step-by-step">Recommended Approach: Set up Step-by-Step</h2> <p>To avoid frustration and facilitate troubleshooting, you should approach the setup in phases. This way, you’ll always know which component is responsible for problems.</p> <ol> <li><strong>Phase 1 — Basic:</strong> <code>darkman</code> + GTK + Firefox/Thunderbird + i3 + Alacritty. These components are reliable and cover the majority of the visual interface.</li> <li><strong>Phase 2 — Extension:</strong> Polybar + VSCodium + neomutt. This requires a bit more configuration, but the functionality is stable.</li> <li><strong>Phase 3 — Problem Children:</strong> Qt apps (KeePassXC, nheko), Chromium, urxvt live-reload. These applications can present app-specific challenges and should be tested separately.</li> </ol> <p>Follow this tutorial linearly and test the functionality after each phase before moving on to the next.</p> <h2 id="theme-choice-dracula-solarized-light">Theme Choice: Dracula ↔ Solarized Light</h2> <p>For dark mode, we will use <strong>Dracula</strong>, a popular and well-supported theme. For the light mode counterpart, several options are available:</p> <ul> <li><strong>Solarized Light:</strong> A classic with well-documented color palettes for many tools, known for its good readability.</li> <li><strong>Catppuccin Latte:</strong> A modern alternative that aesthetically complements Catppuccin Mocha (if you decide to replace Dracula later).</li> <li><strong>GitHub Light:</strong> A pragmatic choice, as many editor themes and browser extensions are available for it.</li> </ul> <p>This guide will use the <strong>Dracula ↔ Solarized Light</strong> pair.</p> <h2 id="migrating-from-a-hand-themed-setup">Migrating from a hand-themed setup</h2> <p>If you’ve already painstakingly themed each application by hand, read this section before running any of the hook scripts. The hooks are designed for a setup built <em>with</em> darkman in mind — applied to an existing setup, they will overwrite or symlink-replace several files without asking.</p> <h3 id="what-the-hooks-will-overwrite-destructive">What the hooks will overwrite (destructive)</h3> <p>These files are rewritten in full on every toggle:</p> <ul> <li><code>~/.config/gtk-3.0/settings.ini</code> and <code>~/.config/gtk-4.0/settings.ini</code> — replaced via <code>cat &gt; ... &lt;&lt;EOF</code>. Any custom keys you have here (cursor theme, font name, dconf-style overrides) will be lost on first toggle.</li> <li><code>~/.config/qt5ct/qt5ct.conf</code>, <code>~/.config/qt6ct/qt6ct.conf</code> — only the <code>color_scheme_path</code> line is rewritten via <code>sed</code>. The rest of the file is preserved.</li> <li><code>~/.config/VSCodium/User/settings.json</code> — only the <code>workbench.colorTheme</code> key is updated via <code>jq</code>. <strong>Caveat:</strong> if your settings.json contains JSONC-style comments, <code>jq</code> will strip them.</li> </ul> <h3 id="what-the-hooks-will-replace-via-symlink-non-destructive-but-pathing-changes">What the hooks will replace via symlink (non-destructive but pathing changes)</h3> <p>These paths become symlinks pointing into <code>~/.config/themes/&lt;theme&gt;/</code>. If a real file exists at the path, the symlink replaces it (the original file stays where it was, but is no longer reachable through the original path):</p> <ul> <li><code>~/.Xresources</code></li> <li><code>~/.config/i3/theme.conf</code></li> <li><code>~/.config/alacritty/theme.toml</code></li> <li><code>~/.config/polybar/config.ini</code></li> <li><code>~/.config/neomutt/colors</code></li> <li><code>~/.config/nvim/colorscheme.vim</code></li> </ul> <h3 id="what-is-changed-system-wide-via-gsettings">What is changed system-wide via gsettings</h3> <p><code>org.gnome.desktop.interface gtk-theme</code> and <code>color-scheme</code> — affects every GTK app on your system that reads gsettings, regardless of whether you intended to theme it through darkman.</p> <h3 id="what-is-not-touched">What is NOT touched</h3> <p>Your main configuration files (<code>~/.config/i3/config</code>, <code>~/.config/alacritty/alacritty.toml</code>, your Polybar bar layout, your <code>.muttrc</code>, your Neovim init, your shell rc files, Firefox/Chromium profiles) are only <em>referenced</em> via <code>include</code>/<code>import</code>/<code>source</code> lines. They stay where they are.</p> <h3 id="recommended-snapshot-before-the-first-toggle">Recommended: snapshot before the first toggle</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/theme-switcher-backup</span></span> <span class="giallo-l"><span style="color: #F97583;">for</span><span> path</span><span style="color: #F97583;"> in</span><span> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ~/.config/gtk-3.0</span><span> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ~/.config/gtk-4.0</span><span> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ~/.config/qt5ct</span><span> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ~/.config/qt6ct</span><span> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ~/.Xresources</span><span> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ~/.config/VSCodium/User/settings.json</span></span> <span class="giallo-l"><span style="color: #F97583;">do</span></span> <span class="giallo-l"><span> [[</span><span style="color: #F97583;"> -e</span><span style="color: #9ECBFF;"> &quot;</span><span>$path</span><span style="color: #9ECBFF;">&quot;</span><span> ]] &amp;&amp;</span><span style="color: #B392F0;"> cp</span><span style="color: #79B8FF;"> -a</span><span style="color: #9ECBFF;"> &quot;</span><span>$path</span><span style="color: #9ECBFF;">&quot; ~/theme-switcher-backup/</span></span> <span class="giallo-l"><span style="color: #F97583;">done</span></span></code></pre> <p>After the first toggle, diff what changed:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">diff</span><span style="color: #79B8FF;"> -r</span><span style="color: #9ECBFF;"> ~/theme-switcher-backup/gtk-3.0 ~/.config/gtk-3.0</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span></span></code></pre> <p>If you find that lines you cared about were lost, <strong>the right fix is not to protect your old config but to teach the hooks about your custom keys</strong> — open the hook scripts in <a href="https://criticalbasics.xyz/posts/i3-dark-light-mode-switcher/#step-7-the-dark-mode-hook-script">Step 7</a> and <a href="https://criticalbasics.xyz/posts/i3-dark-light-mode-switcher/#step-8-the-light-mode-hook-script">Step 8</a> and add your custom lines into the <code>cat &gt; settings.ini &lt;&lt;EOF</code> blocks. Same logic applies to qt5ct, VSCodium, etc.: extend the hook, don’t fight it.</p> <h2 id="step-1-install-prerequisites">Step 1: Install Prerequisites</h2> <h3 id="darkman-and-portal-infrastructure"><code>darkman</code> and Portal Infrastructure</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> darkman xdg-desktop-portal xdg-desktop-portal-gtk jq libnotify</span></span> <span class="giallo-l"><span style="color: #B392F0;">systemctl</span><span style="color: #79B8FF;"> --user</span><span style="color: #9ECBFF;"> enable</span><span style="color: #79B8FF;"> --now</span><span style="color: #9ECBFF;"> darkman.service</span></span></code></pre> <ul> <li><code>jq</code> is needed for patching VSCodium settings.</li> <li><code>libnotify</code> enables notifications via <code>notify-send</code>.</li> </ul> <h3 id="configure-xdg-desktop-portal-to-use-darkman-required">Configure xdg-desktop-portal to use darkman (REQUIRED)</h3> <p>This is the single most overlooked step in dark-mode setups. Since <code>xdg-desktop-portal 1.17.0</code>, the portal must be told <em>which</em> backend implements the Settings interface — otherwise Firefox, Thunderbird, and other portal-aware apps will never see darkman’s color-scheme value, no matter how correctly darkman itself is configured.</p> <p>Create <code>~/.config/xdg-desktop-portal/portals.conf</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.config/xdg-desktop-portal</span></span> <span class="giallo-l"><span style="color: #B392F0;">cat</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> ~/.config/xdg-desktop-portal/portals.conf</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;">&#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">[preferred]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">org.freedesktop.impl.portal.Settings=darkman</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre> <p>You can verify the portal really hands darkman’s value to clients with:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gdbus</span><span style="color: #9ECBFF;"> call</span><span style="color: #79B8FF;"> --session \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> --dest</span><span style="color: #9ECBFF;"> org.freedesktop.portal.Desktop</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> --object-path</span><span style="color: #9ECBFF;"> /org/freedesktop/portal/desktop</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> --method</span><span style="color: #9ECBFF;"> org.freedesktop.portal.Settings.ReadOne</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> org.freedesktop.appearance color-scheme</span></span></code></pre> <p>This should return <code>1</code> (dark) or <code>2</code> (light) depending on darkman’s current mode. If it returns <code>0</code> (“no preference”) or fails, your <code>portals.conf</code> isn’t being read — restart <code>xdg-desktop-portal.service</code> and check <code>XDG_CURRENT_DESKTOP</code> is set in your session environment.</p> <blockquote> <p><strong>Firefox-side counterpart:</strong> In <code>about:config</code>, also set <code>widget.use-xdg-desktop-portal.settings = 1</code>. Without both halves — system-side <code>portals.conf</code> AND Firefox-side preference — the bridge stays broken.</p> </blockquote> <h3 id="gtk-theme">GTK Theme</h3> <p><code>Dracula</code> is not in the official Arch repository. You will need an AUR helper like <code>yay</code> or <code>paru</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">yay</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> dracula-gtk-theme</span></span> <span class="giallo-l"><span style="color: #6A737D;"># or: paru -S dracula-gtk-theme</span></span></code></pre> <p>If you prefer not to use an AUR helper, the setup will automatically fall back to <code>Adwaita-dark</code> and <code>Adwaita</code> respectively (see hook script).</p> <h3 id="qt-control-for-phase-3">Qt Control (for Phase 3)</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> qt5ct qt6ct kvantum</span></span></code></pre><h3 id="i3-keybinding">i3 Keybinding</h3> <p>Add the following keybinding to your i3 configuration file <code>~/.config/i3/config</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>bindsym $mod+Shift+d exec --no-startup-id darkman toggle</span></span></code></pre><h2 id="step-2-create-directory-structure">Step 2: Create Directory Structure</h2> <p>A clean directory structure is crucial for maintainability:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.local/share/dark-mode.d</span></span> <span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.local/share/light-mode.d</span></span> <span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.config/themes/{dracula,solarized-light}</span></span> <span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.config/qt5ct/colors ~/.config/qt6ct/colors</span></span></code></pre> <p>In the <code>~/.config/themes/</code> directory, theme-specific files for each application will be stored. The hook scripts will then create symlinks to the currently desired theme files.</p> <h2 id="step-3-prepare-qt-apps-keepassxc-nheko">Step 3: Prepare Qt Apps (KeePassXC, nheko)</h2> <p>Qt applications do not automatically follow GTK configuration or the XDG-Portal. You must set the <code>QT_QPA_PLATFORMTHEME</code> environment variable in <strong><code>~/.xprofile</code></strong>, as this file is reliably read by i3 at startup.</p> <blockquote> <p><strong>Pragmatic starting point — begin with <code>qt5ct</code> alone:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F97583;">export</span><span> QT_QPA_PLATFORMTHEME</span><span style="color: #F97583;">=</span><span>qt5ct</span></span></code></pre> <p>This setting usually works most reliably in practice and often affects Qt6 applications via a compatibility path.</p> <p><strong>If Qt6 apps ignore theming</strong> (e.g., KeePassXC remains unstyled), you can escalate to the following configuration:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F97583;">export</span><span> QT_QPA_PLATFORMTHEME</span><span style="color: #F97583;">=</span><span>qt5ct:qt6ct</span></span></code></pre> <p>This combined syntax is officially supported from Qt 6.5, but its effectiveness can vary depending on the app’s build and Qt version. Only escalate if <code>qt5ct</code> alone is insufficient.</p> <p><strong>Note on path:</strong> <code>~/.config/environment.d/</code> would be the “more modern” way, but it’s read by <code>systemd --user</code> and doesn’t reliably reach the X process in every i3 session – especially not in <code>startx</code> setups without a display manager. <code>.xprofile</code> is the more robust choice for i3 + X11.</p> </blockquote> <h3 id="last-resort-fallback-per-app-wrapper">Last-resort fallback: per-app wrapper</h3> <p>If neither variable above gets a stubborn Qt6 app to pick up the theme, set the variable just for that one app:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span>QT_QPA_PLATFORMTHEME</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">qt6ct</span><span style="color: #B392F0;"> keepassxc</span></span></code></pre> <p>You can wrap this in a small shell script and place it in <code>~/.local/bin/</code>, or make a desktop file with the env-var prepended in <code>Exec=</code>. Inelegant, but reliable when the global escalation chain fails.</p> <h3 id="obtain-qt-color-schemes">Obtain Qt Color Schemes</h3> <p>Qt color schemes are stored as <code>.conf</code> files under <strong><code>~/.config/qt5ct/colors/</code></strong> and <strong><code>~/.config/qt6ct/colors/</code></strong>. Do not store them under <code>/usr/share/qt5ct/colors/</code>, as these directories are reserved for system defaults and can be overwritten by Pacman updates.</p> <p>For Dracula, an official Qt5ct color scheme exists in the Dracula project:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -fsSL</span><span style="color: #9ECBFF;"> https://raw.githubusercontent.com/dracula/qt5/master/Dracula.conf</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -o</span><span style="color: #9ECBFF;"> ~/.config/qt5ct/colors/Dracula.conf</span></span> <span class="giallo-l"><span style="color: #B392F0;">cp</span><span style="color: #9ECBFF;"> ~/.config/qt5ct/colors/Dracula.conf ~/.config/qt6ct/colors/Dracula.conf</span></span></code></pre> <p>For Solarized Light, <strong>no official Qt5ct color scheme exists</strong>. The most reliable approach is to create one once via the GUI:</p> <ol> <li>Run <code>qt5ct</code> from a terminal.</li> <li>Tab “Style” → next to “Color scheme” click “Edit color scheme” → “Create”.</li> <li>Set Window Background <code>#fdf6e3</code>, Window Text <code>#586e75</code>, Base <code>#fdf6e3</code>, Highlight <code>#268bd2</code>, etc. – the eight Solarized base values are documented at <a rel="noopener external" target="_blank" href="https://ethanschoonover.com/solarized">ethanschoonover.com/solarized</a>.</li> <li>Save as <code>SolarizedLight.conf</code> under <code>~/.config/qt5ct/colors/</code>.</li> <li>Copy the file to <code>~/.config/qt6ct/colors/SolarizedLight.conf</code>.</li> </ol> <blockquote> <p><strong>Why not use a third-party Solarized Qt scheme?</strong> Various community ports exist, but their quality and maintenance vary, and the <code>qt5ct</code> <code>.conf</code> format is fairly strict. A one-time GUI creation gives you a result that exactly matches your other Solarized apps, without surprises.</p> </blockquote> <h2 id="step-4-split-i3-config">Step 4: Split i3 Config</h2> <p>The i3 configuration cannot be recolored at runtime. You must switch it and reload.</p> <h3 id="option-a-include-file-recommended-from-i3-4-20">Option A: include file (recommended, from i3 4.20)</h3> <p>Add the following line to <code>~/.config/i3/config</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>include ~/.config/i3/theme.conf</span></span></code></pre> <p>Then create two theme-specific configuration files. Minimal working examples:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Dracula i3 theme</span></span> <span class="giallo-l"><span style="color: #B392F0;">cat</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> ~/.config/themes/dracula/i3-theme.conf</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;">&#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># class border bground text indicator child_border</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">client.focused #6272a4 #44475a #f8f8f2 #bd93f9 #6272a4</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">client.focused_inactive #44475a #44475a #f8f8f2 #44475a #44475a</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">client.unfocused #282a36 #282a36 #bfbfbf #282a36 #282a36</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">client.urgent #44475a #ff5555 #f8f8f2 #ff5555 #ff5555</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">client.placeholder #282a36 #282a36 #f8f8f2 #282a36 #282a36</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">client.background #282a36</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Solarized Light i3 theme</span></span> <span class="giallo-l"><span style="color: #B392F0;">cat</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> ~/.config/themes/solarized-light/i3-theme.conf</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;">&#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># class border bground text indicator child_border</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">client.focused #268bd2 #eee8d5 #586e75 #268bd2 #268bd2</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">client.focused_inactive #93a1a1 #eee8d5 #586e75 #93a1a1 #93a1a1</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">client.unfocused #fdf6e3 #fdf6e3 #93a1a1 #fdf6e3 #fdf6e3</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">client.urgent #93a1a1 #dc322f #fdf6e3 #dc322f #dc322f</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">client.placeholder #fdf6e3 #fdf6e3 #586e75 #fdf6e3 #fdf6e3</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">client.background #fdf6e3</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre> <p>The hook script will then symlink the correct file to <code>~/.config/i3/theme.conf</code> and execute <code>i3-msg reload</code>.</p> <h3 id="option-b-symlink-the-entire-config">Option B: Symlink the entire config</h3> <p>If you prefer not to use the <code>include</code> directive, you can symlink the entire i3 configuration file. This is less flexible but also works.</p> <h2 id="step-5-integrate-polybar">Step 5: Integrate Polybar</h2> <p>Polybar loads its configuration at startup. There are two ways to restart Polybar:</p> <h3 id="option-1-polybar-msg-cmd-restart-clean-from-polybar-3-6">Option 1: <code>polybar-msg cmd restart</code> (clean, from Polybar 3.6)</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">polybar-msg</span><span style="color: #9ECBFF;"> cmd restart</span></span></code></pre><h3 id="option-2-pkill-launch-script-universal">Option 2: <code>pkill</code> + Launch Script (universal)</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">pkill</span><span style="color: #9ECBFF;"> polybar</span></span> <span class="giallo-l"><span style="color: #B392F0;">sleep</span><span style="color: #79B8FF;"> 0.3</span></span> <span class="giallo-l"><span style="color: #F97583;">~</span><span>/.config/polybar/launch.sh</span></span></code></pre><h3 id="minimal-theme-files">Minimal theme files</h3> <p>You’ll already have a working <code>~/.config/polybar/config.ini</code> from your existing setup. The simplest approach is to extract just the colors into theme-specific files and <code>include-file</code> them. Minimal examples:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Dracula Polybar palette</span></span> <span class="giallo-l"><span style="color: #B392F0;">cat</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> ~/.config/themes/dracula/polybar.ini</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;">&#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">[colors]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">background = #282a36</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">background-alt = #44475a</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">foreground = #f8f8f2</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">foreground-alt = #6272a4</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">primary = #bd93f9</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">secondary = #8be9fd</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">alert = #ff5555</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">disabled = #6272a4</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Solarized Light Polybar palette</span></span> <span class="giallo-l"><span style="color: #B392F0;">cat</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> ~/.config/themes/solarized-light/polybar.ini</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;">&#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">[colors]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">background = #fdf6e3</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">background-alt = #eee8d5</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">foreground = #586e75</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">foreground-alt = #93a1a1</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">primary = #268bd2</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">secondary = #2aa198</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">alert = #dc322f</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">disabled = #93a1a1</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre> <p>In your main Polybar config, reference the colors via <code>include-file = ~/.config/polybar/colors.ini</code>, and let the hook script symlink <code>colors.ini</code> to one of the two palette files. (If your existing config keeps colors and bar layout in a single file, store two complete copies in <code>~/.config/themes/&lt;theme&gt;/polybar.ini</code> and let the hook symlink the whole <code>config.ini</code> instead — both approaches work.)</p> <h2 id="step-6-chromium-flags">Step 6: Chromium Flags</h2> <p>Chromium does not react to theme changes at runtime. It’s important to <strong>clearly separate</strong> two things:</p> <ul> <li><strong>UI-Dark-Mode:</strong> Affects the browser interface (toolbar, tabs, menus).</li> <li><strong>Webpage-Force-Dark:</strong> Forces a dark mode for every webpage. However, this can distort images, diagrams, and carefully designed pages.</li> </ul> <h3 id="recommended-ui-dark-mode-only">Recommended: UI-Dark-Mode only</h3> <p>Create the file <code>~/.config/chromium-flags.conf</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>--force-dark-mode</span></span> <span class="giallo-l"><span>--gtk-version=4</span></span></code></pre> <p><code>--gtk-version=4</code> ensures that Chromium respects the current GTK4 theme and colors its toolbar to match other GTK applications.</p> <h3 id="optional-additionally-force-dark-content-for-webpages">Optional: Additionally force dark content for webpages</h3> <p>If you want to force dark mode for webpage content as well, add:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>--enable-features=WebContentsForceDark</span></span></code></pre> <blockquote> <p><strong>Warning:</strong> This flag name has changed multiple times across Chromium versions (<code>WebContentsForceDark</code>, <code>ForceWebContentsDarkMode</code>, or only via <code>chrome://flags</code>). If it doesn’t work, check <code>chrome://flags</code> for “Force Dark Mode for Web Contents” and enable it there. The recommendation remains: only enable if you’re comfortable with potential content distortion.</p> </blockquote> <p>A true live toggle is not practical here without a browser restart.</p> <h2 id="step-7-the-dark-mode-hook-script">Step 7: The Dark-Mode Hook Script</h2> <p>This script will be executed when <code>darkman</code> switches to dark mode. Create the file <code>~/.local/share/dark-mode.d/apply-theme</code>:</p> <blockquote> <p><strong>A note on hook directory layout:</strong> This guide uses <code>~/.local/share/dark-mode.d/</code> and <code>~/.local/share/light-mode.d/</code>, which the <code>darkman(1)</code> manpage describes as the <em>legacy</em> format (kept for backwards compatibility). The current format is a single <code>~/.local/share/darkman/</code> directory with one script that receives the mode as <code>$1</code>. Both formats work; the split-directory layout is used here because it makes the dark and light scripts easy to read side-by-side. If you want the modern single-script style, consolidate the two scripts and branch on <code>case "$1" in dark|light) ... esac</code>.</p> </blockquote> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;">#!/usr/bin/env bash</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Robustness: undefined vars are errors, but individual app errors</span></span> <span class="giallo-l"><span style="color: #6A737D;"># should not abort the entire hook.</span></span> <span class="giallo-l"><span style="color: #79B8FF;">set -u</span></span> <span class="giallo-l"><span style="color: #79B8FF;">trap</span><span style="color: #9ECBFF;"> &#39;echo &quot;Hook error in: $BASH_COMMAND&quot; &gt;&amp;2&#39; ERR</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>THEME_DIR</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;</span><span>$HOME</span><span style="color: #9ECBFF;">/.config/themes/dracula&quot;</span></span> <span class="giallo-l"><span>GTK_THEME</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;Dracula&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Fallback if dracula-gtk-theme is not installed</span></span> <span class="giallo-l"><span style="color: #F97583;">if !</span><span> [[</span><span style="color: #F97583;"> -d</span><span> /usr/share/themes/Dracula </span><span style="color: #F97583;">|| -d ~</span><span>/.themes/Dracula ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span> GTK_THEME</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;Adwaita-dark&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── GTK 3 / GTK 4 ──────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.config/gtk-3.0 ~/.config/gtk-4.0</span></span> <span class="giallo-l"><span style="color: #B392F0;">cat</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> ~/.config/gtk-3.0/settings.ini</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;">EOF</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">[Settings]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">gtk-theme-name=</span><span>$GTK_THEME</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">gtk-icon-theme-name=Adwaita</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">gtk-application-prefer-dark-theme=1</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span> <span class="giallo-l"><span style="color: #B392F0;">cp</span><span style="color: #9ECBFF;"> ~/.config/gtk-3.0/settings.ini ~/.config/gtk-4.0/settings.ini</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Also via gsettings (for apps that read this)</span></span> <span class="giallo-l"><span style="color: #B392F0;">gsettings</span><span style="color: #9ECBFF;"> set org.gnome.desktop.interface gtk-theme &quot;</span><span>$GTK_THEME</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #B392F0;">gsettings</span><span style="color: #9ECBFF;"> set org.gnome.desktop.interface color-scheme &#39;prefer-dark&#39;</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── Qt5 / Qt6 ──────────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Redirect ColorScheme path in qt5ct/qt6ct — user config, not /usr/share!</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -f ~</span><span>/.config/qt5ct/qt5ct.conf ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> sed</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> &quot;s|^color_scheme_path=.*|color_scheme_path=</span><span>$HOME</span><span style="color: #9ECBFF;">/.config/qt5ct/colors/Dracula.conf|&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ~/.config/qt5ct/qt5ct.conf</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -f ~</span><span>/.config/qt6ct/qt6ct.conf ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> sed</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> &quot;s|^color_scheme_path=.*|color_scheme_path=</span><span>$HOME</span><span style="color: #9ECBFF;">/.config/qt6ct/colors/Dracula.conf|&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ~/.config/qt6ct/qt6ct.conf</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── Xresources / urxvt ─────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">ln</span><span style="color: #79B8FF;"> -sf</span><span style="color: #9ECBFF;"> &quot;</span><span>$THEME_DIR</span><span style="color: #9ECBFF;">/Xresources&quot; ~/.Xresources</span></span> <span class="giallo-l"><span style="color: #B392F0;">xrdb</span><span style="color: #79B8FF;"> -merge</span><span style="color: #9ECBFF;"> ~/.Xresources</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Recolor running urxvt instances via escape sequences (best effort).</span></span> <span class="giallo-l"><span style="color: #6A737D;"># -O tests if the executing user is the owner of the PTS — protects in</span></span> <span class="giallo-l"><span style="color: #6A737D;"># multi-user/SSH setups from writing to foreign terminals.</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Note: These sequences only change Background/Foreground, not ANSI colors.</span></span> <span class="giallo-l"><span style="color: #F97583;">for</span><span> pts</span><span style="color: #F97583;"> in</span><span style="color: #9ECBFF;"> /dev/pts/[0-9</span><span>]</span><span style="color: #F97583;">*</span><span>;</span><span style="color: #F97583;"> do</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #F97583;"> -O</span><span style="color: #9ECBFF;"> &quot;</span><span>$pts</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &amp;&amp; -w</span><span style="color: #9ECBFF;"> &quot;</span><span>$pts</span><span style="color: #9ECBFF;">&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> printf</span><span style="color: #9ECBFF;"> &#39;\033]708;#282a36\007\033]11;#282a36\007\033]10;#f8f8f2\007&#39;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> &quot;</span><span>$pts</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;">done</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── Alacritty ──────────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">ln</span><span style="color: #79B8FF;"> -sf</span><span style="color: #9ECBFF;"> &quot;</span><span>$THEME_DIR</span><span style="color: #9ECBFF;">/alacritty.toml&quot; ~/.config/alacritty/theme.toml</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Alacritty reloads automatically with live_config_reload=true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── i3 Theme ───────────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">ln</span><span style="color: #79B8FF;"> -sf</span><span style="color: #9ECBFF;"> &quot;</span><span>$THEME_DIR</span><span style="color: #9ECBFF;">/i3-theme.conf&quot; ~/.config/i3/theme.conf</span></span> <span class="giallo-l"><span style="color: #B392F0;">i3-msg</span><span style="color: #9ECBFF;"> reload</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;">/dev/null</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── Polybar ────────────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">ln</span><span style="color: #79B8FF;"> -sf</span><span style="color: #9ECBFF;"> &quot;</span><span>$THEME_DIR</span><span style="color: #9ECBFF;">/polybar.ini&quot; ~/.config/polybar/config.ini</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span style="color: #79B8FF;"> command -v</span><span style="color: #9ECBFF;"> polybar-msg</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> 2&gt;&amp;1</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> polybar-msg</span><span style="color: #9ECBFF;"> cmd restart</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> 2&gt;&amp;1 ||</span><span> {</span></span> <span class="giallo-l"><span style="color: #B392F0;"> pkill</span><span style="color: #9ECBFF;"> polybar</span><span>;</span><span style="color: #B392F0;"> sleep</span><span style="color: #79B8FF;"> 0.3</span><span>;</span><span style="color: #B392F0;"> ~/.config/polybar/launch.sh</span><span> &amp;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> pkill</span><span style="color: #9ECBFF;"> polybar</span><span>;</span><span style="color: #B392F0;"> sleep</span><span style="color: #79B8FF;"> 0.3</span><span>;</span><span style="color: #B392F0;"> ~/.config/polybar/launch.sh</span><span> &amp;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── neomutt ────────────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">ln</span><span style="color: #79B8FF;"> -sf</span><span style="color: #9ECBFF;"> &quot;</span><span>$THEME_DIR</span><span style="color: #9ECBFF;">/neomutt-colors&quot; ~/.config/neomutt/colors</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Running neomutt instances require :source ~/.config/neomutt/colors</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── VSCodium ───────────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Patch settings.json. VSCodium usually reacts live via file watcher,</span></span> <span class="giallo-l"><span style="color: #6A737D;"># in rare cases a &quot;Reload Window&quot; (Ctrl+Shift+P) is needed.</span></span> <span class="giallo-l"><span>SETTINGS</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;</span><span>$HOME</span><span style="color: #9ECBFF;">/.config/VSCodium/User/settings.json&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -f</span><span style="color: #9ECBFF;"> &quot;</span><span>$SETTINGS</span><span style="color: #9ECBFF;">&quot;</span><span> ]] &amp;&amp;</span><span style="color: #79B8FF;"> command -v</span><span style="color: #9ECBFF;"> jq</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> 2&gt;&amp;1</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span> tmp</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">mktemp</span><span>)</span></span> <span class="giallo-l"><span style="color: #B392F0;"> jq</span><span style="color: #9ECBFF;"> &#39;.&quot;workbench.colorTheme&quot; = &quot;Dracula&quot;&#39; &quot;</span><span>$SETTINGS</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> &quot;</span><span>$tmp</span><span style="color: #9ECBFF;">&quot;</span><span> &amp;&amp;</span><span style="color: #B392F0;"> mv</span><span style="color: #9ECBFF;"> &quot;</span><span>$tmp</span><span style="color: #9ECBFF;">&quot; &quot;</span><span>$SETTINGS</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── Vim/Neovim (if used) ───────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">ln</span><span style="color: #79B8FF;"> -sf</span><span style="color: #9ECBFF;"> &quot;</span><span>$THEME_DIR</span><span style="color: #9ECBFF;">/nvim-colorscheme.vim&quot; ~/.config/nvim/colorscheme.vim</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── Firefox / Thunderbird ──────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Nothing to do — they follow darkman&#39;s XDG-Portal automatically.</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Prerequisite: in about:config widget.use-xdg-desktop-portal.settings = 1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── Chromium ───────────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Does not react live; flags in ~/.config/chromium-flags.conf take effect</span></span> <span class="giallo-l"><span style="color: #6A737D;"># on next start. See Step 6.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── User Notification ──────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">notify-send</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> weather-clear-night &quot;Theme&quot; &quot;Dark Mode activated (Dracula)&quot;</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;Dark mode activated (Dracula)&quot;</span></span></code></pre> <p>Make the script executable:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">chmod</span><span style="color: #9ECBFF;"> +x ~/.local/share/dark-mode.d/apply-theme</span></span></code></pre><h2 id="step-8-the-light-mode-hook-script">Step 8: The Light-Mode Hook Script</h2> <p>This script will be executed when <code>darkman</code> switches to light mode. Create the file <code>~/.local/share/light-mode.d/apply-theme</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;">#!/usr/bin/env bash</span></span> <span class="giallo-l"><span style="color: #79B8FF;">set -u</span></span> <span class="giallo-l"><span style="color: #79B8FF;">trap</span><span style="color: #9ECBFF;"> &#39;echo &quot;Hook error in: $BASH_COMMAND&quot; &gt;&amp;2&#39; ERR</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>THEME_DIR</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;</span><span>$HOME</span><span style="color: #9ECBFF;">/.config/themes/solarized-light&quot;</span></span> <span class="giallo-l"><span>GTK_THEME</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;Adwaita&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── GTK 3 / GTK 4 ──────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.config/gtk-3.0 ~/.config/gtk-4.0</span></span> <span class="giallo-l"><span style="color: #B392F0;">cat</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> ~/.config/gtk-3.0/settings.ini</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;">EOF</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">[Settings]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">gtk-theme-name=</span><span>$GTK_THEME</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">gtk-icon-theme-name=Adwaita</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">gtk-application-prefer-dark-theme=0</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span> <span class="giallo-l"><span style="color: #B392F0;">cp</span><span style="color: #9ECBFF;"> ~/.config/gtk-3.0/settings.ini ~/.config/gtk-4.0/settings.ini</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">gsettings</span><span style="color: #9ECBFF;"> set org.gnome.desktop.interface gtk-theme &quot;</span><span>$GTK_THEME</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #B392F0;">gsettings</span><span style="color: #9ECBFF;"> set org.gnome.desktop.interface color-scheme &#39;prefer-light&#39;</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── Qt5 / Qt6 ──────────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -f ~</span><span>/.config/qt5ct/qt5ct.conf ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> sed</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> &quot;s|^color_scheme_path=.*|color_scheme_path=</span><span>$HOME</span><span style="color: #9ECBFF;">/.config/qt5ct/colors/SolarizedLight.conf|&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ~/.config/qt5ct/qt5ct.conf</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -f ~</span><span>/.config/qt6ct/qt6ct.conf ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> sed</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> &quot;s|^color_scheme_path=.*|color_scheme_path=</span><span>$HOME</span><span style="color: #9ECBFF;">/.config/qt6ct/colors/SolarizedLight.conf|&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ~/.config/qt6ct/qt6ct.conf</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── Xresources / urxvt ─────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">ln</span><span style="color: #79B8FF;"> -sf</span><span style="color: #9ECBFF;"> &quot;</span><span>$THEME_DIR</span><span style="color: #9ECBFF;">/Xresources&quot; ~/.Xresources</span></span> <span class="giallo-l"><span style="color: #B392F0;">xrdb</span><span style="color: #79B8FF;"> -merge</span><span style="color: #9ECBFF;"> ~/.Xresources</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">for</span><span> pts</span><span style="color: #F97583;"> in</span><span style="color: #9ECBFF;"> /dev/pts/[0-9</span><span>]</span><span style="color: #F97583;">*</span><span>;</span><span style="color: #F97583;"> do</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #F97583;"> -O</span><span style="color: #9ECBFF;"> &quot;</span><span>$pts</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &amp;&amp; -w</span><span style="color: #9ECBFF;"> &quot;</span><span>$pts</span><span style="color: #9ECBFF;">&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> printf</span><span style="color: #9ECBFF;"> &#39;\033]708;#fdf6e3\007\033]11;#fdf6e3\007\033]10;#586e75\007&#39;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> &quot;</span><span>$pts</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;">done</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── Alacritty ──────────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">ln</span><span style="color: #79B8FF;"> -sf</span><span style="color: #9ECBFF;"> &quot;</span><span>$THEME_DIR</span><span style="color: #9ECBFF;">/alacritty.toml&quot; ~/.config/alacritty/theme.toml</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── i3 ─────────────────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">ln</span><span style="color: #79B8FF;"> -sf</span><span style="color: #9ECBFF;"> &quot;</span><span>$THEME_DIR</span><span style="color: #9ECBFF;">/i3-theme.conf&quot; ~/.config/i3/theme.conf</span></span> <span class="giallo-l"><span style="color: #B392F0;">i3-msg</span><span style="color: #9ECBFF;"> reload</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;">/dev/null</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── Polybar ────────────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">ln</span><span style="color: #79B8FF;"> -sf</span><span style="color: #9ECBFF;"> &quot;</span><span>$THEME_DIR</span><span style="color: #9ECBFF;">/polybar.ini&quot; ~/.config/polybar/config.ini</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span style="color: #79B8FF;"> command -v</span><span style="color: #9ECBFF;"> polybar-msg</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> 2&gt;&amp;1</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> polybar-msg</span><span style="color: #9ECBFF;"> cmd restart</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> 2&gt;&amp;1 ||</span><span> {</span></span> <span class="giallo-l"><span style="color: #B392F0;"> pkill</span><span style="color: #9ECBFF;"> polybar</span><span>;</span><span style="color: #B392F0;"> sleep</span><span style="color: #79B8FF;"> 0.3</span><span>;</span><span style="color: #B392F0;"> ~/.config/polybar/launch.sh</span><span> &amp;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> pkill</span><span style="color: #9ECBFF;"> polybar</span><span>;</span><span style="color: #B392F0;"> sleep</span><span style="color: #79B8FF;"> 0.3</span><span>;</span><span style="color: #B392F0;"> ~/.config/polybar/launch.sh</span><span> &amp;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── neomutt ────────────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">ln</span><span style="color: #79B8FF;"> -sf</span><span style="color: #9ECBFF;"> &quot;</span><span>$THEME_DIR</span><span style="color: #9ECBFF;">/neomutt-colors&quot; ~/.config/neomutt/colors</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── VSCodium ───────────────────────────────────────────────────</span></span> <span class="giallo-l"><span>SETTINGS</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;</span><span>$HOME</span><span style="color: #9ECBFF;">/.config/VSCodium/User/settings.json&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -f</span><span style="color: #9ECBFF;"> &quot;</span><span>$SETTINGS</span><span style="color: #9ECBFF;">&quot;</span><span> ]] &amp;&amp;</span><span style="color: #79B8FF;"> command -v</span><span style="color: #9ECBFF;"> jq</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> 2&gt;&amp;1</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span> tmp</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">mktemp</span><span>)</span></span> <span class="giallo-l"><span style="color: #B392F0;"> jq</span><span style="color: #9ECBFF;"> &#39;.&quot;workbench.colorTheme&quot; = &quot;Solarized Light&quot;&#39; &quot;</span><span>$SETTINGS</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> &quot;</span><span>$tmp</span><span style="color: #9ECBFF;">&quot;</span><span> &amp;&amp;</span><span style="color: #B392F0;"> mv</span><span style="color: #9ECBFF;"> &quot;</span><span>$tmp</span><span style="color: #9ECBFF;">&quot; &quot;</span><span>$SETTINGS</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── Neovim ─────────────────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">ln</span><span style="color: #79B8FF;"> -sf</span><span style="color: #9ECBFF;"> &quot;</span><span>$THEME_DIR</span><span style="color: #9ECBFF;">/nvim-colorscheme.vim&quot; ~/.config/nvim/colorscheme.vim</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ─── User Notification ──────────────────────────────────────────</span></span> <span class="giallo-l"><span style="color: #B392F0;">notify-send</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> weather-clear &quot;Theme&quot; &quot;Light Mode activated (Solarized Light)&quot;</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;Light mode activated (Solarized Light)&quot;</span></span></code></pre> <p>Make the script executable:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">chmod</span><span style="color: #9ECBFF;"> +x ~/.local/share/light-mode.d/apply-theme</span></span></code></pre><h2 id="step-9-initial-state-and-persistence-on-login">Step 9: Initial State and Persistence on Login</h2> <p><code>darkman</code> is designed as a user service that <strong>persists its own state</strong>. The service typically remembers the last mode after a restart and executes the corresponding hooks at startup.</p> <blockquote> <p><strong>Important — no hardcoded <code>darkman set</code> calls in <code>.xprofile</code>!</strong> It might be tempting to write <code>darkman set dark</code> in <code>.xprofile</code> to “always start with Dark mode.” However, this is counterproductive:</p> <ul> <li>It overwrites the last manual toggle on every login.</li> <li>It <strong>completely disables auto-switching based on sunrise/sunset</strong>, if you enable it later.</li> </ul> <p>Just let the service run.</p> </blockquote> <h3 id="reality-check-verify-persistence">Reality Check: Verify Persistence</h3> <p>In practice, reliable persistence depends on the interplay between the user service, login manager, and XDG state directory. <strong>Do not blindly trust it – check it after the first login cycle</strong>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># What does darkman currently think?</span></span> <span class="giallo-l"><span style="color: #B392F0;">darkman</span><span style="color: #9ECBFF;"> get</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Was the service started cleanly at login and did it trigger hooks?</span></span> <span class="giallo-l"><span style="color: #B392F0;">journalctl</span><span style="color: #79B8FF;"> --user -u</span><span style="color: #9ECBFF;"> darkman.service</span><span style="color: #79B8FF;"> -b</span></span></code></pre> <p>If <code>darkman get</code> returns a different mode than expected, or if the hook scripts were not executed at login, you have a persistence problem (see next section).</p> <h3 id="if-persistence-is-unreliable">If Persistence is Unreliable</h3> <p>Some possible countermeasures:</p> <ul> <li>Ensure <code>darkman.service</code> is truly enabled: <code>systemctl --user is-enabled darkman.service</code></li> <li>In rare setups (TTY login + <code>startx</code>, no display manager), it helps to set <code>dbus-update-activation-environment --systemd DISPLAY XAUTHORITY</code> in <code>.xprofile</code> so that user services can see the X session.</li> <li>Workaround: In <code>.xprofile</code>, call <strong><code>darkman get</code></strong> once and only set a fallback mode if it’s empty. However, this is a hack – it’s better to address the root cause of the problem.</li> </ul> <h3 id="optional-auto-switching-based-on-sunrise-sunset">Optional: Auto-Switching Based on Sunrise/Sunset</h3> <p>If <code>darkman</code> should automatically switch based on time of day, create the file <code>~/.config/darkman/config.yaml</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #85E89D;">lat</span><span>:</span><span style="color: #79B8FF;"> 48.2082</span></span> <span class="giallo-l"><span style="color: #85E89D;">lng</span><span>:</span><span style="color: #79B8FF;"> 16.3738</span></span> <span class="giallo-l"><span style="color: #85E89D;">usegeoclue</span><span>:</span><span style="color: #79B8FF;"> false</span></span></code></pre> <p>(The coordinates provided here are for Vienna – adjust them to your location.)</p> <p>The service calculates sunrise and sunset times from this and automatically triggers the hooks.</p> <h3 id="if-you-really-need-a-default-value-on-the-very-first-start">If you really need a default value on the very first start</h3> <p>If you’ve just installed <code>darkman</code> and want a defined initial state for the very first toggle, perform this <strong>manually once</strong> in the shell:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">darkman</span><span style="color: #9ECBFF;"> set dark</span></span></code></pre> <p>— not in <code>.xprofile</code>. From the next login onwards, the service will remember.</p> <h2 id="step-10-obtain-theme-files">Step 10: Obtain Theme Files</h2> <p>For each application, place a dark and a light variant in <code>~/.config/themes/&lt;theme&gt;/</code>. The following commands cover most cases. You can paste these directly:</p> <h3 id="alacritty">Alacritty</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -fsSL</span><span style="color: #9ECBFF;"> https://raw.githubusercontent.com/dracula/alacritty/master/dracula.toml</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -o</span><span style="color: #9ECBFF;"> ~/.config/themes/dracula/alacritty.toml</span></span> <span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -fsSL</span><span style="color: #9ECBFF;"> https://raw.githubusercontent.com/alacritty/alacritty-theme/master/themes/solarized_light.toml</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -o</span><span style="color: #9ECBFF;"> ~/.config/themes/solarized-light/alacritty.toml</span></span></code></pre> <p>In your main <code>~/.config/alacritty/alacritty.toml</code>, import the symlink the hook will manage and confirm live-reload is on. Live-reload defaults to enabled in current Alacritty versions, but being explicit avoids confusion if a future upstream change flips the default:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="toml"><span class="giallo-l"><span>import = [</span><span style="color: #9ECBFF;">&quot;~/.config/alacritty/theme.toml&quot;</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>[</span><span style="color: #B392F0;">general</span><span>]</span></span> <span class="giallo-l"><span>live_config_reload =</span><span style="color: #79B8FF;"> true</span><span style="color: #6A737D;"> # default; explicit for clarity</span></span></code></pre> <blockquote> <p><strong>TOML note:</strong> Pre-0.13 Alacritty used a top-level <code>live_config_reload = true</code>. From 0.13 onward, it lives under <code>[general]</code>. If your Alacritty is older, drop the <code>[general]</code> table.</p> </blockquote> <h3 id="xresources-urxvt">Xresources / urxvt</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Dracula</span></span> <span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -fsSL</span><span style="color: #9ECBFF;"> https://raw.githubusercontent.com/dracula/xresources/master/Xresources</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -o</span><span style="color: #9ECBFF;"> ~/.config/themes/dracula/Xresources</span></span></code></pre> <p>For Solarized Light, the upstream <code>solarized/xresources</code> file uses C preprocessor <code>#define</code> statements. Many display managers and login flows invoke <code>xrdb</code> with <code>-nocpp</code>, which silently strips these defines and leaves you with default colors. To avoid this entirely, write a flat (preprocessor-free) version directly:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">cat</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> ~/.config/themes/solarized-light/Xresources</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;">&#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">! Solarized Light — flat, no #define preprocessing required</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*background: #fdf6e3</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*foreground: #657b83</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*fadeColor: #fdf6e3</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*cursorColor: #586e75</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*pointerColorBackground:#93a1a1</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*pointerColorForeground:#586e75</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">! black</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color0: #073642</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color8: #002b36</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">! red</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color1: #dc322f</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color9: #cb4b16</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">! green</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color2: #859900</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color10: #586e75</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">! yellow</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color3: #b58900</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color11: #657b83</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">! blue</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color4: #268bd2</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color12: #839496</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">! magenta</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color5: #d33682</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color13: #6c71c4</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">! cyan</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color6: #2aa198</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color14: #93a1a1</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">! white</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color7: #eee8d5</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">*color15: #fdf6e3</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre> <p>The values above are taken from the canonical Solarized palette and match the structure of the upstream file with the <code>#define</code>s already resolved.</p> <h3 id="polybar">Polybar</h3> <p>See <a href="https://criticalbasics.xyz/posts/i3-dark-light-mode-switcher/#step-5-integrate-polybar">Step 5</a> — minimal Dracula and Solarized Light palettes are inlined there. Copy them into <code>~/.config/themes/&lt;theme&gt;/polybar.ini</code> if you haven’t already.</p> <h3 id="neomutt">neomutt</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Dracula</span></span> <span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.config/themes/dracula</span></span> <span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -fsSL</span><span style="color: #9ECBFF;"> https://raw.githubusercontent.com/dracula/mutt/master/dracula.muttrc</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -o</span><span style="color: #9ECBFF;"> ~/.config/themes/dracula/neomutt-colors</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Solarized Light (16-color version recommended for terminal accuracy)</span></span> <span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -fsSL</span><span style="color: #9ECBFF;"> https://raw.githubusercontent.com/altercation/mutt-colors-solarized/master/mutt-colors-solarized-light-16.muttrc</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -o</span><span style="color: #9ECBFF;"> ~/.config/themes/solarized-light/neomutt-colors</span></span></code></pre><h3 id="vscodium">VSCodium</h3> <p>VSCodium (like VS Code) ships with <strong>Solarized Light</strong> and <strong>Solarized Dark</strong> as built-in themes — no extension required. Dracula, however, must be installed separately:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">codium</span><span style="color: #79B8FF;"> --install-extension</span><span style="color: #9ECBFF;"> dracula-theme.theme-dracula</span></span></code></pre> <p>The hook scripts already set the correct theme name via <code>jq</code>. If your VSCodium uses a different binary name (e.g., <code>vscodium</code>), adjust the command accordingly.</p> <h3 id="gtk-and-qt">GTK and Qt</h3> <p>GTK Dracula via AUR (<code>yay -S dracula-gtk-theme</code>); Adwaita is shipped by default. Qt color schemes: see <a href="https://criticalbasics.xyz/posts/i3-dark-light-mode-switcher/#step-3-prepare-qt-apps-keepassxc-nheko">Step 3</a>.</p> <h3 id="reference-table">Reference table</h3> <table><thead><tr><th>App</th><th>File</th><th>Source</th></tr></thead><tbody> <tr><td>GTK</td><td>Theme via AUR/Pacman</td><td><code>dracula-gtk-theme</code>, Adwaita is default</td></tr> <tr><td>Xresources/urxvt</td><td><code>Xresources</code></td><td><code>dracula/xresources</code>, <code>solarized/xresources</code></td></tr> <tr><td>Alacritty</td><td><code>alacritty.toml</code></td><td><code>dracula/alacritty</code>, <code>alacritty/alacritty-theme</code></td></tr> <tr><td>i3</td><td><code>i3-theme.conf</code></td><td>inlined examples in Step 4</td></tr> <tr><td>Polybar</td><td><code>polybar.ini</code></td><td>inlined examples in Step 5</td></tr> <tr><td>neomutt</td><td><code>neomutt-colors</code></td><td><code>dracula/mutt</code>, <code>altercation/mutt-colors-solarized</code></td></tr> <tr><td>VSCodium</td><td>built-in / Extension</td><td>Solarized built-in, “Dracula Official” via marketplace</td></tr> <tr><td>qt5ct/qt6ct</td><td><code>*.conf</code></td><td><code>dracula/qt5</code>, Solarized via qt5ct GUI</td></tr> </tbody></table> <p>You can find Dracula themes collected at <a rel="noopener external" target="_blank" href="https://draculatheme.com">https://draculatheme.com</a> – Solarized at <a rel="noopener external" target="_blank" href="https://ethanschoonover.com/solarized">https://ethanschoonover.com/solarized</a>.</p> <h2 id="caveats-and-honest-expectations">Caveats and Honest Expectations</h2> <p>What <strong>switches live</strong> (without restart):</p> <ul> <li>GTK apps via gsettings/portal: Thunar, Firefox, Thunderbird (with Portal setting)</li> <li>Alacritty (with <code>live_config_reload = true</code>)</li> <li>i3 (after <code>reload</code>)</li> <li>Polybar (after restart)</li> <li>VSCodium (mostly, via file watcher on settings.json)</li> </ul> <p>What <strong>requires an app restart</strong>:</p> <ul> <li>KeePassXC, nheko (Qt apps do not react live)</li> <li>GIMP, LibreOffice (own theme logic)</li> <li>urxvt terminals (except with escape sequence trick, which only affects Background/Foreground, not ANSI colors)</li> <li>neomutt (or <code>:source</code> within the session)</li> <li>Chromium (flags file takes effect on start)</li> </ul> <p>What <strong>needs to be configured manually</strong> within the app:</p> <ul> <li>LibreOffice: set Light/Dark once in <code>Tools → Options → Application Colors</code></li> <li>GIMP: has its own theme system under <code>Preferences → Theme</code></li> <li>Inkscape: follows GTK, but restart required</li> </ul> <h2 id="tips">Tips</h2> <ul> <li><strong>Geo-based Auto-Switching:</strong> <code>darkman</code> can do this automatically based on sunrise/sunset – see Step 9.</li> <li><strong>Debugging:</strong> <code>journalctl --user -u darkman.service -f</code> shows if hooks are being executed.</li> <li><strong>Manual Hook Testing:</strong> Execute <code>~/.local/share/dark-mode.d/apply-theme</code> directly to see errors in isolation.</li> <li><strong>Consistency Across Multiple Machines:</strong> Version <code>~/.config/themes/</code>, <code>~/.local/share/dark-mode.d/</code>, <code>~/.local/share/light-mode.d/</code>, and <code>~/.config/qt5ct/colors/</code> in your dotfiles repository.</li> <li><strong>Forced KeePassXC Reload (optional, usually undesirable):</strong> If you absolutely need the KeePassXC theme to update at the moment of switching, you can include <code>pkill keepassxc</code> in the hook – but remember that this will lose all unsaved changes and the open database. Realistically: just let it switch on the next start.</li> </ul> <h2 id="extension-ideas">Extension Ideas</h2> <ul> <li><strong>base16-Framework</strong> instead of Dracula/Solarized: Generate a unified scheme for hundreds of apps from a single palette (<a rel="noopener external" target="_blank" href="https://github.com/chriskempson/base16">https://github.com/chriskempson/base16</a>).</li> <li><strong>Per-Workspace-Themes</strong>: Theoretically possible via i3-IPC, but rarely practical.</li> <li><strong>Polybar Module</strong> with current theme status as an indicator.</li> </ul> <h2 id="summary">Summary</h2> <p>The implemented architecture is:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>darkman (Trigger + Portal + Persistence)</span></span> <span class="giallo-l"><span> ├── Hooks → GTK, Qt, Xresources, App Configs</span></span> <span class="giallo-l"><span> ├── Live-Reload: i3, Polybar, Alacritty, GTK Apps via Portal, VSCodium</span></span> <span class="giallo-l"><span> └── Accepted: Some apps require restart</span></span></code></pre> <p>You switch with <code>$mod+Shift+d</code>. Most apps react immediately, some require a restart – this is the current state of Linux desktop reality, not a flaw in your setup.</p> <p>When setting up for the first time, it’s worthwhile to follow the phased strategy from the beginning of the tutorial: first the basics (GTK, Firefox, i3, Alacritty), then extensions, and finally the “problem children.” This way, you can more easily identify the cause of problems if they arise.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;wiki.archlinux.org&#x2F;title&#x2F;Dark_mode_theme_switching" class="retro-button"> <span class="emoji">📚</span><span class="button-text">ARCH WIKI: DARK MODE THEME SWITCHING</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;mwh&#x2F;darkman" class="retro-button"> <span class="emoji">💻</span><span class="button-text">DARKMAN PROJECT ON GITHUB</span> </a> </p> Server Security Audit Script for Debian/Ubuntu Mon, 04 May 2026 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/server-security-audit-script/ https://criticalbasics.xyz/posts/server-security-audit-script/ <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2026-05-04</td><td><strong>Initial Version:</strong> Full audit script with comprehensive explanations.</td></tr> </tbody></table> </div> <hr /> <h2 id="introduction-to-the-server-security-audit-script">Introduction to the Server Security Audit Script</h2> <p>When you provision a new server, especially in a cloud environment using tools like cloud-init, it’s crucial to verify that all intended security measures have been correctly applied. Manual checks can be time-consuming and error-prone. This Bash script automates a significant portion of this auditing process, providing a quick overview of your server’s security posture on Debian or Ubuntu-based systems.</p> <p>This script is designed to be run with root privileges and will:</p> <ul> <li><strong>Check System Fundamentals:</strong> Hostname, timezone, kernel, pending updates, and reboot status.</li> <li><strong>Audit User &amp; Authentication:</strong> Verify the existence and <code>sudo</code> privileges of a dedicated admin user, check root password status, and identify accounts with UID 0 or empty passwords.</li> <li><strong>Harden SSH:</strong> Scrutinize your SSH daemon’s configuration for best practices like disabled root login, password authentication, X11 forwarding, and the use of strong key algorithms. It also checks for the presence of SSH keys for your admin user.</li> <li><strong>Firewall Configuration (UFW):</strong> Confirm UFW’s active status, default policies, specific rule sets (e.g., rate-limiting for SSH), and log redirection.</li> <li><strong>Intrusion Prevention (Fail2Ban):</strong> Validate that Fail2Ban is running, its SSH jail is active, and it’s monitoring the correct SSH port.</li> <li><strong>Automated Updates:</strong> Ensure <code>unattended-upgrades</code> is installed and configured to keep your system patched.</li> <li><strong>Docker Security:</strong> If Docker is installed, it checks daemon status, Docker Compose presence, user group membership, and critically, Docker’s log rotation settings and network configuration.</li> <li><strong>Log Rotation:</strong> Verify persistent journaling and <code>logrotate</code> configurations for Traefik and UFW logs.</li> <li><strong>Network &amp; Open Ports:</strong> List actively listening ports and check for known insecure legacy services.</li> <li><strong>Filesystem Security:</strong> Scan for world-writable files in critical directories and report disk usage.</li> </ul> <p>At the end, it provides a summary of <code>PASS</code>, <code>WARN</code>, and <code>FAIL</code> counts, giving you an immediate understanding of areas needing attention.</p> <p><strong>Why is this important?</strong> Even with cloud-init or automated provisioning, misconfigurations can occur. This script acts as your second line of defense, ensuring that your server adheres to a baseline of security best practices before it goes into production.</p> <hr /> <h2 id="how-to-use-the-script">How to Use the Script</h2> <ol> <li><strong>Save the script:</strong> Copy the entire script content into a file, for example, <code>server-audit.sh</code>.</li> <li><strong>Make it executable:</strong><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">chmod</span><span style="color: #9ECBFF;"> +x server-audit.sh</span></span></code></pre></li> <li><strong>Run with <code>sudo</code>:</strong> The script requires root privileges to access system configurations and logs.<pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ./server-audit.sh</span></span></code></pre></li> <li><strong>Review the output:</strong> Pay close attention to <code>[FAIL]</code> and <code>[WARN]</code> messages, which indicate potential security vulnerabilities or areas for improvement.</li> </ol> <hr /> <h2 id="the-server-security-audit-script">The Server Security Audit Script</h2> <p>Here is the complete script. You can customize the <code>ADMIN_USER</code> variable at the beginning to match your dedicated administrative username.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;">#!/bin/bash</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Server Security Audit Script</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Checks if the cloud-init setup has been correctly applied and if current</span></span> <span class="giallo-l"><span style="color: #6A737D;"># security standards are met.</span></span> <span class="giallo-l"><span style="color: #6A737D;">#</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Usage: sudo bash server-audit.sh</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;">set -u</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># --- Colors &amp; Symbols --------------------------------------------------------</span></span> <span class="giallo-l"><span>GREEN</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;\033[0;32m&quot;</span></span> <span class="giallo-l"><span>RED</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;\033[0;31m&quot;</span></span> <span class="giallo-l"><span>YELLOW</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;\033[0;33m&quot;</span></span> <span class="giallo-l"><span>CYAN</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;\033[0;36m&quot;</span></span> <span class="giallo-l"><span>BOLD</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;\033[1m&quot;</span></span> <span class="giallo-l"><span>NC</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;\033[0m&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>PASS</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;${</span><span>GREEN</span><span style="color: #9ECBFF;">}PASS${</span><span>NC</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span>FAIL</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;${</span><span>RED</span><span style="color: #9ECBFF;">}FAIL${</span><span>NC</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span>WARN</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;${</span><span>YELLOW</span><span style="color: #9ECBFF;">}WARN${</span><span>NC</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span>INFO</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;${</span><span>CYAN</span><span style="color: #9ECBFF;">}INFO${</span><span>NC</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>pass_count</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">0</span></span> <span class="giallo-l"><span>fail_count</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">0</span></span> <span class="giallo-l"><span>warn_count</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">log_pass</span><span>() {</span><span style="color: #79B8FF;"> echo -e</span><span style="color: #9ECBFF;"> &quot; [${</span><span>PASS</span><span style="color: #9ECBFF;">}] </span><span style="color: #79B8FF;">$1</span><span style="color: #9ECBFF;">&quot;</span><span>; ((pass_count</span><span style="color: #F97583;">++</span><span>)); }</span></span> <span class="giallo-l"><span style="color: #B392F0;">log_fail</span><span>() {</span><span style="color: #79B8FF;"> echo -e</span><span style="color: #9ECBFF;"> &quot; [${</span><span>FAIL</span><span style="color: #9ECBFF;">}] </span><span style="color: #79B8FF;">$1</span><span style="color: #9ECBFF;">&quot;</span><span>; ((fail_count</span><span style="color: #F97583;">++</span><span>)); }</span></span> <span class="giallo-l"><span style="color: #B392F0;">log_warn</span><span>() {</span><span style="color: #79B8FF;"> echo -e</span><span style="color: #9ECBFF;"> &quot; [${</span><span>WARN</span><span style="color: #9ECBFF;">}] </span><span style="color: #79B8FF;">$1</span><span style="color: #9ECBFF;">&quot;</span><span>; ((warn_count</span><span style="color: #F97583;">++</span><span>)); }</span></span> <span class="giallo-l"><span style="color: #B392F0;">log_info</span><span>() {</span><span style="color: #79B8FF;"> echo -e</span><span style="color: #9ECBFF;"> &quot; [${</span><span>INFO</span><span style="color: #9ECBFF;">}] </span><span style="color: #79B8FF;">$1</span><span style="color: #9ECBFF;">&quot;</span><span>; }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">section</span><span>() {</span><span style="color: #79B8FF;"> echo -e</span><span style="color: #9ECBFF;"> &quot;\n${</span><span>BOLD</span><span style="color: #9ECBFF;">}=== </span><span style="color: #79B8FF;">$1</span><span style="color: #9ECBFF;"> ===${</span><span>NC</span><span style="color: #9ECBFF;">}&quot;</span><span>; }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># --- Root Check --------------------------------------------------------------</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[ $EUID</span><span style="color: #F97583;"> -ne</span><span style="color: #79B8FF;"> 0</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo -e</span><span style="color: #9ECBFF;"> &quot;${</span><span>RED</span><span style="color: #9ECBFF;">}This script must be run with sudo.${</span><span>NC</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> exit 1</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>ADMIN_USER</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;delightfuldude&quot;</span><span style="color: #6A737D;"> # &lt;--- CUSTOMIZE THIS TO YOUR ADMIN USERNAME</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;">echo -e</span><span style="color: #9ECBFF;"> &quot;${</span><span>BOLD</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;============================================================&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot; Server Security Audit - $(</span><span style="color: #B392F0;">date</span><span style="color: #9ECBFF;"> &#39;+%Y-%m-%d %H:%M:%S&#39;)&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;============================================================&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo -e</span><span style="color: #9ECBFF;"> &quot;${</span><span>NC</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #6A737D;"># 1. SYSTEM FUNDAMENTALS</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #B392F0;">section</span><span style="color: #9ECBFF;"> &quot;1. System Fundamentals&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Hostname</span></span> <span class="giallo-l"><span>CURRENT_HOSTNAME</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">hostnamectl</span><span style="color: #79B8FF;"> --static</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #B392F0;"> hostname</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$CURRENT_HOSTNAME</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> !=</span><span style="color: #9ECBFF;"> &quot;localhost&quot;</span><span style="color: #F97583;"> &amp;&amp; -n</span><span style="color: #9ECBFF;"> &quot;</span><span>$CURRENT_HOSTNAME</span><span style="color: #9ECBFF;">&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Hostname set: ${</span><span>CURRENT_HOSTNAME</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;Hostname is still on default&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Timezone</span></span> <span class="giallo-l"><span>CURRENT_TZ</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">timedatectl</span><span style="color: #9ECBFF;"> show</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> Timezone</span><span style="color: #79B8FF;"> --value</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #B392F0;"> cat</span><span style="color: #9ECBFF;"> /etc/timezone</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;unknown&quot;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$CURRENT_TZ</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &quot;Europe/Berlin&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Timezone: ${</span><span>CURRENT_TZ</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;Timezone is ${</span><span>CURRENT_TZ</span><span style="color: #9ECBFF;">} (expected: Europe/Berlin)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Kernel &amp; OS</span></span> <span class="giallo-l"><span style="color: #B392F0;">log_info</span><span style="color: #9ECBFF;"> &quot;OS: $(</span><span style="color: #B392F0;">grep</span><span style="color: #9ECBFF;"> PRETTY_NAME /etc/os-release</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> cut</span><span style="color: #79B8FF;"> -d= -f2</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> tr</span><span style="color: #79B8FF;"> -d</span><span style="color: #9ECBFF;"> &#39;&quot;&#39;)&quot;</span></span> <span class="giallo-l"><span style="color: #B392F0;">log_info</span><span style="color: #9ECBFF;"> &quot;Kernel: $(</span><span style="color: #B392F0;">uname</span><span style="color: #79B8FF;"> -r</span><span style="color: #9ECBFF;">)&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Uptime</span></span> <span class="giallo-l"><span style="color: #B392F0;">log_info</span><span style="color: #9ECBFF;"> &quot;Uptime: $(</span><span style="color: #B392F0;">uptime</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;">)&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Pending Updates</span></span> <span class="giallo-l"><span>UPDATES</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">apt</span><span style="color: #9ECBFF;"> list</span><span style="color: #79B8FF;"> --upgradable</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -c</span><span style="color: #9ECBFF;"> upgradable</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$UPDATES</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> -eq</span><span style="color: #79B8FF;"> 0</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;No pending package updates&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;${</span><span>UPDATES</span><span style="color: #9ECBFF;">} package update(s) available&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Reboot required?</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -f</span><span> /var/run/reboot-required ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;System reboot required&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;No reboot required&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #6A737D;"># 2. USER &amp; AUTHENTICATION</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #B392F0;">section</span><span style="color: #9ECBFF;"> &quot;2. User &amp; Authentication&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Admin user exists</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span style="color: #B392F0;"> id</span><span style="color: #9ECBFF;"> &quot;</span><span>$ADMIN_USER</span><span style="color: #9ECBFF;">&quot;</span><span> &amp;</span><span style="color: #F97583;">&gt;</span><span>/dev/null;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;User &#39;${</span><span>ADMIN_USER</span><span style="color: #9ECBFF;">}&#39; exists&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;User &#39;${</span><span>ADMIN_USER</span><span style="color: #9ECBFF;">}&#39; does NOT exist&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># sudo group</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span style="color: #B392F0;"> groups</span><span style="color: #9ECBFF;"> &quot;</span><span>$ADMIN_USER</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -qw</span><span style="color: #9ECBFF;"> sudo</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;&#39;${</span><span>ADMIN_USER</span><span style="color: #9ECBFF;">}&#39; is in the sudo group&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;&#39;${</span><span>ADMIN_USER</span><span style="color: #9ECBFF;">}&#39; is NOT in the sudo group&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># NOPASSWD in sudoers (accepted for cloud-init without password)</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -r</span><span style="color: #9ECBFF;"> &quot;NOPASSWD&quot; /etc/sudoers /etc/sudoers.d/</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -v</span><span style="color: #9ECBFF;"> &quot;^#&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -q</span><span style="color: #9ECBFF;"> &quot;</span><span>$ADMIN_USER</span><span style="color: #9ECBFF;">&quot;</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_info</span><span style="color: #9ECBFF;"> &quot;&#39;${</span><span>ADMIN_USER</span><span style="color: #9ECBFF;">}&#39; has NOPASSWD (intended, as cloud-init doesn&#39;t set a password)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;No NOPASSWD for &#39;${</span><span>ADMIN_USER</span><span style="color: #9ECBFF;">}&#39; - sudo requires password&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Root password (should be locked or random, not empty)</span></span> <span class="giallo-l"><span>ROOT_PW_STATUS</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">passwd</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> root</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $2}&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;">case</span><span style="color: #9ECBFF;"> &quot;</span><span>$ROOT_PW_STATUS</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> in</span></span> <span class="giallo-l"><span style="color: #DBEDFF;"> L</span><span style="color: #F97583;">)</span><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Root account is locked&quot;</span><span> ;;</span></span> <span class="giallo-l"><span style="color: #DBEDFF;"> P</span><span style="color: #F97583;">)</span><span style="color: #B392F0;"> log_info</span><span style="color: #9ECBFF;"> &quot;Root has a password set (randomized by cloud-init)&quot;</span><span> ;;</span></span> <span class="giallo-l"><span style="color: #DBEDFF;"> NP</span><span style="color: #F97583;">)</span><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Root has NO password!&quot;</span><span> ;;</span></span> <span class="giallo-l"><span style="color: #F97583;"> *)</span><span style="color: #B392F0;"> log_info</span><span style="color: #9ECBFF;"> &quot;Root password status: ${</span><span>ROOT_PW_STATUS</span><span style="color: #9ECBFF;">}&quot;</span><span> ;;</span></span> <span class="giallo-l"><span style="color: #F97583;">esac</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Accounts with empty password</span></span> <span class="giallo-l"><span>EMPTY_PW</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">awk</span><span style="color: #79B8FF;"> -F:</span><span style="color: #9ECBFF;"> &#39;($2 == &quot;&quot; ) { print $1 }&#39; /etc/shadow</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -z</span><span style="color: #9ECBFF;"> &quot;</span><span>$EMPTY_PW</span><span style="color: #9ECBFF;">&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;No accounts with empty password&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Accounts with empty password: ${</span><span>EMPTY_PW</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># UID-0 accounts (only root should have UID 0)</span></span> <span class="giallo-l"><span>ROOT_ACCOUNTS</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">awk</span><span style="color: #79B8FF;"> -F:</span><span style="color: #9ECBFF;"> &#39;($3 == 0) { print $1 }&#39; /etc/passwd</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$ROOT_ACCOUNTS</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &quot;root&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Only &#39;root&#39; has UID 0&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Multiple accounts with UID 0: ${</span><span>ROOT_ACCOUNTS</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #6A737D;"># 3. SSH HARDENING</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #B392F0;">section</span><span style="color: #9ECBFF;"> &quot;3. SSH Hardening&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Read effective SSH configuration</span></span> <span class="giallo-l"><span>SSHD_CONFIG</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">sshd</span><span style="color: #79B8FF;"> -T</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -z</span><span style="color: #9ECBFF;"> &quot;</span><span>$SSHD_CONFIG</span><span style="color: #9ECBFF;">&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Cannot read SSH configuration (sshd -T failed)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Port</span></span> <span class="giallo-l"><span> SSH_PORT</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$SSHD_CONFIG</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;^port &quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $2}&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$SSH_PORT</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> !=</span><span style="color: #9ECBFF;"> &quot;22&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;SSH port changed: ${</span><span>SSH_PORT</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;SSH is running on default port 22&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # Root Login</span></span> <span class="giallo-l"><span> ROOT_LOGIN</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$SSHD_CONFIG</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;^permitrootlogin &quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $2}&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$ROOT_LOGIN</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &quot;no&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Root login disabled&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Root login is &#39;${</span><span>ROOT_LOGIN</span><span style="color: #9ECBFF;">}&#39; (should be &#39;no&#39;)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # Password Auth</span></span> <span class="giallo-l"><span> PW_AUTH</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$SSHD_CONFIG</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;^passwordauthentication &quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $2}&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$PW_AUTH</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &quot;no&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Password authentication disabled&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Password authentication is enabled!&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # Pubkey Auth</span></span> <span class="giallo-l"><span> PUBKEY_AUTH</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$SSHD_CONFIG</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;^pubkeyauthentication &quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $2}&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$PUBKEY_AUTH</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &quot;yes&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Public-key authentication enabled&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Public-key authentication is disabled!&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # MaxAuthTries</span></span> <span class="giallo-l"><span> MAX_AUTH</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$SSHD_CONFIG</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;^maxauthtries &quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $2}&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$MAX_AUTH</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> -le</span><span style="color: #79B8FF;"> 3</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;MaxAuthTries: ${</span><span>MAX_AUTH</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;MaxAuthTries is ${</span><span>MAX_AUTH</span><span style="color: #9ECBFF;">} (recommended: &lt;=3)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # LoginGraceTime</span></span> <span class="giallo-l"><span> GRACE_TIME</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$SSHD_CONFIG</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;^logingracetime &quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $2}&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$GRACE_TIME</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> -le</span><span style="color: #79B8FF;"> 60</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;LoginGraceTime: ${</span><span>GRACE_TIME</span><span style="color: #9ECBFF;">}s&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;LoginGraceTime is ${</span><span>GRACE_TIME</span><span style="color: #9ECBFF;">}s (recommended: &lt;=60)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # X11Forwarding</span></span> <span class="giallo-l"><span> X11</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$SSHD_CONFIG</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;^x11forwarding &quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $2}&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$X11</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &quot;no&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;X11Forwarding disabled&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;X11Forwarding is enabled&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # TCP Forwarding</span></span> <span class="giallo-l"><span> TCP_FWD</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$SSHD_CONFIG</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;^allowtcpforwarding &quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $2}&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$TCP_FWD</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &quot;no&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;TCP-Forwarding disabled&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;TCP-Forwarding is enabled&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # Agent Forwarding</span></span> <span class="giallo-l"><span> AGENT_FWD</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$SSHD_CONFIG</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;^allowagentforwarding &quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $2}&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$AGENT_FWD</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &quot;no&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Agent-Forwarding disabled&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;Agent-Forwarding is enabled&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # AllowUsers set</span></span> <span class="giallo-l"><span> ALLOW_USERS</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$SSHD_CONFIG</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;^allowusers &quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{$1=&quot;&quot;; print $0}&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> xargs</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #F97583;"> -n</span><span style="color: #9ECBFF;"> &quot;</span><span>$ALLOW_USERS</span><span style="color: #9ECBFF;">&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;AllowUsers restricted to: ${</span><span>ALLOW_USERS</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;AllowUsers is not set (all users can use SSH)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # Check if insecure Key Algorithms are accepted</span></span> <span class="giallo-l"><span> ACCEPTED_ALGOS</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$SSHD_CONFIG</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;^pubkeyacceptedalgorithms &quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{$1=&quot;&quot;; print $0}&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> xargs</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #F97583;"> -n</span><span style="color: #9ECBFF;"> &quot;</span><span>$ACCEPTED_ALGOS</span><span style="color: #9ECBFF;">&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$ACCEPTED_ALGOS</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -qw</span><span style="color: #9ECBFF;"> &quot;ssh-rsa&quot;</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;ssh-rsa (SHA-1) is still allowed - use rsa-sha2-* only!&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Only modern Key Algorithms allowed&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_info</span><span style="color: #9ECBFF;"> &quot;Allowed Algorithms: ${</span><span>ACCEPTED_ALGOS</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_info</span><span style="color: #9ECBFF;"> &quot;PubkeyAcceptedAlgorithms: System Default (SHA-1 blocked since OpenSSH 8.8)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># SSH Key present for Admin User</span></span> <span class="giallo-l"><span>ADMIN_HOME</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">eval</span><span style="color: #9ECBFF;"> echo ~&quot;</span><span>$ADMIN_USER</span><span style="color: #9ECBFF;">&quot;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -f</span><span style="color: #9ECBFF;"> &quot;${</span><span>ADMIN_HOME</span><span style="color: #9ECBFF;">}/.ssh/authorized_keys&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span> KEY_COUNT</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">grep</span><span style="color: #79B8FF;"> -c</span><span style="color: #9ECBFF;"> &quot;^ssh-&quot; &quot;${</span><span>ADMIN_HOME</span><span style="color: #9ECBFF;">}/.ssh/authorized_keys&quot;</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$KEY_COUNT</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> -gt</span><span style="color: #79B8FF;"> 0</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;${</span><span>KEY_COUNT</span><span style="color: #9ECBFF;">} SSH key(s) stored for &#39;${</span><span>ADMIN_USER</span><span style="color: #9ECBFF;">}&#39;&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> while</span><span> IFS</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;"> read -r</span><span style="color: #9ECBFF;"> line</span><span>;</span><span style="color: #F97583;"> do</span></span> <span class="giallo-l"><span> KEY_TYPE</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$line</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $1}&#39;</span><span>)</span></span> <span class="giallo-l"><span> KEY_COMMENT</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$line</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $3}&#39;</span><span>)</span></span> <span class="giallo-l"><span> KEY_BITS</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">ssh-keygen</span><span style="color: #79B8FF;"> -l -f</span><span style="color: #9ECBFF;"> /dev/stdin</span><span style="color: #F97583;"> &lt;&lt;&lt;</span><span style="color: #9ECBFF;"> &quot;</span><span>$line</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $1}&#39;</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span><span>)</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_info</span><span style="color: #9ECBFF;"> &quot; Key: ${</span><span>KEY_TYPE</span><span style="color: #9ECBFF;">} ${</span><span>KEY_BITS</span><span style="color: #F97583;">:-</span><span style="color: #9ECBFF;">?} bit (${</span><span>KEY_COMMENT</span><span style="color: #F97583;">:-</span><span>no comment</span><span style="color: #9ECBFF;">})&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> done &lt;</span><span style="color: #9ECBFF;"> &lt;(</span><span style="color: #B392F0;">grep</span><span style="color: #9ECBFF;"> &quot;^ssh-&quot; &quot;${</span><span>ADMIN_HOME</span><span style="color: #9ECBFF;">}/.ssh/authorized_keys&quot;)</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;No SSH keys in authorized_keys!&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;No authorized_keys file for &#39;${</span><span>ADMIN_USER</span><span style="color: #9ECBFF;">}&#39;!&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>SSH_VERSION</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">ssh</span><span style="color: #79B8FF;"> -V</span><span style="color: #F97583;"> 2&gt;&amp;1</span><span>)</span></span> <span class="giallo-l"><span style="color: #B392F0;">log_info</span><span style="color: #9ECBFF;"> &quot;SSH Version: ${</span><span>SSH_VERSION</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #6A737D;"># 4. FIREWALL (UFW)</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #B392F0;">section</span><span style="color: #9ECBFF;"> &quot;4. Firewall (UFW)&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># SSH_PORT for later use (if sshd -T failed)</span></span> <span class="giallo-l"><span>SSH_PORT</span><span style="color: #F97583;">=</span><span>${SSH_PORT</span><span style="color: #F97583;">:-</span><span>8496}</span><span style="color: #6A737D;"> # Fallback to a common custom port</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span style="color: #79B8FF;"> command -v</span><span style="color: #9ECBFF;"> ufw</span><span> &amp;</span><span style="color: #F97583;">&gt;</span><span>/dev/null;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span> UFW_STATUS</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">ufw</span><span style="color: #9ECBFF;"> status</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$UFW_STATUS</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -q</span><span style="color: #9ECBFF;"> &quot;Status: active&quot;</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;UFW is active&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # Default Policies</span></span> <span class="giallo-l"><span> UFW_VERBOSE</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">ufw</span><span style="color: #9ECBFF;"> status verbose</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$UFW_VERBOSE</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -q</span><span style="color: #9ECBFF;"> &quot;deny (incoming)&quot;</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Default policy incoming: deny&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Default policy incoming is NOT deny!&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$UFW_VERBOSE</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -q</span><span style="color: #9ECBFF;"> &quot;allow (outgoing)&quot;</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Default policy outgoing: allow&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_info</span><span style="color: #9ECBFF;"> &quot;Default policy outgoing is not &#39;allow&#39;&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # List open ports</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;&quot;</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_info</span><span style="color: #9ECBFF;"> &quot;Active rules:&quot;</span></span> <span class="giallo-l"><span style="color: #B392F0;"> ufw</span><span style="color: #9ECBFF;"> status numbered</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -E</span><span style="color: #9ECBFF;"> &quot;^\[&quot;</span><span style="color: #F97583;"> | while</span><span> IFS</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;"> read -r</span><span style="color: #9ECBFF;"> rule</span><span>;</span><span style="color: #F97583;"> do</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo -e</span><span style="color: #9ECBFF;"> &quot; ${</span><span>rule</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> done</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # SSH port with rate-limit?</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$UFW_STATUS</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -q</span><span style="color: #9ECBFF;"> &quot;${</span><span>SSH_PORT</span><span style="color: #9ECBFF;">}.*LIMIT&quot;</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;SSH port ${</span><span>SSH_PORT</span><span style="color: #9ECBFF;">} has Rate-Limiting&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> elif</span><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$UFW_STATUS</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -q</span><span style="color: #9ECBFF;"> &quot;${</span><span>SSH_PORT</span><span style="color: #9ECBFF;">}&quot;</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;SSH port ${</span><span>SSH_PORT</span><span style="color: #9ECBFF;">} is open, but WITHOUT Rate-Limiting&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;SSH port ${</span><span>SSH_PORT</span><span style="color: #9ECBFF;">} is not explicitly in UFW&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;UFW is NOT active&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # UFW Logging Redirect (VNC Console fix)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #F97583;"> -f</span><span> /etc/rsyslog.d/20-ufw.conf ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;UFW logs are redirected to /var/log/ufw.log (console remains clean)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;UFW logs not redirected - VNC console will be flooded with [UFW BLOCK]&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;UFW is not installed&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #6A737D;"># 5. FAIL2BAN</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #B392F0;">section</span><span style="color: #9ECBFF;"> &quot;5. Fail2Ban&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span style="color: #79B8FF;"> command -v</span><span style="color: #9ECBFF;"> fail2ban-client</span><span> &amp;</span><span style="color: #F97583;">&gt;</span><span>/dev/null;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #B392F0;"> systemctl</span><span style="color: #9ECBFF;"> is-active</span><span style="color: #79B8FF;"> --quiet</span><span style="color: #9ECBFF;"> fail2ban</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Fail2Ban is running&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # SSH Jail active?</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #B392F0;"> fail2ban-client</span><span style="color: #9ECBFF;"> status sshd</span><span> &amp;</span><span style="color: #F97583;">&gt;</span><span>/dev/null;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;SSH Jail is active&quot;</span></span> <span class="giallo-l"><span> F2B_STATUS</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">fail2ban-client</span><span style="color: #9ECBFF;"> status sshd</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span><span>)</span></span> <span class="giallo-l"><span> BANNED</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$F2B_STATUS</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;Currently banned&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $NF}&#39;</span><span>)</span></span> <span class="giallo-l"><span> TOTAL_BANNED</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$F2B_STATUS</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;Total banned&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $NF}&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_info</span><span style="color: #9ECBFF;"> &quot;Currently banned: ${</span><span>BANNED</span><span style="color: #F97583;">:-</span><span>0</span><span style="color: #9ECBFF;">}, Total banned: ${</span><span>TOTAL_BANNED</span><span style="color: #F97583;">:-</span><span>0</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;SSH Jail is NOT active&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # Check configuration</span></span> <span class="giallo-l"><span> F2B_PORT</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">grep</span><span style="color: #79B8FF;"> -r</span><span style="color: #9ECBFF;"> &quot;^port&quot; /etc/fail2ban/jail.local</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> head</span><span style="color: #79B8FF;"> -1</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $NF}&#39;</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$F2B_PORT</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &quot;</span><span>$SSH_PORT</span><span style="color: #9ECBFF;">&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Fail2Ban monitors correct SSH port (${</span><span>F2B_PORT</span><span style="color: #9ECBFF;">})&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> elif</span><span> [[</span><span style="color: #F97583;"> -n</span><span style="color: #9ECBFF;"> &quot;</span><span>$F2B_PORT</span><span style="color: #9ECBFF;">&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Fail2Ban monitors port ${</span><span>F2B_PORT</span><span style="color: #9ECBFF;">}, SSH runs on ${</span><span>SSH_PORT</span><span style="color: #9ECBFF;">}!&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Fail2Ban is installed, but NOT active&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Fail2Ban is not installed&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #6A737D;"># 6. AUTOMATIC UPDATES</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #B392F0;">section</span><span style="color: #9ECBFF;"> &quot;6. Automatic Updates&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span style="color: #B392F0;"> dpkg</span><span style="color: #79B8FF;"> -l</span><span style="color: #9ECBFF;"> unattended-upgrades</span><span> &amp;</span><span style="color: #F97583;">&gt;</span><span>/dev/null;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;unattended-upgrades is installed&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #F97583;"> -f</span><span> /etc/apt/apt.conf.d/20auto-upgrades ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -q</span><span style="color: #9ECBFF;"> &#39;Unattended-Upgrade &quot;1&quot;&#39; /etc/apt/apt.conf.d/20auto-upgrades</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Automatic upgrades are enabled&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;20auto-upgrades exists, but upgrades appear disabled&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;20auto-upgrades configuration is missing&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;unattended-upgrades is not installed&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #6A737D;"># 7. DOCKER</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #B392F0;">section</span><span style="color: #9ECBFF;"> &quot;7. Docker&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span style="color: #79B8FF;"> command -v</span><span style="color: #9ECBFF;"> docker</span><span> &amp;</span><span style="color: #F97583;">&gt;</span><span>/dev/null;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Docker is installed: $(</span><span style="color: #B392F0;">docker</span><span style="color: #79B8FF;"> --version</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> head</span><span style="color: #79B8FF;"> -1</span><span style="color: #9ECBFF;">)&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #B392F0;"> systemctl</span><span style="color: #9ECBFF;"> is-active</span><span style="color: #79B8FF;"> --quiet</span><span style="color: #9ECBFF;"> docker</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Docker daemon is running&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;Docker daemon is not active&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # Docker Compose</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #B392F0;"> docker</span><span style="color: #9ECBFF;"> compose version</span><span> &amp;</span><span style="color: #F97583;">&gt;</span><span>/dev/null;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Docker Compose: $(</span><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose version</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> head</span><span style="color: #79B8FF;"> -1</span><span style="color: #9ECBFF;">)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;Docker Compose Plugin not found&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # User in docker group</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #B392F0;"> groups</span><span style="color: #9ECBFF;"> &quot;</span><span>$ADMIN_USER</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -qw</span><span style="color: #9ECBFF;"> docker</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;&#39;${</span><span>ADMIN_USER</span><span style="color: #9ECBFF;">}&#39; is in the docker group&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;&#39;${</span><span>ADMIN_USER</span><span style="color: #9ECBFF;">}&#39; is NOT in the docker group&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # Log rotation configured?</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #F97583;"> -f</span><span> /etc/docker/daemon.json ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -q</span><span style="color: #9ECBFF;"> &quot;max-size&quot; /etc/docker/daemon.json</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Docker Log rotation configured&quot;</span></span> <span class="giallo-l"><span> MAX_SIZE</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">grep</span><span style="color: #9ECBFF;"> &quot;max-size&quot; /etc/docker/daemon.json</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> tr</span><span style="color: #79B8FF;"> -d</span><span style="color: #9ECBFF;"> &#39; &quot;,&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> cut</span><span style="color: #79B8FF;"> -d: -f2</span><span>)</span></span> <span class="giallo-l"><span> MAX_FILE</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">grep</span><span style="color: #9ECBFF;"> &quot;max-file&quot; /etc/docker/daemon.json</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> tr</span><span style="color: #79B8FF;"> -d</span><span style="color: #9ECBFF;"> &#39; &quot;,&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> cut</span><span style="color: #79B8FF;"> -d: -f2</span><span>)</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_info</span><span style="color: #9ECBFF;"> &quot;max-size: ${</span><span>MAX_SIZE</span><span style="color: #9ECBFF;">}, max-file: ${</span><span>MAX_FILE</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;daemon.json exists, but no Log rotation configured&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;No daemon.json - Docker logs can grow indefinitely!&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # Proxy network</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #B392F0;"> docker</span><span style="color: #9ECBFF;"> network ls</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -q</span><span style="color: #9ECBFF;"> &quot;proxy&quot;</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Docker network &#39;proxy&#39; exists&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;Docker network &#39;proxy&#39; is missing&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Docker is not installed&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #6A737D;"># 8. TRAEFIK PREPARATION</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #B392F0;">section</span><span style="color: #9ECBFF;"> &quot;8. Traefik Stack Preparation&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>TRAEFIK_DIR</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;/opt/containers/traefik-stack&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -d</span><span style="color: #9ECBFF;"> &quot;</span><span>$TRAEFIK_DIR</span><span style="color: #9ECBFF;">&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Directory ${</span><span>TRAEFIK_DIR</span><span style="color: #9ECBFF;">} exists&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # Subdirectories</span></span> <span class="giallo-l"><span style="color: #F97583;"> for</span><span> dir</span><span style="color: #F97583;"> in</span><span style="color: #9ECBFF;"> traefik/dynamic traefik/logs traefik/certs crowdsec/config crowdsec/data</span><span>;</span><span style="color: #F97583;"> do</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #F97583;"> -d</span><span style="color: #9ECBFF;"> &quot;${</span><span>TRAEFIK_DIR</span><span style="color: #9ECBFF;">}/${</span><span>dir</span><span style="color: #9ECBFF;">}&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot; ${</span><span>dir</span><span style="color: #9ECBFF;">}/ is present&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot; ${</span><span>dir</span><span style="color: #9ECBFF;">}/ is missing&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;"> done</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # acme.json Permissions</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #F97583;"> -f</span><span style="color: #9ECBFF;"> &quot;${</span><span>TRAEFIK_DIR</span><span style="color: #9ECBFF;">}/traefik/certs/acme.json&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span> ACME_PERMS</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">stat -c</span><span style="color: #9ECBFF;"> &quot;%a&quot; &quot;${</span><span>TRAEFIK_DIR</span><span style="color: #9ECBFF;">}/traefik/certs/acme.json&quot;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$ACME_PERMS</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &quot;600&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;acme.json has correct permissions (600)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;acme.json has permissions ${</span><span>ACME_PERMS</span><span style="color: #9ECBFF;">} (should be 600)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;acme.json does not exist yet&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Directory ${</span><span>TRAEFIK_DIR</span><span style="color: #9ECBFF;">} is missing&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #6A737D;"># 9. LOG ROTATION</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #B392F0;">section</span><span style="color: #9ECBFF;"> &quot;9. Log Rotation&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Persistent Journal</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -d</span><span> /var/log/journal ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Persistent Journal activated&quot;</span></span> <span class="giallo-l"><span> JOURNAL_SIZE</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">journalctl</span><span style="color: #79B8FF;"> --disk-usage</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -oP</span><span style="color: #9ECBFF;"> &#39;[\d.]+\w+&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> head</span><span style="color: #79B8FF;"> -1</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> true</span><span>)</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_info</span><span style="color: #9ECBFF;"> &quot;Journal size: ${</span><span>JOURNAL_SIZE</span><span style="color: #F97583;">:-</span><span>unknown</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;Journal is NOT persistent (logs are lost on reboot)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Logrotate: Traefik</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -f</span><span> /etc/logrotate.d/traefik ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Logrotate for Traefik configured&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;Logrotate for Traefik is missing&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Logrotate: UFW</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -f</span><span> /etc/logrotate.d/ufw-custom ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Logrotate for UFW logs configured&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">elif</span><span> [[</span><span style="color: #F97583;"> -f</span><span> /etc/logrotate.d/ufw ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Logrotate for UFW logs configured (system default)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;Logrotate for UFW logs is missing - /var/log/ufw.log can grow indefinitely!&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Docker Log Rotation (Summary)</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #F97583;"> -f</span><span> /etc/docker/daemon.json ]] &amp;&amp;</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -q</span><span style="color: #9ECBFF;"> &quot;max-size&quot; /etc/docker/daemon.json</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Docker Container logs rotated&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;Docker Container logs are not rotated&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #6A737D;"># 10. NETWORK &amp; OPEN PORTS</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #B392F0;">section</span><span style="color: #9ECBFF;"> &quot;10. Network &amp; Open Ports&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">log_info</span><span style="color: #9ECBFF;"> &quot;Listening ports (externally accessible):&quot;</span></span> <span class="giallo-l"><span style="color: #B392F0;">ss</span><span style="color: #79B8FF;"> -tlnp</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -v</span><span style="color: #9ECBFF;"> &quot;127.0.0&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;LISTEN&quot;</span><span style="color: #F97583;"> | while</span><span> IFS</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;"> read -r</span><span style="color: #9ECBFF;"> line</span><span>;</span><span style="color: #F97583;"> do</span></span> <span class="giallo-l"><span> PORT</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$line</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;{print $4}&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> rev</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> cut</span><span style="color: #79B8FF;"> -d: -f1</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> rev</span><span>)</span></span> <span class="giallo-l"><span> PROC</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$line</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -oP</span><span style="color: #9ECBFF;"> &#39;users:\(\(&quot;\K[^&quot;]+&#39;</span><span style="color: #F97583;"> ||</span><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;unknown&quot;</span><span>)</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo -e</span><span style="color: #9ECBFF;"> &quot; Port ${</span><span>PORT</span><span style="color: #9ECBFF;">} (${</span><span>PROC</span><span style="color: #9ECBFF;">})&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">done</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Check for known insecure services</span></span> <span class="giallo-l"><span>INSECURE_FOUND</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">0</span></span> <span class="giallo-l"><span style="color: #F97583;">for</span><span> svc</span><span style="color: #F97583;"> in</span><span style="color: #9ECBFF;"> telnetd rshd rlogind vsftpd proftpd</span><span>;</span><span style="color: #F97583;"> do</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #B392F0;"> systemctl</span><span style="color: #9ECBFF;"> is-active</span><span style="color: #79B8FF;"> --quiet</span><span style="color: #9ECBFF;"> &quot;</span><span>$svc</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Insecure service running: ${</span><span>svc</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span> INSECURE_FOUND</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">1</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;">done</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$INSECURE_FOUND</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> -eq</span><span style="color: #79B8FF;"> 0</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;No insecure legacy services active&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #6A737D;"># 11. FILESYSTEM SECURITY</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #B392F0;">section</span><span style="color: #9ECBFF;"> &quot;11. Filesystem&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># World-writable files in critical directories</span></span> <span class="giallo-l"><span>WW_COUNT</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">find</span><span style="color: #9ECBFF;"> /etc /usr</span><span style="color: #79B8FF;"> -xdev -type</span><span style="color: #9ECBFF;"> f</span><span style="color: #79B8FF;"> -perm -o+w</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> wc</span><span style="color: #79B8FF;"> -l</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$WW_COUNT</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> -eq</span><span style="color: #79B8FF;"> 0</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;No world-writable files in /etc and /usr&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;${</span><span>WW_COUNT</span><span style="color: #9ECBFF;">} world-writable file(s) in /etc or /usr&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># SUID Binaries (informative)</span></span> <span class="giallo-l"><span>SUID_COUNT</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">find</span><span style="color: #9ECBFF;"> /</span><span style="color: #79B8FF;"> -xdev -type</span><span style="color: #9ECBFF;"> f</span><span style="color: #79B8FF;"> -perm -4000</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> wc</span><span style="color: #79B8FF;"> -l</span><span>)</span></span> <span class="giallo-l"><span style="color: #B392F0;">log_info</span><span style="color: #9ECBFF;"> &quot;SUID binaries found: ${</span><span>SUID_COUNT</span><span style="color: #9ECBFF;">} (manual review if needed)&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Disk Usage</span></span> <span class="giallo-l"><span>DISK_USAGE</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">df</span><span style="color: #79B8FF;"> -h</span><span style="color: #9ECBFF;"> /</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> awk</span><span style="color: #9ECBFF;"> &#39;NR==2 {print $5}&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> tr</span><span style="color: #79B8FF;"> -d</span><span style="color: #9ECBFF;"> &#39;%&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$DISK_USAGE</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> -lt</span><span style="color: #79B8FF;"> 80</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_pass</span><span style="color: #9ECBFF;"> &quot;Disk usage: ${</span><span>DISK_USAGE</span><span style="color: #9ECBFF;">}%&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">elif</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$DISK_USAGE</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> -lt</span><span style="color: #79B8FF;"> 90</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_warn</span><span style="color: #9ECBFF;"> &quot;Disk usage: ${</span><span>DISK_USAGE</span><span style="color: #9ECBFF;">}% (getting low)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> log_fail</span><span style="color: #9ECBFF;"> &quot;Disk usage: ${</span><span>DISK_USAGE</span><span style="color: #9ECBFF;">}% (critical!)&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #6A737D;"># SUMMARY</span></span> <span class="giallo-l"><span style="color: #6A737D;"># =============================================================================</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo -e</span><span style="color: #9ECBFF;"> &quot;${</span><span>BOLD</span><span style="color: #9ECBFF;">}============================================================${</span><span>NC</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo -e</span><span style="color: #9ECBFF;"> &quot;${</span><span>BOLD</span><span style="color: #9ECBFF;">} SUMMARY${</span><span>NC</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo -e</span><span style="color: #9ECBFF;"> &quot;${</span><span>BOLD</span><span style="color: #9ECBFF;">}============================================================${</span><span>NC</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo -e</span><span style="color: #9ECBFF;"> &quot; ${</span><span>GREEN</span><span style="color: #9ECBFF;">}Passed:${</span><span>NC</span><span style="color: #9ECBFF;">} ${</span><span>pass_count</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo -e</span><span style="color: #9ECBFF;"> &quot; ${</span><span>YELLOW</span><span style="color: #9ECBFF;">}Warnings:${</span><span>NC</span><span style="color: #9ECBFF;">} ${</span><span>warn_count</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo -e</span><span style="color: #9ECBFF;"> &quot; ${</span><span>RED</span><span style="color: #9ECBFF;">}Failed:${</span><span>NC</span><span style="color: #9ECBFF;">} ${</span><span>fail_count</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo -e</span><span style="color: #9ECBFF;"> &quot;${</span><span>BOLD</span><span style="color: #9ECBFF;">}============================================================${</span><span>NC</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$fail_count</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> -eq</span><span style="color: #79B8FF;"> 0</span><span style="color: #F97583;"> &amp;&amp;</span><span style="color: #9ECBFF;"> &quot;</span><span>$warn_count</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> -eq</span><span style="color: #79B8FF;"> 0</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo -e</span><span style="color: #9ECBFF;"> &quot;\n${</span><span>GREEN</span><span style="color: #9ECBFF;">}${</span><span>BOLD</span><span style="color: #9ECBFF;">}Excellent! All checks passed.${</span><span>NC</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">elif</span><span> [[</span><span style="color: #9ECBFF;"> &quot;</span><span>$fail_count</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> -eq</span><span style="color: #79B8FF;"> 0</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo -e</span><span style="color: #9ECBFF;"> &quot;\n${</span><span>YELLOW</span><span style="color: #9ECBFF;">}${</span><span>BOLD</span><span style="color: #9ECBFF;">}Good - no critical failures, but review warnings.${</span><span>NC</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo -e</span><span style="color: #9ECBFF;"> &quot;\n${</span><span>RED</span><span style="color: #9ECBFF;">}${</span><span>BOLD</span><span style="color: #9ECBFF;">}Attention - there are critical failures that should be resolved!${</span><span>NC</span><span style="color: #9ECBFF;">}&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;">exit</span><span style="color: #9ECBFF;"> &quot;</span><span>$fail_count</span><span style="color: #9ECBFF;">&quot;</span></span></code></pre> Self-Hosting Plausible Analytics with Docker and Traefik Wed, 11 Mar 2026 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/plausible-analytics-selfhosted/ https://criticalbasics.xyz/posts/plausible-analytics-selfhosted/ <p>This guide walks you through deploying a fully self-hosted <a rel="noopener external" target="_blank" href="https://plausible.io/">Plausible Analytics</a> instance. Plausible is a lightweight, privacy-friendly alternative to Google Analytics — it doesn’t use cookies, is fully GDPR-compliant, and respects the privacy of your visitors. By self-hosting it, you retain complete ownership of your data while keeping your analytics costs predictable.</p> <p>We use the <strong>official Plausible Community Edition repository</strong> as the foundation and integrate it with our existing Traefik v3 reverse proxy via a <code>compose.override.yml</code>. This approach keeps the original <code>compose.yml</code> untouched, making future updates clean and painless.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2026-03-11</td><td><strong>Initial Version:</strong> Guide created for self-hosting Plausible CE v3.2.0 behind Traefik v3 with CrowdSec, based on the official repository.</td></tr> </tbody></table> </div> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>This guide builds upon a secure Docker environment. Before you begin, you must have a fully functional Traefik v3 and CrowdSec stack.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ HARD REQUIREMENT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The following steps will not work correctly without the Traefik stack running as described in the prerequisite guide.</p> <ul> <li><strong><a href="../traefik_v3_crowdsec_tutorial/">Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack</a></strong>: This is the foundation for our public-facing reverse proxy and security.</li> </ul> </td> </tr> </table> <p>You will also need:</p> <ul> <li>A dedicated subdomain for your Plausible instance (e.g., <code>plausible.your-domain.com</code>) pointed to your server’s IP address.</li> <li><code>sudo</code> or root access.</li> <li><code>git</code> and the <code>openssl</code> utility (<code>sudo apt install git openssl</code>).</li> </ul> <h2 id="2-clone-the-official-repository">2. Clone the Official Repository</h2> <p>Instead of building our own Docker Compose configuration from scratch, we clone the official Plausible CE repository. It ships with a tested <code>compose.yml</code> and pre-configured ClickHouse settings (including IPv4-only mode and resource-friendly defaults).</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> git clone</span><span style="color: #79B8FF;"> -b</span><span style="color: #9ECBFF;"> v3.2.0</span><span style="color: #79B8FF;"> --single-branch</span><span style="color: #9ECBFF;"> https://github.com/plausible/community-edition plausible</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> plausible</span></span></code></pre> <p>The repository contains the following structure:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>plausible/</span></span> <span class="giallo-l"><span>├── clickhouse/</span></span> <span class="giallo-l"><span>│ ├── default-profile-low-resources-overrides.xml</span></span> <span class="giallo-l"><span>│ ├── ipv4-only.xml</span></span> <span class="giallo-l"><span>│ ├── logs.xml</span></span> <span class="giallo-l"><span>│ └── low-resources.xml</span></span> <span class="giallo-l"><span>├── compose.yml</span></span> <span class="giallo-l"><span>├── LICENSE</span></span> <span class="giallo-l"><span>└── README.md</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ WHY NOT A CUSTOM COMPOSE FILE? </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The official <code>compose.yml</code> includes battle-tested ClickHouse configuration, proper healthchecks, and sensible defaults. Building a custom Compose file from scratch is error-prone and makes updates harder. Instead, we use a <code>compose.override.yml</code> to add only our Traefik-specific configuration — Docker Compose merges both files automatically.</p> </td> </tr> </table> <h2 id="3-configuration">3. Configuration</h2> <p>We only need to create two files: an <code>.env</code> file with your settings and a <code>compose.override.yml</code> for Traefik integration.</p> <h3 id="3-1-generate-secrets">3.1. Generate Secrets</h3> <p>Plausible requires a secret key base for signing tokens and a TOTP vault key for two-factor authentication.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Generate the secret key base (at least 64 bytes)</span></span> <span class="giallo-l"><span>SECRET_KEY_BASE</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">openssl</span><span style="color: #9ECBFF;"> rand</span><span style="color: #79B8FF;"> -base64 48</span><span>)</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;Your Secret Key Base is: </span><span>$SECRET_KEY_BASE</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Generate the TOTP vault key</span></span> <span class="giallo-l"><span>TOTP_VAULT_KEY</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">openssl</span><span style="color: #9ECBFF;"> rand</span><span style="color: #79B8FF;"> -base64 32</span><span>)</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;Your TOTP Vault Key is: </span><span>$TOTP_VAULT_KEY</span><span style="color: #9ECBFF;">&quot;</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ SAVE THESE SECRETS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Copy these generated values into a temporary text file. You will need to paste them into the <code>.env</code> file in the next step.</p> </td> </tr> </table> <h3 id="3-2-environment-configuration-env">3.2. Environment Configuration (<code>.env</code>)</h3> <p>This single file holds all your instance-specific settings. Create it in the repository root:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">cat</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> .env</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># --- Required Settings ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Replace with your actual domain, including https://</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">BASE_URL=https://plausible.your-domain.com</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Paste the secret key base generated in step 3.1</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">SECRET_KEY_BASE=PASTE-YOUR-SECRET-KEY-BASE-HERE</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Paste the TOTP vault key generated in step 3.1</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">TOTP_VAULT_KEY=PASTE-YOUR-TOTP-VAULT-KEY-HERE</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"># --- Registration ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># &quot;invite_only&quot; = only you can invite users. &quot;true&quot; = no new signups at all.</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Remove this line entirely to allow open registration.</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">DISABLE_REGISTRATION=invite_only</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"># --- Email / SMTP (Optional but recommended) ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Without SMTP, features like password resets and weekly reports will not work.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"># The &quot;From:&quot; address shown in emails sent by Plausible.</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Use your SMTP login address or an alias your mail server accepts.</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">MAILER_EMAIL=plausible@your-domain.com</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Your SMTP server address, e.g. smtp.mailbox.org or mail.your-domain.com</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">SMTP_HOST_ADDR=your-mail-server.com</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Your SMTP port: typically 587 (STARTTLS) or 465 (SSL)</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">SMTP_HOST_PORT=587</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Your SMTP username — usually your full email address</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">SMTP_USER_NAME=your-smtp-username</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Your SMTP password</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">SMTP_USER_PWD=your-smtp-password</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Set to &quot;true&quot; only if your port is 465 (implicit SSL). For port 587, keep &quot;false&quot;.</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">SMTP_HOST_SSL_ENABLED=false</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ BASE_URL MUST BE CORRECT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The <code>BASE_URL</code> must match your public URL exactly, including <code>https://</code>. A mismatch will cause tracking scripts to fail and break the dashboard.</p> </td> </tr> </table> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 REGISTRATION POLICY </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The <code>DISABLE_REGISTRATION=invite_only</code> setting means that only you (the admin) can invite new users. This is the recommended setting for personal instances. Set it to <code>true</code> to completely disable new signups, or remove the line entirely to allow open registration.</p> </td> </tr> </table> <h3 id="3-3-traefik-integration-compose-override-yml">3.3. Traefik Integration (<code>compose.override.yml</code>)</h3> <p>This file adds the Traefik labels and network connection to the Plausible service. Docker Compose merges it automatically with the official <code>compose.yml</code> — no need to modify the original file.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">cat</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> compose.override.yml</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">services:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> plausible:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - default</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - proxy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> labels:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Replace plausible.your-domain.com with your actual domain.</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # This tells Traefik which incoming requests to route to this container.</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.plausible.rule=Host(`plausible.your-domain.com`)&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.plausible.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.plausible.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.plausible.middlewares=security-headers@file,crowdsec-bouncer@docker&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.services.plausible.loadbalancer.server.port=8000&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.docker.network=proxy&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> external: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ WHY DOES THE DOMAIN APPEAR TWICE? </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p><code>BASE_URL</code> in <code>.env</code> tells <strong>Plausible</strong> which URL it runs under — for generating correct links, cookies, and tracking scripts. The Traefik <code>Host()</code> label in <code>compose.override.yml</code> tells <strong>Traefik</strong> which incoming requests to route to the Plausible container. These are two independent systems that don’t read each other’s configuration, so both need the domain separately.</p> </td> </tr> </table> <h3 id="3-4-update-configuration-with-your-values">3.4. Update Configuration with Your Values</h3> <p>Replace all placeholders in the two files you just created. Every value that needs your input is marked with inline comments.</p> <ol> <li><strong>Domain Name:</strong> In <code>.env</code> (<code>BASE_URL</code>) and <code>compose.override.yml</code> (Traefik <code>Host</code> label), replace <code>plausible.your-domain.com</code> with your actual domain.</li> <li><strong>Secrets:</strong> In <code>.env</code>, paste the <code>SECRET_KEY_BASE</code> and <code>TOTP_VAULT_KEY</code> you generated in step 3.1.</li> <li><strong>Email Settings:</strong> In <code>.env</code>, update the SMTP section with your mail server details. Each field has an inline comment explaining what to enter.</li> </ol> <h2 id="4-launch-the-stack">4. Launch the Stack</h2> <p>With both files in place, start the stack:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># From within the /opt/containers/plausible directory</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose up</span><span style="color: #79B8FF;"> -d</span></span></code></pre> <p>The first launch will take a few minutes as Docker pulls the images and Plausible runs its initial database migrations. You can monitor the progress with:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose logs</span><span style="color: #79B8FF;"> -f</span></span></code></pre> <p>Press <code>CTRL+C</code> to exit the logs view once all services are stable. You should see Plausible report that it is ready.</p> <h2 id="5-verify-the-installation">5. Verify the Installation</h2> <ol> <li> <p><strong>Check Running Containers:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> ps</span><span style="color: #79B8FF;"> --format</span><span style="color: #9ECBFF;"> &#39;{{.Names}}&#39;</span></span></code></pre> <p>You should see three containers running: <code>plausible-plausible-1</code>, <code>plausible-plausible_db-1</code> (PostgreSQL), and <code>plausible-plausible_events_db-1</code> (ClickHouse).</p> </li> <li> <p><strong>Access the Dashboard:</strong> Open a web browser and navigate to <code>https://plausible.your-domain.com</code>. You should see the Plausible registration page.</p> </li> <li> <p><strong>Create Your Admin Account:</strong> Register with your email address and a strong password. Since we set <code>DISABLE_REGISTRATION=invite_only</code>, this first account becomes the admin. All future registrations will require an invitation from you.</p> </li> </ol> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 EMAIL VERIFICATION WITHOUT SMTP </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>If you skipped the SMTP configuration, you can manually verify your email address by running: <code>sudo docker compose exec plausible_db psql -U postgres -h localhost -d plausible_db -c "UPDATE users SET email_verified = true;"</code></p> </td> </tr> </table> <h2 id="6-add-plausible-to-your-website">6. Add Plausible to Your Website</h2> <p>After logging in and creating your first site in the dashboard, Plausible will provide a tracking snippet. Starting with v3, Plausible generates a <strong>dynamic, site-specific script</strong> for each site you add. Simply copy the snippet from the site settings and add it to the <code>&lt;head&gt;</code> section of your website.</p> <p>For a Zola-based site, add the provided snippet to your <code>templates/base.html</code> (or equivalent template). It will look something like this:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="html"><span class="giallo-l"><span style="color: #6A737D;">&lt;!-- Replace both domains: plausible.your-domain.com = your Plausible instance, your-website.com = the site you want to track --&gt;</span></span> <span class="giallo-l"><span>&lt;</span><span style="color: #85E89D;">script</span><span style="color: #B392F0;"> defer src</span><span>=</span><span style="color: #9ECBFF;">&quot;https://plausible.your-domain.com/js/script.js&quot;</span><span style="color: #B392F0;"> data-domain</span><span>=</span><span style="color: #9ECBFF;">&quot;your-website.com&quot;</span><span>&gt;&lt;/</span><span style="color: #85E89D;">script</span><span>&gt;</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ NEW DYNAMIC SNIPPET IN V3 </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Plausible v3 introduced a new, more configurable tracking snippet that is specific to each site. Legacy <code>script.js</code> snippets from older versions will continue to work, but new sites will receive the dynamic format. You can configure tracking options (outbound links, file downloads, tagged events, etc.) directly in the site settings without changing the script URL.</p> </td> </tr> </table> <h2 id="7-maintenance">7. Maintenance</h2> <h3 id="updating-plausible">Updating Plausible</h3> <p>Since we cloned the official repository, updating involves fetching the new version tag and restarting. Your <code>compose.override.yml</code> and <code>.env</code> remain untouched.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/plausible</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Fetch the latest tags from the repository</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> git fetch</span><span style="color: #79B8FF;"> --tags</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Check out the new version (replace v3.x.x with the actual new version tag)</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> git checkout v3.x.x</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Re-apply your override (it&#39;s preserved — just verify it&#39;s still there)</span></span> <span class="giallo-l"><span style="color: #B392F0;">cat</span><span style="color: #9ECBFF;"> compose.override.yml</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Pull the new images and restart</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose pull</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose up</span><span style="color: #79B8FF;"> -d --remove-orphans</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 CHECK RELEASE NOTES </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Always consult the <a rel="noopener external" target="_blank" href="https://github.com/plausible/analytics/releases">official Plausible release notes</a> before updating. Major version upgrades may require changes to your <code>.env</code> or introduce new configuration options.</p> </td> </tr> </table> <h3 id="backing-up">Backing Up</h3> <p>A complete backup consists of the PostgreSQL database (user data, site settings) and the ClickHouse database (analytics events). Since the official setup uses Docker named volumes, we back up via the running containers.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># From your /opt/containers/plausible directory</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 1. Back up the PostgreSQL database</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose exec</span><span style="color: #79B8FF;"> -T</span><span style="color: #9ECBFF;"> plausible_db pg_dump</span><span style="color: #79B8FF;"> -U</span><span style="color: #9ECBFF;"> postgres</span><span style="color: #79B8FF;"> -d</span><span style="color: #9ECBFF;"> plausible_db</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> gzip</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> plausible_pg_backup_</span><span>$(</span><span style="color: #B392F0;">date</span><span style="color: #9ECBFF;"> +%F</span><span>)</span><span style="color: #9ECBFF;">.sql.gz</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 2. Back up the ClickHouse data via a temporary Alpine container</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker run</span><span style="color: #79B8FF;"> --rm \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -v</span><span style="color: #9ECBFF;"> plausible_event-data:/data</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -v</span><span> $(</span><span style="color: #79B8FF;">pwd</span><span>)</span><span style="color: #9ECBFF;">:/backup</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> alpine tar</span><span style="color: #79B8FF;"> -czvf</span><span style="color: #9ECBFF;"> /backup/plausible_clickhouse_backup_</span><span>$(</span><span style="color: #B392F0;">date</span><span style="color: #9ECBFF;"> +%F</span><span>)</span><span style="color: #9ECBFF;">.tar.gz</span><span style="color: #79B8FF;"> -C</span><span style="color: #9ECBFF;"> /data .</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;Backup complete.&quot;</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ BACKUP STRATEGY </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>For a production instance, consider automating this with a cron job. The PostgreSQL dump can run against the live database without stopping services. For ClickHouse, a file-level backup of the named volume is sufficient for smaller instances.</p> </td> </tr> </table> <h3 id="restoring-from-backup">Restoring from Backup</h3> <p>To restore your instance from a backup:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/plausible</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 1. Stop the main application</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose stop plausible</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 2. Restore PostgreSQL</span></span> <span class="giallo-l"><span style="color: #B392F0;">gunzip</span><span style="color: #F97583;"> &lt;</span><span style="color: #9ECBFF;"> plausible_pg_backup_YYYY-MM-DD.sql.gz</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sudo</span><span style="color: #9ECBFF;"> docker compose exec</span><span style="color: #79B8FF;"> -T</span><span style="color: #9ECBFF;"> plausible_db psql</span><span style="color: #79B8FF;"> -U</span><span style="color: #9ECBFF;"> postgres</span><span style="color: #79B8FF;"> -d</span><span style="color: #9ECBFF;"> plausible_db</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 3. Restore ClickHouse (stop ClickHouse first)</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose stop plausible_events_db</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker run</span><span style="color: #79B8FF;"> --rm \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -v</span><span style="color: #9ECBFF;"> plausible_event-data:/data</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> -v</span><span> $(</span><span style="color: #79B8FF;">pwd</span><span>)</span><span style="color: #9ECBFF;">:/backup</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> alpine sh</span><span style="color: #79B8FF;"> -c</span><span style="color: #9ECBFF;"> &quot;rm -rf /data/* &amp;&amp; tar -xzvf /backup/plausible_clickhouse_backup_YYYY-MM-DD.tar.gz -C /data&quot;</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose start plausible_events_db</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 4. Start everything</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose start plausible</span></span></code></pre><h2 id="conclusion">Conclusion</h2> <p>You now have a fully self-hosted, privacy-respecting analytics platform running behind your secure Traefik and CrowdSec stack. By using the official Plausible CE repository as a foundation and adding only a lightweight <code>compose.override.yml</code> for Traefik, your setup is easy to maintain and update — closely following the upstream project without custom workarounds.</p> <p>Plausible gives you all the essential web analytics insights — page views, referrers, locations, devices — without compromising your visitors’ privacy or relying on third-party services. Your data stays on your server, under your control.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;plausible.io&#x2F;docs&#x2F;self-hosting" class="retro-button"> <span class="emoji">📚</span><span class="button-text">PLAUSIBLE SELF-HOSTING DOCS</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;plausible&#x2F;community-edition" class="retro-button"> <span class="emoji">📦</span><span class="button-text">PLAUSIBLE CE ON GITHUB</span> </a> </p> Essential Initial Setup for a Secure Debian Server Tue, 03 Mar 2026 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/debian-server-initial-setup/ https://criticalbasics.xyz/posts/debian-server-initial-setup/ <p>Welcome to the essential security guide for any new Debian server. A fresh installation is a blank slate, and taking the right steps immediately after setup is crucial for protecting your server from threats. This guide provides a logical, step-by-step process to establish a strong security baseline.</p> <p>We will cover user management, hardening SSH access, configuring a firewall, setting up automatic intrusion prevention, and enabling automatic security updates.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ FOLLOW THE ORDER </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>These steps are designed to be followed sequentially. For example, we will set up SSH key authentication <em>before</em> disabling password logins to ensure you don’t lock yourself out.</p> </td> </tr> </table> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2026-03-03</td><td>Comprehensive update: hardened SSH config, added backup strategy, monitoring, and WireGuard.</td></tr> <tr><td>2025-07-10</td><td>Initial version of the comprehensive Debian hardening guide.</td></tr> </tbody></table> </div> <hr /> <h2 id="step-1-initial-login-update-and-hostname">Step 1: Initial Login, Update and Hostname</h2> <p>First, log into your new server as the <code>root</code> user. Your cloud provider will have supplied you with the initial IP address and password.</p> <p>The very first action should always be to update the package list and upgrade all installed packages. For a fresh server, we use <code>full-upgrade</code> to ensure even kernel updates and new dependencies are handled.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Log in as root</span></span> <span class="giallo-l"><span style="color: #B392F0;">ssh</span><span style="color: #9ECBFF;"> root@your_server_ip</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Update package lists</span></span> <span class="giallo-l"><span style="color: #B392F0;">apt</span><span style="color: #9ECBFF;"> update</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Upgrade all installed packages (including kernel updates)</span></span> <span class="giallo-l"><span style="color: #B392F0;">apt</span><span style="color: #9ECBFF;"> full-upgrade</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Reboot to ensure the new kernel and all updates are active</span></span> <span class="giallo-l"><span style="color: #B392F0;">reboot</span></span></code></pre> <p>After the reboot, log back in. It’s best practice to set the hostname immediately so all subsequent logs reflect the correct name.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Set your server&#39;s hostname</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> hostnamectl set-hostname my-awesome-server</span></span></code></pre> <p>You should also edit <code>/etc/hosts</code> to associate the new hostname with <code>127.0.1.1</code>.</p> <hr /> <h2 id="step-2-create-a-dedicated-admin-user">Step 2: Create a Dedicated Admin User</h2> <p>Operating directly as the <code>root</code> user is risky. We will create a new user account with administrative privileges via the <code>sudo</code> command. This improves security and provides better auditing.</p> <p>Replace <code>adminuser</code> with a username of your choice.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Create a new user</span></span> <span class="giallo-l"><span style="color: #B392F0;">adduser</span><span style="color: #9ECBFF;"> adminuser</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># You will be prompted to set a password and fill in user information.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Add the new user to the &#39;sudo&#39; group</span></span> <span class="giallo-l"><span style="color: #B392F0;">usermod</span><span style="color: #79B8FF;"> -aG</span><span style="color: #9ECBFF;"> sudo adminuser</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Log out from the root session</span></span> <span class="giallo-l"><span style="color: #79B8FF;">exit</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ SUDO PASSWORD SECURITY </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>By default, <code>sudo</code> will ask for your user password before executing administrative commands. Do not configure <code>NOPASSWD</code> for your admin user. This password prompt prevents accidental destructive commands and is an additional authentication layer if your SSH session is compromised.</p> </td> </tr> </table> <p>From now on, you will log in as this new user and prefix any administrative commands with <code>sudo</code>.</p> <hr /> <h2 id="step-3-harden-ssh-access">Step 3: Harden SSH Access</h2> <p>Securing SSH is the single most effective thing you can do to protect your server. While we will change the default port to reduce log noise from automated scanners, the real security comes from key-only authentication and the hardening settings below.</p> <h3 id="3-1-set-up-ssh-key-authentication">3.1. Set Up SSH Key Authentication</h3> <p>SSH keys are far more secure than passwords. A key pair consists of a private key (which you keep on your local computer) and a public key (which you place on the server).</p> <p><strong>On your local computer (not the server):</strong> If you don’t have an SSH key pair yet, generate one. The <code>ed25519</code> algorithm is modern and highly secure.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># This command is run on your local machine</span></span> <span class="giallo-l"><span style="color: #B392F0;">ssh-keygen</span><span style="color: #79B8FF;"> -t</span><span style="color: #9ECBFF;"> ed25519</span><span style="color: #79B8FF;"> -C</span><span style="color: #9ECBFF;"> &quot;your_email@example.com&quot;</span></span></code></pre> <p>Press Enter to accept the default file location and set an optional (but recommended) passphrase for your key.</p> <p><strong>Copy your public key to the server:</strong> The <code>ssh-copy-id</code> command is the easiest way to do this. It will automatically add your public key to the correct file on the server.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Replace with your new username and server IP</span></span> <span class="giallo-l"><span style="color: #B392F0;">ssh-copy-id</span><span style="color: #9ECBFF;"> adminuser@your_server_ip</span></span></code></pre> <p>After this, you should be able to log into your server as <code>adminuser</code> without being asked for a password (you might be asked for your key’s passphrase if you set one).</p> <h3 id="3-2-configure-and-secure-the-ssh-daemon">3.2. Configure and Secure the SSH Daemon</h3> <p>Now we will edit the main SSH configuration file to improve security.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ DO NOT CLOSE YOUR TERMINAL! </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Keep your current SSH session open while performing these steps. If you make a mistake, you can revert the changes. Only close the terminal after you have successfully tested the new login method in a separate terminal window.</p> </td> </tr> </table> <p>Open the configuration file with a text editor:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> vim /etc/ssh/sshd_config</span></span></code></pre> <p>Make the following changes to harden the configuration:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Change port (optional, reduces log noise from bots)</span></span> <span class="giallo-l"><span style="color: #B392F0;">Port</span><span style="color: #79B8FF;"> 8496</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Authentication</span></span> <span class="giallo-l"><span style="color: #B392F0;">PermitRootLogin</span><span style="color: #9ECBFF;"> no</span></span> <span class="giallo-l"><span style="color: #B392F0;">PasswordAuthentication</span><span style="color: #9ECBFF;"> no</span></span> <span class="giallo-l"><span style="color: #B392F0;">PubkeyAuthentication</span><span style="color: #9ECBFF;"> yes</span></span> <span class="giallo-l"><span style="color: #B392F0;">MaxAuthTries</span><span style="color: #79B8FF;"> 3</span></span> <span class="giallo-l"><span style="color: #B392F0;">LoginGraceTime</span><span style="color: #79B8FF;"> 30</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Restrict to specific user(s)</span></span> <span class="giallo-l"><span style="color: #B392F0;">AllowUsers</span><span style="color: #9ECBFF;"> adminuser</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Disable unnecessary features</span></span> <span class="giallo-l"><span style="color: #B392F0;">X11Forwarding</span><span style="color: #9ECBFF;"> no</span></span> <span class="giallo-l"><span style="color: #B392F0;">AllowTcpForwarding</span><span style="color: #9ECBFF;"> no</span></span> <span class="giallo-l"><span style="color: #B392F0;">AllowAgentForwarding</span><span style="color: #9ECBFF;"> no</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Restrict key algorithms to modern, secure options</span></span> <span class="giallo-l"><span style="color: #B392F0;">PubkeyAcceptedAlgorithms</span><span style="color: #9ECBFF;"> ssh-ed25519,sk-ssh-ed25519@openssh.com</span></span></code></pre> <p><strong>Key explanations for these options:</strong></p> <ul> <li><strong>MaxAuthTries 3</strong> — Limits login attempts per connection to 3.</li> <li><strong>LoginGraceTime 30</strong> — Disconnects after 30 seconds without successful authentication.</li> <li><strong>AllowUsers adminuser</strong> — Only the specified user(s) can log in via SSH.</li> <li><strong>X11Forwarding no</strong> — Disables GUI forwarding, reducing attack surface.</li> <li><strong>AllowTcp/AgentForwarding no</strong> — Prevents SSH tunneling and potential agent exploitation.</li> <li><strong>PubkeyAcceptedAlgorithms</strong> — Restricts to Ed25519 and FIDO2/Hardware keys (YubiKey).</li> </ul> <p>Save the file and exit the editor.</p> <h3 id="3-3-test-and-restart-ssh">3.3. Test and Restart SSH</h3> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ CRITICAL: TEST BEFORE RESTART </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Always validate your configuration before restarting the SSH daemon. A syntax error can lead to a permanent lockout.</p> </td> </tr> </table> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># ALWAYS test configuration before restarting</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> sshd</span><span style="color: #79B8FF;"> -t</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Only if no errors are shown, restart the service:</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> systemctl restart sshd.service</span></span></code></pre> <p>Now, <strong>open a new terminal window</strong> and try to connect using the new port and your key.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Use your username, IP, and the new port number</span></span> <span class="giallo-l"><span style="color: #B392F0;">ssh</span><span style="color: #9ECBFF;"> adminuser@your_server_ip</span><span style="color: #79B8FF;"> -p 8496</span></span></code></pre> <p>If the login is successful, your SSH hardening is complete. You can now safely close the old terminal window.</p> <h2 id="step-4-configure-a-firewall-with-ufw">Step 4: Configure a Firewall with UFW</h2> <p>A firewall is essential for controlling network traffic. We will use UFW (Uncomplicated Firewall) because it is user-friendly and effective.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Install UFW</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt install ufw</span></span></code></pre> <p>Next, we will set up some basic rules. By default, we will deny all incoming traffic and allow all outgoing traffic. Then we will explicitly allow traffic for the services we need.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Set default policies</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw default deny incoming</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw default allow outgoing</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Allow standard web traffic</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow http</span><span style="color: #6A737D;"> # Port 80</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow https</span><span style="color: #6A737D;"> # Port 443</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># IMPORTANT: Allow your new SSH port</span></span> <span class="giallo-l"><span style="color: #6A737D;"># We use &#39;limit&#39; to help protect against brute-force attacks</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw limit 8496/tcp</span><span style="color: #6A737D;"> # Use the port you chose</span></span></code></pre> <p>Now, enable the firewall. It will ask for confirmation to proceed.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw enable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Check the status of the firewall at any time</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw status verbose</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 CLOUD FIREWALL </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Cloud providers like Hetzner, DigitalOcean, or AWS offer cloud-level firewalls in their web panel. These filter traffic before it reaches your server. If available, mirror your UFW rules there as an additional layer.</p> </td> </tr> </table> <hr /> <h2 id="step-5-prevent-intrusion-with-fail2ban">Step 5: Prevent Intrusion with Fail2Ban</h2> <p>With key-only SSH authentication, brute-force attacks against SSH are already neutralized. So why Fail2Ban? Because your server will likely run more than SSH. Once you deploy a web server, mail server, or other services, Fail2Ban protects those too. It is a general-purpose intrusion prevention tool.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Install Fail2Ban</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt install fail2ban</span></span></code></pre> <p>Fail2Ban’s configuration should be done in a local file, which overrides the default settings without being changed during package updates.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Create a local configuration file</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local</span></span></code></pre> <p>Now, edit the new local file to configure it for our custom SSH port.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> vim /etc/fail2ban/jail.local</span></span></code></pre> <p>Find the <code>[sshd]</code> section. Most settings can be left as default, but you must update the <code>port</code> to match your custom SSH port and ensure it’s enabled.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #B392F0;">[sshd]</span></span> <span class="giallo-l"><span style="color: #F97583;">enabled</span><span> = true</span></span> <span class="giallo-l"><span style="color: #F97583;">port</span><span> = 8496</span></span> <span class="giallo-l"><span style="color: #F97583;">maxretry</span><span> = 3</span></span> <span class="giallo-l"><span style="color: #F97583;">bantime</span><span> = 1h</span></span> <span class="giallo-l"><span style="color: #F97583;">findtime</span><span> = 10m</span></span></code></pre> <p>Save the file and restart Fail2Ban to apply the changes.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> systemctl restart fail2ban</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Check the status of the SSH jail</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> fail2ban-client status sshd</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 VERSATILE PROTECTION </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Fail2Ban is incredibly powerful. You can configure it to protect many other services, such as web servers (Nginx, Apache) or mail servers, by creating custom jails.</p> </td> </tr> </table> <hr /> <h2 id="step-6-automate-security-updates">Step 6: Automate Security Updates</h2> <p>Even with a hardened server, new vulnerabilities are discovered all the time. It is vital to install security updates promptly. The <code>unattended-upgrades</code> package can do this for you automatically.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Install the package</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt install unattended-upgrades apt-listchanges</span></span></code></pre> <p>Now, run the configuration wizard to enable it.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># This will open a simple text-based interface</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> dpkg-reconfigure</span><span style="color: #79B8FF;"> -plow</span><span style="color: #9ECBFF;"> unattended-upgrades</span></span></code></pre> <p>Select <strong>“Yes”</strong> to enable automatic updates. This will create a configuration file that tells the system to automatically install packages from Debian’s security repository.</p> <p>To further harden this, you can configure email notifications and an automatic reboot policy (essential for kernel updates) in <code>/etc/apt/apt.conf.d/50unattended-upgrades</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span># Email notification (requires a working mail setup like msmtp)</span></span> <span class="giallo-l"><span>Unattended-Upgrade::Mail &quot;your@email.com&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Automatic reboot policy (e.g., at 04:00 AM)</span></span> <span class="giallo-l"><span>Unattended-Upgrade::Automatic-Reboot &quot;true&quot;;</span></span> <span class="giallo-l"><span>Unattended-Upgrade::Automatic-Reboot-Time &quot;04:00&quot;;</span></span></code></pre> <hr /> <h2 id="step-7-final-system-housekeeping">Step 7: Final System Housekeeping</h2> <p>A few final touches will make your server easier to manage.</p> <p><strong>1. Set the Timezone:</strong> Correct log timestamps are crucial for troubleshooting.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Set your timezone, e.g., for Berlin</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> timedatectl set-timezone Europe/Berlin</span></span></code></pre> <p><strong>2. Install Useful Tools:</strong> These small utilities are incredibly helpful for administration.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt install htop ncdu curl git</span></span></code></pre> <ul> <li><code>htop</code>: An interactive process viewer.</li> <li><code>ncdu</code>: A disk usage analyzer to easily find large files.</li> <li><code>curl</code>: A tool for transferring data with URLs.</li> <li><code>git</code>: Version control system, often needed to download software.</li> </ul> <hr /> <h2 id="step-8-basic-monitoring-and-logging">Step 8: Basic Monitoring and Logging</h2> <p>A secure server is one where you <em>notice</em> when something goes wrong.</p> <h3 id="8-1-persistent-journal-logging">8.1. Persistent Journal Logging</h3> <p>On some Debian installations, journal logs are lost upon reboot. This makes them persistent:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> /var/log/journal</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> systemd-tmpfiles</span><span style="color: #79B8FF;"> --create --prefix</span><span style="color: #9ECBFF;"> /var/log/journal</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> systemctl restart systemd-journald</span></span></code></pre><h3 id="8-2-logwatch-optional">8.2. Logwatch (Optional)</h3> <p>Logwatch provides a daily summary of SSH attempts, disk usage, and service errors.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt install logwatch</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> logwatch</span><span style="color: #79B8FF;"> --detail</span><span style="color: #9ECBFF;"> Med</span><span style="color: #79B8FF;"> --range</span><span style="color: #9ECBFF;"> yesterday</span><span style="color: #79B8FF;"> --output</span><span style="color: #9ECBFF;"> stdout</span></span></code></pre><h3 id="8-3-monitoring-disk-space">8.3. Monitoring Disk Space</h3> <p>Full disks are a common cause of service failures.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">df</span><span style="color: #79B8FF;"> -h</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ncdu /</span></span></code></pre> <hr /> <h2 id="step-9-backup-strategy">Step 9: Backup Strategy</h2> <p>Security = <strong>Prevent</strong> + <strong>Detect</strong> + <strong>Recover</strong>. A server without a backup is not truly secure.</p> <h3 id="core-principles">Core Principles</h3> <ol> <li><strong>Provider Snapshots:</strong> Enable them as your first layer of defense.</li> <li><strong>Application-Level Backups:</strong> Use tools like <code>borgbackup</code> or <code>restic</code>.</li> <li><strong>3-2-1 Rule:</strong> 3 copies, 2 different media, 1 offsite.</li> <li><strong>Test Restores:</strong> A backup is only as good as its last successful restore.</li> </ol> <p><strong>Example with BorgBackup:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt install borgbackup</span></span> <span class="giallo-l"><span style="color: #B392F0;">borg</span><span style="color: #9ECBFF;"> init</span><span style="color: #79B8FF;"> --encryption=repokey</span><span style="color: #9ECBFF;"> /path/to/backup/repo</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Note: Adjust paths like /var/lib depending on your data volume (e.g., Docker volumes, databases).</span></span> <span class="giallo-l"><span style="color: #B392F0;">borg</span><span style="color: #9ECBFF;"> create /path/to/backup/repo::</span><span>$(</span><span style="color: #B392F0;">date</span><span style="color: #9ECBFF;"> +%Y-%m-%d</span><span>)</span><span style="color: #9ECBFF;"> /etc /home /var/lib</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Verify your backup</span></span> <span class="giallo-l"><span style="color: #B392F0;">borg</span><span style="color: #9ECBFF;"> list /path/to/backup/repo</span></span></code></pre> <hr /> <h2 id="step-10-optional-maximum-security-ssh-via-wireguard">Step 10 (Optional): Maximum Security — SSH via WireGuard</h2> <p>For maximum security, do not expose SSH publicly at all. Access your server through a WireGuard VPN tunnel; SSH then listens only on the VPN interface. This eliminates scanning and brute-force attacks entirely.</p> <h3 id="10-1-setup-wireguard-server">10.1. Setup WireGuard Server</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt install wireguard</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Create directory with restricted permissions first</span></span> <span class="giallo-l"><span style="color: #79B8FF;">umask 077</span></span> <span class="giallo-l"><span style="color: #B392F0;">wg</span><span style="color: #9ECBFF;"> genkey</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> tee</span><span style="color: #9ECBFF;"> /etc/wireguard/server_private.key</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> wg</span><span style="color: #9ECBFF;"> pubkey</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /etc/wireguard/server_public.key</span></span></code></pre> <p><em>(Note: The <code>tee</code> command outputs the private key to your terminal. Do not share this output.)</em></p> <h3 id="10-2-server-configuration">10.2. Server Configuration</h3> <p>Create <code>/etc/wireguard/wg0.conf</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #B392F0;">[Interface]</span></span> <span class="giallo-l"><span style="color: #F97583;">Address</span><span> = 10.0.0.1/24</span></span> <span class="giallo-l"><span style="color: #F97583;">ListenPort</span><span> = 51820</span></span> <span class="giallo-l"><span style="color: #F97583;">PrivateKey</span><span> = &lt;contents of server_private.key&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">[Peer]</span></span> <span class="giallo-l"><span style="color: #F97583;">PublicKey</span><span> = &lt;client_public_key&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;">AllowedIPs</span><span> = 10.0.0.2/32</span></span></code></pre> <p>Enable the service:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> systemctl enable wg-quick@wg0</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> systemctl start wg-quick@wg0</span></span></code></pre><h3 id="10-3-restrict-ssh-to-vpn">10.3. Restrict SSH to VPN</h3> <p>In <code>/etc/ssh/sshd_config</code>, set:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">ListenAddress</span><span style="color: #79B8FF;"> 10.0.0.1</span></span></code></pre> <p>Test and restart:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> sshd</span><span style="color: #79B8FF;"> -t</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> systemctl restart sshd.service</span></span></code></pre><h3 id="10-4-update-firewall">10.4. Update Firewall</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 51820/udp</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw delete limit 8496/tcp</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ WARNING </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>After this change, SSH is ONLY reachable via WireGuard. Ensure your VPN connection works before closing your session.</p> </td> </tr> </table> <h3 id="10-5-client-configuration">10.5. Client Configuration</h3> <p>To connect to your newly secured server, you will need to configure a WireGuard client on your local machine using the public key from the server and a newly generated client key pair:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #6A737D;"># /etc/wireguard/wg0.conf on client</span></span> <span class="giallo-l"><span style="color: #B392F0;">[Interface]</span></span> <span class="giallo-l"><span style="color: #F97583;">Address</span><span> = 10.0.0.2/24</span></span> <span class="giallo-l"><span style="color: #F97583;">PrivateKey</span><span> = &lt;client_private_key&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">[Peer]</span></span> <span class="giallo-l"><span style="color: #F97583;">PublicKey</span><span> = &lt;server_public_key&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;">Endpoint</span><span> = your_server_ip:51820</span></span> <span class="giallo-l"><span style="color: #F97583;">AllowedIPs</span><span> = 10.0.0.1/32</span></span></code></pre> <hr /> <h2 id="conclusion">Conclusion</h2> <p>Congratulations! You have successfully performed the essential first steps to harden your new Debian server. By creating a sudo user, securing SSH with key authentication, and setting up a firewall and intrusion prevention system, you have built a solid foundation for any application you wish to deploy.</p> <p>Combined with monitoring, a solid backup strategy, and optionally a VPN-secured access layer, your server is well-prepared for production use. Your server is now significantly more resistant to common automated attacks and hardware failures.</p> <!-- Retro-Trennlinie Shortcode - Kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: retro_divider(style="dots") --> <!-- Styles: dots, double, dashed, solid, shadow --> <hr size="2" noshade color="#666666" style="margin: 15px 0; border-style: double;"> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ WHAT&#x27;S NEXT? </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>With this secure base, you are now ready to install your applications, such as a web server (Nginx/Apache), a database, or a Docker environment.</p> </td> </tr> </table> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;www.debian.org&#x2F;doc&#x2F;manuals&#x2F;securing-debian-manual&#x2F;" class="retro-button"> <span class="emoji">📚</span><span class="button-text">OFFICIAL DEBIAN SECURITY MANUAL</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;wiki.debian.org&#x2F;Fail2ban" class="retro-button"> <span class="emoji">🛡️</span><span class="button-text">DEBIAN WIKI: FAIL2BAN</span> </a> </p> Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack Tue, 03 Mar 2026 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/traefik-v3-crowdsec-tutorial/ https://criticalbasics.xyz/posts/traefik-v3-crowdsec-tutorial/ <p>This guide provides a streamlined approach to deploying a powerful and secure web stack using Traefik as a reverse proxy and CrowdSec for threat protection. We will use Docker Compose to orchestrate the services, creating a setup that is easy to manage, scale, and maintain.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2026-03-03</td><td><strong>Security Fix:</strong> Added <code>forwardedHeaders.trustedIPs</code> to both entrypoints to prevent X-Forwarded-For spoofing.</td></tr> <tr><td>2026-03-03</td><td><strong>Component Updates &amp; Syntax Fixes:</strong> Updated Traefik to v3.6, CrowdSec plugin to v1.4.7, and pinned CrowdSec to v1.6. Fixed Traefik v3 <code>HostRegexp</code> syntax and improved healthchecks.</td></tr> <tr><td>2026-01-26</td><td><strong>Robustness Update:</strong> Added AccessLog filtering to prevent disk exhaustion and improved logrotate instructions with path discovery.</td></tr> <tr><td>2026-01-15</td><td><strong>Docs Update:</strong> Removed redundant <code>router.tls=true</code> label from the bypass example and added a new section explaining how to route multiple (sub)domains to one service.</td></tr> <tr><td>2025-12-10</td><td><strong>Production Hardening:</strong> Added comprehensive log rotation configuration and disk troubleshooting section based on real-world feedback.</td></tr> <tr><td>2025-09-18</td><td><strong>Final Review:</strong> Switched to robust httpChallenge, corrected provider in example, added raw API key generation.</td></tr> <tr><td>2025-09-17</td><td><strong>Major Refactor:</strong> Switched from legacy bouncer container to modern Traefik Plugin. Moved all variable configs to Docker Labels.</td></tr> <tr><td>2025-07-10</td><td><strong>Added Special Use-Case:</strong> Included a clear example of how to deploy a service <em>without</em> CrowdSec protection for specific needs.</td></tr> <tr><td>2025-07-09</td><td><strong>Initial Version:</strong> Article created based on best practices for a modern Traefik v3 and CrowdSec deployment with Docker Compose.</td></tr> </tbody></table> </div> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>Before you begin, ensure you have the following installed on your server (e.g., Ubuntu 22.04 or Debian 12):</p> <ul> <li><strong>Docker</strong> and <strong>Docker Compose</strong></li> <li><code>curl</code>, <code>openssl</code>, and <code>apache2-utils</code> (for password generation)</li> <li>A domain name pointed to your server’s IP address</li> <li>Open firewall ports <code>80</code> and <code>443</code></li> <li><code>sudo</code> or root access</li> </ul> <p>You can install the required utilities with:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt update</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt install</span><span style="color: #79B8FF;"> -y</span><span style="color: #9ECBFF;"> curl openssl apache2-utils</span></span></code></pre><h2 id="2-directory-structure">2. Directory Structure</h2> <p>A well-organized directory structure is key. We will create a central location for our stack’s configuration and data.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Create the main directory</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> /opt/containers/traefik-stack</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/traefik-stack</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Create directories for each service</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> traefik/{dynamic,logs,certs}</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> crowdsec/{config,data}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Prepare Let&#39;s Encrypt certificates file</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> touch traefik/certs/acme.json</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> chmod</span><span style="color: #79B8FF;"> 600</span><span style="color: #9ECBFF;"> traefik/certs/acme.json</span></span></code></pre> <p>This structure keeps everything tidy and separated.</p> <h2 id="3-configuration-files">3. Configuration Files</h2> <p>Now, let’s create the configuration files for our stack.</p> <h3 id="3-1-main-configuration-env">3.1. Main Configuration (<code>.env</code>)</h3> <p>This file holds all your environment-specific variables.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee .env</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># --- General Settings ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">TZ=Europe/Berlin</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">DOMAIN_NAME=your-domain.com</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"># --- Traefik Settings ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">TRAEFIK_DASHBOARD_HOST=traefik.${DOMAIN_NAME}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">LETSENCRYPT_EMAIL=your-email@example.com</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"># --- CrowdSec Settings ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">CROWDSEC_COLLECTIONS=&quot;crowdsecurity/traefik crowdsecurity/linux&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"># --- Credentials ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">CROWDSEC_BOUNCER_API_KEY=PASTE-YOUR-GENERATED-KEY-HERE</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ IMPORTANT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Replace <code>your-domain.com</code>, <code>your-email@example.com</code>. The API key will be generated and pasted in a later step.</p> </td> </tr> </table> <h3 id="3-2-traefik-static-configuration-traefik-yml">3.2. Traefik Static Configuration (<code>traefik.yml</code>)</h3> <p>This file contains the core Traefik settings that rarely change.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee traefik.yml</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">global:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> checkNewVersion: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> sendAnonymousUsage: false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">api:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> dashboard: true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">ping: {}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">entryPoints:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> web:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> address: &quot;:80&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> http:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> redirections:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> entryPoint:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> to: websecure</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> scheme: https</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> forwardedHeaders:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> insecure: false</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> trustedIPs:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;127.0.0.1/32&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;10.0.0.0/8&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;172.16.0.0/12&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;192.168.0.0/16&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> websecure:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> address: &quot;:443&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> forwardedHeaders:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> insecure: false</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> trustedIPs:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;127.0.0.1/32&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;10.0.0.0/8&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;172.16.0.0/12&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;192.168.0.0/16&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">providers:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> docker:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> endpoint: &quot;unix:///var/run/docker.sock&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> exposedByDefault: false</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> file:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> directory: /etc/traefik/dynamic</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> watch: true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">experimental:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> plugins:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> crowdsec-bouncer:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> moduleName: github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> version: v1.4.7</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">certificatesResolvers:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> tls_resolver:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> acme:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> storage: /certs/acme.json</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> httpChallenge:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> entryPoint: web</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">log:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> level: INFO</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> filePath: /var/log/traefik/traefik.log</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">accessLog:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> filePath: /var/log/traefik/access.log</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> format: json</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> filters:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> statusCodes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;400-599&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> fields:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> headers:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> defaultMode: keep</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><h3 id="3-2-1-forwarded-headers-trusted-ips">3.2.1. Forwarded Headers (Trusted IPs)</h3> <p>Traefik acts as a reverse proxy in front of your applications. To ensure your apps see the real client IP (and not the internal Docker gateway IP), Traefik must correctly process the <code>X-Forwarded-For</code> header.</p> <p><strong>Without this configuration</strong>, any visitor can spoof the <code>X-Forwarded-For</code> header, bypassing IP-based rate limiting, abuse protection, or geo-blocking.</p> <p><strong>What do these entries in <code>traefik.yml</code> mean?</strong></p> <ul> <li><code>insecure: false</code> — Traefik does not automatically trust all incoming <code>X-Forwarded-For</code> headers. This is the default, but we set it explicitly for clarity.</li> <li><code>trustedIPs</code> — Traefik only accepts the forwarded header from these source IPs. For all other requests, Traefik overwrites the header with the actual sender IP.</li> <li>The four ranges cover the loopback interface (127.0.0.1) and all private network ranges (used for internal Docker communication).</li> </ul> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ UPSTREAM PROXIES </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>If you run a load balancer or CDN in front of Traefik, you must add its IP ranges as well. Examples:</p> <ul> <li><strong>Hetzner Load Balancer:</strong> The private IPs of the LB within the same network (e.g., <code>10.0.0.0/8</code> already covers this if the LB is in the same private network). Alternatively, explicitly add the public LB IP.</li> <li><strong>Cloudflare:</strong> Add the official Cloudflare IP ranges. See <a rel="noopener external" target="_blank" href="https://www.cloudflare.com/ips/">https://www.cloudflare.com/ips/</a>. Traefik also offers the shorthand <code>cloudflare</code> as a provider for this (undocumented, better to set the ranges explicitly).</li> <li><strong>AWS ALB / NLB:</strong> The VPC subnet ranges of the load balancer.</li> </ul> <p>Without the correct IPs, your application will see the load balancer’s IP instead of the client’s IP.</p> </td> </tr> </table> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ NEVER USE INSECURE: TRUE </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The setting <code>insecure: true</code> causes Traefik to accept the <code>X-Forwarded-For</code> header from <strong>any</strong> source — even directly from the internet. This opens the door for IP spoofing and should never be used in production.</p> </td> </tr> </table> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ PLUGIN NAMING CONVENTION </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The plugin is defined here under the name <code>crowdsec-bouncer</code>. You will often see the official CrowdSec documentation refer to it simply as <code>bouncer</code>. Both work perfectly, as long as you are consistent when referencing it in your Docker labels later on.</p> </td> </tr> </table> <h3 id="3-3-traefik-dynamic-configuration-dynamic-middlewares-yml">3.3. Traefik Dynamic Configuration (<code>dynamic/middlewares.yml</code>)</h3> <p>This file defines reusable middleware components.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee traefik/dynamic/middlewares.yml</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">http:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> middlewares:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # 1. General security headers</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> security-headers:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> headers:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> browserXssFilter: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> contentTypeNosniff: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> frameDeny: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> forceSTSHeader: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> stsIncludeSubdomains: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> stsPreload: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> stsSeconds: 31536000</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # 2. Basic Auth for the dashboard</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> traefik-dashboard-auth:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> basicAuth:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> usersFile: &quot;/etc/traefik/dynamic/.htpasswd&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><h3 id="3-4-docker-compose-docker-compose-yml">3.4. Docker Compose (<code>docker-compose.yml</code>)</h3> <p>This is the main file defining our services.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee docker-compose.yml</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">services:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> traefik:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: traefik:v3.6</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: traefik</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ports:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;80:80&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;443:443&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> command:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - --certificatesresolvers.tls_resolver.acme.email=${LETSENCRYPT_EMAIL}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - proxy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - /var/run/docker.sock:/var/run/docker.sock:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./traefik.yml:/etc/traefik/traefik.yml:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./traefik/dynamic:/etc/traefik/dynamic:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./traefik/certs:/certs</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./traefik/logs:/var/log/traefik</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> environment:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - TZ=${TZ}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> labels:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.middlewares.crowdsec-bouncer.plugin.crowdsec-bouncer.crowdsecMode=stream&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.middlewares.crowdsec-bouncer.plugin.crowdsec-bouncer.crowdsecLapiHost=crowdsec:8080&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.middlewares.crowdsec-bouncer.plugin.crowdsec-bouncer.crowdsecLapiKey=${CROWDSEC_BOUNCER_API_KEY}&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.dashboard.rule=Host(`${TRAEFIK_DASHBOARD_HOST}`)&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.dashboard.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.dashboard.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.dashboard.service=api@internal&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.dashboard.middlewares=traefik-dashboard-auth@file,crowdsec-bouncer@docker&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> healthcheck:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> test: [&quot;CMD&quot;, &quot;traefik&quot;, &quot;healthcheck&quot;, &quot;--ping&quot;]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> interval: 30s</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> timeout: 10s</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> retries: 3</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> crowdsec:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: crowdsecurity/crowdsec:latest</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: crowdsec</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - proxy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - /var/run/docker.sock:/var/run/docker.sock:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./crowdsec/config:/etc/crowdsec:z</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./crowdsec/data:/var/lib/crowdsec/data:z</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./traefik/logs:/var/log/traefik:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - /var/log:/var/log/host/:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> environment:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - TZ=${TZ}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - COLLECTIONS=${CROWDSEC_COLLECTIONS}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> healthcheck:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> test: [&quot;CMD&quot;, &quot;cscli&quot;, &quot;version&quot;]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> interval: 60s</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> timeout: 15s</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> retries: 3</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> name: proxy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> external: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ DOCKER SOCKET SECURITY </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Mounting <code>/var/run/docker.sock</code> directly gives the container root-equivalent access to the Docker daemon. For a production-hardened setup, consider using a Docker Socket Proxy (like <code>tecnativa/docker-socket-proxy</code>) to restrict Traefik to read-only access for essential API endpoints.</p> </td> </tr> </table> <h3 id="3-5-create-dashboard-password">3.5. Create Dashboard Password</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> htpasswd</span><span style="color: #79B8FF;"> -c</span><span style="color: #9ECBFF;"> traefik/dynamic/.htpasswd admin</span></span></code></pre><h3 id="3-6-crowdsec-acquisition-configuration-crowdsec-config-acquis-yaml">3.6. CrowdSec Acquisition Configuration (<code>crowdsec/config/acquis.yaml</code>)</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee crowdsec/config/acquis.yaml</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">filenames:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - /var/log/traefik/access.log</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">labels:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> type: traefik</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">filenames:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - /var/log/host/auth.log</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - /var/log/host/syslog</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">labels:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> type: syslog</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><h2 id="4-launch-and-verify-the-stack">4. Launch and Verify the Stack</h2> <ol> <li><strong>Create the external network:</strong><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> network create proxy</span></span></code></pre></li> <li><strong>Start the services:</strong><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose up</span><span style="color: #79B8FF;"> -d</span></span></code></pre>Upon first launch, Traefik will request a certificate from Let’s Encrypt. This may take a minute.</li> <li><strong>Generate the Bouncer API Key:</strong><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose exec crowdsec cscli bouncers add traefik</span><span style="color: #79B8FF;"> -o</span><span style="color: #9ECBFF;"> raw</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ LAPI STARTUP TIME </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Upon the very first start, CrowdSec might take a few moments to initialize the Local API (LAPI). If you get a connection error, wait 10-20 seconds and try the command again.</p> </td> </tr> </table> Copy the long, alphanumeric string that is output.</li> <li><strong>Update your <code>.env</code> file:</strong> Paste the copied key as the value for <code>CROWDSEC_BOUNCER_API_KEY</code>.</li> <li><strong>Restart Traefik to apply the key:</strong><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose up</span><span style="color: #79B8FF;"> -d --force-recreate</span><span style="color: #9ECBFF;"> traefik</span></span></code></pre></li> <li><strong>Verify the bouncer connection:</strong><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose exec crowdsec cscli bouncers list</span></span></code></pre>You should see the <code>traefik</code> bouncer listed. You can now access your dashboard at <code>https://traefik.your-domain.com</code>.</li> </ol> <h2 id="5-adding-services-to-traefik">5. Adding Services to Traefik</h2> <p>Here is how to expose other Docker services through Traefik, with and without CrowdSec protection.</p> <h3 id="5-1-scenario-1-service-protected-by-crowdsec-standard">5.1. Scenario 1: Service Protected by CrowdSec (Standard)</h3> <p>This is the recommended setup for most public-facing services. We’ll use WordPress as an example. Create a <code>docker-compose.yml</code> in a separate directory (e.g., <code>/opt/containers/wordpress</code>):</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #85E89D;">services</span><span>:</span></span> <span class="giallo-l"><span style="color: #85E89D;"> wordpress</span><span>:</span></span> <span class="giallo-l"><span style="color: #85E89D;"> image</span><span>:</span><span style="color: #9ECBFF;"> wordpress:latest</span></span> <span class="giallo-l"><span style="color: #85E89D;"> restart</span><span>:</span><span style="color: #9ECBFF;"> unless-stopped</span></span> <span class="giallo-l"><span style="color: #85E89D;"> networks</span><span>:</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> default</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> proxy</span></span> <span class="giallo-l"><span style="color: #85E89D;"> labels</span><span>:</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.wordpress.rule=Host(`blog.your-domain.com`)&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.wordpress.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.wordpress.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.wordpress.middlewares=security-headers@file,crowdsec-bouncer@docker&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.services.wordpress.loadbalancer.server.port=80&quot;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #85E89D;"> db</span><span>:</span></span> <span class="giallo-l"><span style="color: #85E89D;"> image</span><span>:</span><span style="color: #9ECBFF;"> mariadb:11</span></span> <span class="giallo-l"><span style="color: #85E89D;"> restart</span><span>:</span><span style="color: #9ECBFF;"> unless-stopped</span></span> <span class="giallo-l"><span style="color: #85E89D;"> environment</span><span>:</span></span> <span class="giallo-l"><span style="color: #85E89D;"> MYSQL_ROOT_PASSWORD</span><span>:</span><span style="color: #9ECBFF;"> change-me</span></span> <span class="giallo-l"><span style="color: #85E89D;"> MYSQL_DATABASE</span><span>:</span><span style="color: #9ECBFF;"> wordpress</span></span> <span class="giallo-l"><span style="color: #85E89D;"> MYSQL_USER</span><span>:</span><span style="color: #9ECBFF;"> wordpress</span></span> <span class="giallo-l"><span style="color: #85E89D;"> MYSQL_PASSWORD</span><span>:</span><span style="color: #9ECBFF;"> supersecret</span></span> <span class="giallo-l"><span style="color: #85E89D;"> volumes</span><span>:</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> db_data:/var/lib/mysql</span></span> <span class="giallo-l"><span style="color: #85E89D;"> networks</span><span>:</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> default</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #85E89D;">networks</span><span>:</span></span> <span class="giallo-l"><span style="color: #85E89D;"> proxy</span><span>:</span></span> <span class="giallo-l"><span style="color: #85E89D;"> external</span><span>:</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #85E89D;"> default</span><span>:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #85E89D;">volumes</span><span>:</span></span> <span class="giallo-l"><span style="color: #85E89D;"> db_data</span><span>:</span></span></code></pre> <p>The key label is <code>traefik.http.routers.wordpress.middlewares=security-headers@file,crowdsec-bouncer@docker</code>, which applies our security headers (from the file provider) and the CrowdSec bouncer (defined on the Traefik service via Docker labels).</p> <h3 id="5-2-scenario-2-service-bypassing-crowdsec-special-case">5.2. Scenario 2: Service Bypassing CrowdSec (Special Case)</h3> <p>Sometimes you need to expose a service without CrowdSec’s interference. Common reasons include:</p> <ul> <li>A public API that must not be blocked.</li> <li>A site heavily reliant on ad network traffic, where false positives could impact revenue.</li> <li>Internal tools that are already secured by other means.</li> </ul> <p>To bypass CrowdSec, simply omit the <code>crowdsec-bouncer@docker</code> middleware.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #6A737D;"># In the labels for your service (e.g., an API)</span></span> <span class="giallo-l"><span style="color: #85E89D;">labels</span><span>:</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.my-api.rule=Host(`api.your-domain.com`)&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.my-api.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.my-api.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # --- Middlewares (Security ONLY) ---</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.my-api.middlewares=security-headers@file&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.services.my-api.loadbalancer.server.port=3000&quot;</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ MAXIMUM FLEXIBILITY </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>By applying middleware on a per-router basis instead of globally on the entrypoint, you gain complete control over which services are protected by CrowdSec and which are not.</p> </td> </tr> </table> <h3 id="5-3-routing-multiple-sub-domains-to-one-service">5.3. Routing Multiple (Sub)Domains to One Service</h3> <p>Sometimes one container should respond to more than one hostname (e.g., <code>example.com</code> and <code>www.example.com</code>, or multiple subdomains pointing to the same app). You have a few common options.</p> <h4 id="option-a-multiple-explicit-hosts-in-one-router">Option A: Multiple Explicit Hosts in One Router</h4> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #85E89D;">labels</span><span>:</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app.rule=Host(`example.com`) || Host(`www.example.com`)&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app.middlewares=security-headers@file,crowdsec-bouncer@docker&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.services.app.loadbalancer.server.port=80&quot;</span></span></code></pre><h4 id="option-b-wildcard-pattern-matching-many-subdomains">Option B: Wildcard / Pattern Matching (Many Subdomains)</h4> <p>Use this if you want to match <em>many</em> subdomains dynamically.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #85E89D;">labels</span><span>:</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app.rule=HostRegexp(`[a-z0-9-]+\.example\.com`)&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app.middlewares=security-headers@file,crowdsec-bouncer@docker&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.services.app.loadbalancer.server.port=80&quot;</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ WILDCARD CERTIFICATES &amp; LET&#x27;S ENCRYPT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>While <code>HostRegexp</code> routes the traffic dynamically, the <code>httpChallenge</code> configured earlier cannot issue a wildcard certificate (e.g., <code>*.example.com</code>). Let’s Encrypt requires a <strong>DNS challenge</strong> for wildcards. With <code>httpChallenge</code>, Traefik will attempt to request individual certificates for every matched subdomain, which can quickly exhaust Let’s Encrypt rate limits.</p> </td> </tr> </table> <h4 id="option-c-multiple-routers-one-service-different-middleware-per-host">Option C: Multiple Routers, One Service (Different Middleware per Host)</h4> <p>This is useful if one hostname should bypass CrowdSec while another one stays protected.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #85E89D;">labels</span><span>:</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app-main.rule=Host(`app.example.com`)&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app-main.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app-main.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app-main.middlewares=security-headers@file,crowdsec-bouncer@docker&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app-api.rule=Host(`api.example.com`)&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app-api.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app-api.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app-api.middlewares=security-headers@file&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.services.app.loadbalancer.server.port=80&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app-main.service=app&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.app-api.service=app&quot;</span></span></code></pre><h2 id="6-maintenance">6. Maintenance</h2> <p>To update your stack to the latest container images:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/traefik-stack</span></span> <span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose pull</span></span> <span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose up</span><span style="color: #79B8FF;"> -d --remove-orphans</span></span></code></pre><h3 id="6-1-log-rotation-critical-for-production">6.1. Log Rotation (Critical for Production)</h3> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ DON&#x27;T SKIP THIS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>This setup generates detailed JSON access logs for CrowdSec analysis. Without proper log rotation, Traefik logs alone can consume <strong>70+ GB</strong> within weeks on a busy server. Docker container logs can add another 40+ GB. Configure rotation <strong>before</strong> going to production.</p> </td> </tr> </table> <h4 id="docker-global-log-rotation">Docker Global Log Rotation</h4> <p>Configure Docker to automatically rotate all container logs by editing <code>/etc/docker/daemon.json</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee /etc/docker/daemon.json</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">{</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;log-driver&quot;: &quot;json-file&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;log-opts&quot;: {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;max-size&quot;: &quot;10m&quot;,</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;max-file&quot;: &quot;3&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre> <p>Apply the changes:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> systemctl restart docker</span></span> <span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> info</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -A3</span><span style="color: #9ECBFF;"> &quot;Logging Driver&quot;</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ EXISTING CONTAINERS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>This setting only applies to newly created containers. Existing containers keep their old logging configuration. Recreate them with <code>docker compose up -d --force-recreate</code> to apply the new limits.</p> </td> </tr> </table> <h4 id="traefik-host-log-rotation">Traefik Host Log Rotation</h4> <p>Since Traefik writes logs directly to the host filesystem, use <code>logrotate</code>.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ PATH VERIFICATION </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Ensure the path in the config below matches your <strong>host path</strong> where the logs are stored. You can find it by running: <code>docker inspect traefik --format '{{range .Mounts}}{{.Source}}{{"\n"}}{{end}}' | grep logs</code></p> </td> </tr> </table> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee /etc/logrotate.d/traefik</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">/opt/containers/traefik-stack/traefik/logs/*.log {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> daily</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> rotate 7</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> compress</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> delaycompress</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> missingok</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> notifempty</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> copytruncate</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> maxsize 50M</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><h4 id="verify-log-rotation">Verify Log Rotation</h4> <p>To ensure your rotation is working correctly and to troubleshoot issues, use these commands:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Debug: show which rules would apply without actually rotating</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> logrotate</span><span style="color: #79B8FF;"> -d</span><span style="color: #9ECBFF;"> /etc/logrotate.d/traefik</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Force rotation: execute immediately</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> logrotate</span><span style="color: #79B8FF;"> -f</span><span style="color: #9ECBFF;"> /etc/logrotate.d/traefik</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Check rotation status: see when logs were last rotated</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> cat /var/lib/logrotate/status</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> &quot;traefik&quot;</span></span></code></pre><h2 id="7-troubleshooting-disk-full">7. Troubleshooting: Disk Full</h2> <p>If your server runs out of disk space, logs are usually the culprit. Here’s how to diagnose and fix it.</p> <h3 id="7-1-identify-the-problem">7.1. Identify the Problem</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Quick overview</span></span> <span class="giallo-l"><span style="color: #B392F0;">df</span><span style="color: #79B8FF;"> -h</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Find large directories</span></span> <span class="giallo-l"><span style="color: #B392F0;">du</span><span style="color: #79B8FF;"> -h -d1</span><span style="color: #9ECBFF;"> /</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sort</span><span style="color: #79B8FF;"> -h</span></span> <span class="giallo-l"><span style="color: #B392F0;">du</span><span style="color: #79B8FF;"> -h -d1</span><span style="color: #9ECBFF;"> /var</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sort</span><span style="color: #79B8FF;"> -h</span></span> <span class="giallo-l"><span style="color: #B392F0;">du</span><span style="color: #79B8FF;"> -h -d1</span><span style="color: #9ECBFF;"> /opt</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sort</span><span style="color: #79B8FF;"> -h</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Docker-specific</span></span> <span class="giallo-l"><span style="color: #B392F0;">du</span><span style="color: #79B8FF;"> -h -d1</span><span style="color: #9ECBFF;"> /var/lib/docker</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sort</span><span style="color: #79B8FF;"> -h</span></span> <span class="giallo-l"><span style="color: #B392F0;">du</span><span style="color: #79B8FF;"> -h -d1</span><span style="color: #9ECBFF;"> /var/lib/docker/containers</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sort</span><span style="color: #79B8FF;"> -h</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Find large container logs</span></span> <span class="giallo-l"><span style="color: #B392F0;">find</span><span style="color: #9ECBFF;"> /var/lib/docker/containers</span><span style="color: #79B8FF;"> -name</span><span style="color: #9ECBFF;"> &#39;*-json.log&#39;</span><span style="color: #79B8FF;"> -exec</span><span style="color: #9ECBFF;"> du</span><span style="color: #79B8FF;"> -h</span><span style="color: #9ECBFF;"> {}</span><span style="color: #79B8FF;"> \;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sort</span><span style="color: #79B8FF;"> -h</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Check journald (usually not the problem)</span></span> <span class="giallo-l"><span style="color: #B392F0;">journalctl</span><span style="color: #79B8FF;"> --disk-usage</span></span></code></pre><h3 id="7-2-emergency-cleanup">7.2. Emergency Cleanup</h3> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ CAUTION </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>These commands delete log data permanently. Only proceed if you don’t need the logs for debugging.</p> </td> </tr> </table> <p><strong>Truncate Docker container logs:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> find /var/lib/docker/containers</span><span style="color: #79B8FF;"> -name</span><span style="color: #9ECBFF;"> &#39;*-json.log&#39;</span><span style="color: #79B8FF;"> -exec</span><span style="color: #9ECBFF;"> truncate</span><span style="color: #79B8FF;"> -s 0</span><span style="color: #9ECBFF;"> {}</span><span style="color: #79B8FF;"> \;</span></span></code></pre> <p><strong>Clear Traefik logs:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/traefik-stack</span></span> <span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose down</span></span> <span class="giallo-l"><span style="color: #B392F0;">rm</span><span style="color: #79B8FF;"> -rf</span><span style="color: #9ECBFF;"> traefik/logs/</span><span style="color: #79B8FF;">*</span></span> <span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose up</span><span style="color: #79B8FF;"> -d</span></span></code></pre> <p>After cleanup, <strong>immediately configure log rotation</strong> as described in section 6.1 to prevent recurrence.</p> <h2 id="conclusion">Conclusion</h2> <p>You now have a modern, secure, and flexible reverse proxy setup. Traefik handles routing and TLS termination effortlessly, while CrowdSec provides a powerful, community-driven security layer. By managing middlewares on a per-service basis, you can tailor the level of protection to fit the exact needs of each application you deploy.</p> <p>As a next step, you might want to explore the <strong>AppSec (WAF)</strong> capabilities of the CrowdSec Bouncer plugin, which adds application-level protection against advanced attacks like SQL injection and Cross-Site Scripting directly at the Traefik layer.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;doc.traefik.io&#x2F;traefik&#x2F;" class="retro-button"> <span class="emoji">📚</span><span class="button-text">TRAEFIK DOCUMENTATION</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;docs.crowdsec.net&#x2F;" class="retro-button"> <span class="emoji">🛡️</span><span class="button-text">CROWDSEC DOCUMENTATION</span> </a> </p> Deploying a Matrix Synapse Server with Docker and Traefik Fri, 20 Feb 2026 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/matrix-synapse-server/ https://criticalbasics.xyz/posts/matrix-synapse-server/ <p>This guide will walk you through deploying a powerful, federated Matrix Synapse homeserver. We will use the popular <code>matrix-docker-ansible-deploy</code> playbook, which simplifies the setup of Synapse and its various components, including bridges for other chat platforms.</p> <p>This setup is designed to integrate seamlessly with an existing Traefik v3 reverse proxy and a root-domain <a href="../nginx_webserver/">Nginx web server</a>, making it a perfect addition to a modern, container-based infrastructure.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2026-02-20</td><td><strong>Configuration Update:</strong> Updated <code>matrix_coturn_enabled</code> to <code>coturn_enabled</code>, removed Sliding Sync, and added PostgreSQL upgrade instructions.</td></tr> <tr><td>2025-09-17</td><td><strong>Initial Version:</strong> Guide created, focusing on Traefik v3 integration, Ansible deployment, and enabling various bridges and features like Sliding Sync.</td></tr> </tbody></table> </div> <h2 id="1-prerequisites">1. Prerequisites</h2> <ol> <li><strong><a href="../traefik-v3-crowdsec-tutorial/">Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack</a></strong>: This is the foundation for our reverse proxy and security.</li> <li><strong><a href="../nginx-webserver/">Deploying a Secure Nginx Website with Traefik and Docker Compose</a></strong>: This step is crucial as it establishes a web server on your root domain and correctly configures the <code>.well-known/matrix</code> delegation required for federation.</li> </ol> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ HARD REQUIREMENT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The following steps will not work correctly without the Traefik and Nginx stacks running as described in the prerequisite guides.</p> </td> </tr> </table> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ ROOT DOMAIN REMAINS FREE FOR YOUR WEBSITE </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Synapse runs on a dedicated subdomain (e.g., <code>matrix.your-domain.com</code>). The root domain (e.g., <code>your-domain.com</code>) continues to serve your main website via <a href="../nginx-webserver/">Nginx</a>. The <code>.well-known</code> files on the root domain merely delegate clients and federation to the subdomain, so your homepage remains unaffected.</p> </td> </tr> </table> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>Architecture (simplified)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Users / Browsers / Homeservers</span></span> <span class="giallo-l"><span> │</span></span> <span class="giallo-l"><span> ▼</span></span> <span class="giallo-l"><span> your-domain.com ──&gt; [Nginx](../nginx_webserver/) on root domain</span></span> <span class="giallo-l"><span> │ │</span></span> <span class="giallo-l"><span> │ ├─ Serves your website (/, /assets, ...)</span></span> <span class="giallo-l"><span> │ └─ Serves .well-known/matrix/{server,client}</span></span> <span class="giallo-l"><span> │ │</span></span> <span class="giallo-l"><span> │ ▼</span></span> <span class="giallo-l"><span> └────────────────────────── delegates to ──&gt; matrix.your-domain.com</span></span> <span class="giallo-l"><span> (Synapse via Traefik)</span></span> <span class="giallo-l"><span> │</span></span> <span class="giallo-l"><span> ▼</span></span> <span class="giallo-l"><span> Traefik (websecure, synapse)</span></span> <span class="giallo-l"><span> │</span></span> <span class="giallo-l"><span> ▼</span></span> <span class="giallo-l"><span> Synapse</span></span></code></pre> <p>You will also need:</p> <ul> <li><code>git</code>, <code>jq</code>, and <code>pwgen</code> for version control, JSON parsing, and password generation.</li> <li>Python 3 and <code>pip</code> installed on your server.</li> <li><code>sudo</code> or root access.</li> </ul> <p>Install the required tools:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt update</span><span> &amp;&amp;</span><span style="color: #B392F0;"> sudo</span><span style="color: #9ECBFF;"> apt</span><span style="color: #79B8FF;"> -y</span><span style="color: #9ECBFF;"> install git jq pwgen python3-pip</span></span></code></pre><h2 id="2-directory-structure">2. Directory Structure</h2> <p>First, we’ll create a dedicated directory for the Matrix playbook configuration and files.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> /opt/containers/matrix</span></span></code></pre><h2 id="3-download-the-ansible-playbook">3. Download the Ansible Playbook</h2> <p>Next, clone the official <code>matrix-docker-ansible-deploy</code> repository from GitHub into the directory you just created.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git /opt/containers/matrix</span></span></code></pre><h2 id="4-initial-configuration">4. Initial Configuration</h2> <p>The playbook is configured using Ansible variables. We’ll start by creating a configuration directory based on your Matrix server’s hostname and copying the example <code>vars.yml</code> file.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ HOSTNAME CONVENTION </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The playbook expects the server to be available at <code>matrix.your-domain.com</code>. The configuration directory must match this hostname.</p> </td> </tr> </table> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/matrix</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Replace &#39;matrix.your-domain.com&#39; with your actual server name</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> inventory/host_vars/matrix.your-domain.com</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> cp examples/vars.yml inventory/host_vars/matrix.your-domain.com/</span></span></code></pre><h3 id="4-1-generate-secret-keys">4.1. Generate Secret Keys</h3> <p>The configuration requires two strong secret keys. You can generate these using <code>pwgen</code> or <code>openssl</code>.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Generate two strong keys and save them for the next step</span></span> <span class="giallo-l"><span style="color: #B392F0;">pwgen</span><span style="color: #79B8FF;"> -s 64 1</span></span> <span class="giallo-l"><span style="color: #B392F0;">pwgen</span><span style="color: #79B8FF;"> -s 64 1</span></span></code></pre><h3 id="4-2-customize-vars-yml">4.2. Customize <code>vars.yml</code></h3> <p>Now, open the <code>vars.yml</code> file and customize it for your environment. This is the most critical step.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> nano inventory/host_vars/matrix.your-domain.com/vars.yml</span></span></code></pre> <p>Below is a complete configuration based on a feature-rich setup. Adjust the values to match your domain, secrets, and desired features.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #6A737D;"># The bare domain name which represents your Matrix identity.</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_domain</span><span>:</span><span style="color: #9ECBFF;"> your-domain.com</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_homeserver_implementation</span><span>:</span><span style="color: #9ECBFF;"> synapse</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_homeserver_generic_secret_key</span><span>:</span><span style="color: #9ECBFF;"> &#39;PASTE-YOUR-GENERIC-SECRET-KEY-HERE&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Use our own Traefik (externally managed)</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_playbook_reverse_proxy_type</span><span>:</span><span style="color: #9ECBFF;"> other-traefik-container</span></span> <span class="giallo-l"><span style="color: #85E89D;">traefik_certs_dumper_enabled</span><span>:</span><span style="color: #79B8FF;"> false</span></span> <span class="giallo-l"><span style="color: #85E89D;">traefik_config_certificatesResolvers_acme_email</span><span>:</span><span style="color: #9ECBFF;"> &#39;your-email@example.com&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #85E89D;">postgres_connection_password</span><span>:</span><span style="color: #9ECBFF;"> &#39;PASTE-YOUR-POSTGRES-PASSWORD-HERE&#39;</span></span> <span class="giallo-l"><span style="color: #85E89D;">devture_systemd_docker_base_docker_service_name</span><span>:</span><span style="color: #9ECBFF;"> &quot;docker&quot;</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_playbook_docker_installation_enabled</span><span>:</span><span style="color: #79B8FF;"> false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># We delegate .well-known from the root domain via Nginx</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_static_files_enabled</span><span>:</span><span style="color: #79B8FF;"> false</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_static_files_container_labels_traefik_enabled</span><span>:</span><span style="color: #79B8FF;"> false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #85E89D;">coturn_enabled</span><span>:</span><span style="color: #79B8FF;"> false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Traefik integration</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_playbook_reverse_proxy_container_network</span><span>:</span><span style="color: #9ECBFF;"> proxy</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_playbook_reverse_proxy_hostname</span><span>:</span><span style="color: #9ECBFF;"> traefik</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_federation_traefik_entrypoint_name</span><span>:</span><span style="color: #9ECBFF;"> synapse</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Disable Synapse&#39;s internal client-API router (or redirect to a valid entrypoint)</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_enabled</span><span>:</span><span style="color: #79B8FF;"> false</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_entrypoints</span><span>:</span><span style="color: #9ECBFF;"> websecure</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># --- Core services ---</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_synapse_container_labels_traefik_docker_network</span><span>:</span><span style="color: #9ECBFF;"> proxy</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_synapse_container_labels_traefik_entrypoints</span><span>:</span><span style="color: #9ECBFF;"> websecure</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_synapse_container_labels_traefik_tls_certResolver</span><span>:</span><span style="color: #9ECBFF;"> tls_resolver</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_synapse_container_labels_traefik_middlewares</span><span>:</span><span style="color: #9ECBFF;"> &#39;security-headers@file,crowdsec-bouncer@docker&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_client_element_container_labels_traefik_docker_network</span><span>:</span><span style="color: #9ECBFF;"> proxy</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_client_element_container_labels_traefik_entrypoints</span><span>:</span><span style="color: #9ECBFF;"> websecure</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_client_element_container_labels_traefik_tls_certResolver</span><span>:</span><span style="color: #9ECBFF;"> tls_resolver</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_client_element_container_labels_traefik_middlewares</span><span>:</span><span style="color: #9ECBFF;"> &#39;security-headers@file,crowdsec-bouncer@docker&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_admin</span><span>:</span><span style="color: #9ECBFF;"> &#39;@your-username:your-domain.com&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_synapse_admin_enabled</span><span>:</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_synapse_admin_container_http_host_bind_port</span><span>:</span><span style="color: #9ECBFF;"> &quot;&quot;</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_synapse_admin_container_labels_traefik_docker_network</span><span>:</span><span style="color: #9ECBFF;"> proxy</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_synapse_admin_container_labels_traefik_entrypoints</span><span>:</span><span style="color: #9ECBFF;"> websecure</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_synapse_admin_container_labels_traefik_tls_certResolver</span><span>:</span><span style="color: #9ECBFF;"> tls_resolver</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_synapse_admin_container_labels_traefik_middlewares</span><span>:</span><span style="color: #9ECBFF;"> &#39;security-headers@file,crowdsec-bouncer@docker&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># E-Mail relay (optional)</span></span> <span class="giallo-l"><span style="color: #85E89D;">exim_relay_sender_address</span><span>:</span><span style="color: #9ECBFF;"> &quot;matrix@your-domain.com&quot;</span></span> <span class="giallo-l"><span style="color: #85E89D;">exim_relay_relay_use</span><span>:</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #85E89D;">exim_relay_relay_host_name</span><span>:</span><span style="color: #9ECBFF;"> &quot;mail.your-domain.com&quot;</span></span> <span class="giallo-l"><span style="color: #85E89D;">exim_relay_relay_host_port</span><span>:</span><span style="color: #79B8FF;"> 587</span></span> <span class="giallo-l"><span style="color: #85E89D;">exim_relay_relay_auth</span><span>:</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #85E89D;">exim_relay_relay_auth_username</span><span>:</span><span style="color: #9ECBFF;"> &quot;user@your-domain.com&quot;</span></span> <span class="giallo-l"><span style="color: #85E89D;">exim_relay_relay_auth_password</span><span>:</span><span style="color: #9ECBFF;"> &quot;YOUR-EMAIL-PASSWORD&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_appservice_double_puppet_enabled</span><span>:</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># --- Bridges ---</span></span> <span class="giallo-l"><span style="color: #6A737D;"># The playbook can install and configure various bridges to connect your Matrix homeserver</span></span> <span class="giallo-l"><span style="color: #6A737D;"># to other chat networks like Telegram, Discord, Signal, etc. When enabling a bridge,</span></span> <span class="giallo-l"><span style="color: #6A737D;"># it is crucial to provide the `homeserver` configuration block to ensure it communicates</span></span> <span class="giallo-l"><span style="color: #6A737D;"># correctly with Synapse via Traefik. For more details on available bridges and their</span></span> <span class="giallo-l"><span style="color: #6A737D;"># specific configurations, refer to the official documentation.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Telegram – Correct EntryPoints + specify Homeserver</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_mautrix_telegram_enabled</span><span>:</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_mautrix_telegram_api_id</span><span>:</span><span style="color: #79B8FF;"> 12345678</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_mautrix_telegram_api_hash</span><span>:</span><span style="color: #9ECBFF;"> &#39;your_telegram_api_hash&#39;</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_mautrix_telegram_container_labels_traefik_entrypoints</span><span>:</span><span style="color: #9ECBFF;"> websecure</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_mautrix_telegram_container_labels_public_endpoint_traefik_entrypoints</span><span>:</span><span style="color: #9ECBFF;"> websecure</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_mautrix_telegram_container_labels_metrics_traefik_entrypoints</span><span>:</span><span style="color: #9ECBFF;"> websecure</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_mautrix_telegram_configuration_extension_yaml</span><span>:</span><span style="color: #F97583;"> |</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> homeserver:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> address: &quot;https://matrix.your-domain.com&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> domain: &quot;your-domain.com&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> bridge:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> permissions:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &#39;{{ matrix_admin }}&#39;: admin</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Meta Messenger</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_mautrix_meta_messenger_enabled</span><span>:</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_mautrix_meta_messenger_configuration_extension_yaml</span><span>:</span><span style="color: #F97583;"> |</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> homeserver:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> address: &quot;https://matrix.your-domain.com&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> domain: &quot;your-domain.com&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> bridge:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> permissions:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &#39;*&#39;: relay</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &#39;your-domain.com&#39;: admin</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &#39;{{ matrix_admin }}&#39;: admin</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Discord – Correct Avatar-Proxy &amp; general EntryPoints</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_mautrix_discord_enabled</span><span>:</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_mautrix_discord_container_labels_traefik_entrypoints</span><span>:</span><span style="color: #9ECBFF;"> websecure</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_mautrix_discord_container_labels_avatar_proxy_traefik_entrypoints</span><span>:</span><span style="color: #9ECBFF;"> websecure</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_mautrix_discord_configuration_extension_yaml</span><span>:</span><span style="color: #F97583;"> |</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> homeserver:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> address: &quot;https://matrix.your-domain.com&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> domain: &quot;your-domain.com&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># --- Element Call / Livekit ---</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_element_call_enabled</span><span>:</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_element_call_container_labels_traefik_entrypoints</span><span>:</span><span style="color: #9ECBFF;"> websecure</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_element_call_container_labels_traefik_tls_certResolver</span><span>:</span><span style="color: #9ECBFF;"> tls_resolver</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_element_call_container_labels_traefik_docker_network</span><span>:</span><span style="color: #9ECBFF;"> proxy</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_livekit_jwt_service_container_labels_traefik_entrypoints</span><span>:</span><span style="color: #9ECBFF;"> websecure</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_livekit_jwt_service_container_labels_traefik_tls_certResolver</span><span>:</span><span style="color: #9ECBFF;"> tls_resolver</span></span> <span class="giallo-l"><span style="color: #85E89D;">matrix_livekit_jwt_service_container_labels_traefik_docker_network</span><span>:</span><span style="color: #9ECBFF;"> proxy</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #85E89D;">livekit_server_container_labels_traefik_entrypoints</span><span>:</span><span style="color: #9ECBFF;"> websecure</span></span> <span class="giallo-l"><span style="color: #85E89D;">livekit_server_container_labels_public_metrics_traefik_tls_certResolver</span><span>:</span><span style="color: #9ECBFF;"> tls_resolver</span></span> <span class="giallo-l"><span style="color: #85E89D;">livekit_server_container_labels_traefik_docker_network</span><span>:</span><span style="color: #9ECBFF;"> proxy</span></span></code></pre><h2 id="5-install-ansible-and-dependencies">5. Install Ansible and Dependencies</h2> <p>This playbook uses Ansible to automate the setup. Choose the installation method that fits your distribution policy.</p> <h3 id="for-debian-12-system-pip-with-break-system-packages">For Debian 12 (system pip with –break-system-packages)</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Ensure pip is available</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt install</span><span style="color: #79B8FF;"> -y</span><span style="color: #9ECBFF;"> python3-pip</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Install Ansible and required Python packages system-wide</span></span> <span class="giallo-l"><span style="color: #B392F0;">pip3</span><span style="color: #9ECBFF;"> install</span><span style="color: #79B8FF;"> --break-system-packages</span><span style="color: #9ECBFF;"> ansible docker passlib</span></span></code></pre><h3 id="for-other-linux-distributions-recommended-python-virtual-environment">For Other Linux Distributions (recommended: Python virtual environment)</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Create and activate a dedicated virtual environment</span></span> <span class="giallo-l"><span style="color: #B392F0;">python3</span><span style="color: #79B8FF;"> -m</span><span style="color: #9ECBFF;"> venv ~/.venvs/matrix-ansible</span></span> <span class="giallo-l"><span style="color: #79B8FF;">source</span><span style="color: #9ECBFF;"> ~/.venvs/matrix-ansible/bin/activate</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Upgrade pip and install required packages in the venv</span></span> <span class="giallo-l"><span style="color: #B392F0;">pip</span><span style="color: #9ECBFF;"> install</span><span style="color: #79B8FF;"> --upgrade</span><span style="color: #9ECBFF;"> pip</span></span> <span class="giallo-l"><span style="color: #B392F0;">pip</span><span style="color: #9ECBFF;"> install ansible docker passlib</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ VIRTUALENV REMINDER </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>If you use the virtual environment, remember to reactivate it in new shell sessions with: <code>source ~/.venvs/matrix-ansible/bin/activate</code></p> </td> </tr> </table> <p>Next, install the Ansible roles required by the playbook:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/matrix</span></span> <span class="giallo-l"><span style="color: #B392F0;">make</span><span style="color: #9ECBFF;"> roles</span></span></code></pre><h2 id="6-configure-ansible-hosts">6. Configure Ansible Hosts</h2> <p>Now, we need to tell Ansible which server to configure. Since we are running it locally, the setup is simple.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Copy the example hosts file</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> cp examples/hosts inventory/hosts</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Edit the file</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> nano inventory/hosts</span></span></code></pre> <p>Modify the file to look like this. The <code>ansible_connection=local</code> tells Ansible to run all commands on the machine it’s currently on, instead of connecting to a remote server via SSH. Because of this, <code>ansible_host=127.0.0.1</code> (localhost) is the correct value. Parameters like <code>ansible_ssh_user=root</code> are ignored in this mode, as the playbook runs with the permissions of the user executing it (in our case, <code>root</code> via <code>sudo</code>).</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #B392F0;">[matrix_servers]</span></span> <span class="giallo-l"><span>matrix.your-domain.com </span><span style="color: #F97583;">ansible_host</span><span>=127.0.0.1 </span><span style="color: #F97583;">ansible_connection</span><span>=local</span></span></code></pre><h2 id="7-adjust-traefik-for-federation">7. Adjust Traefik for Federation</h2> <p>For Matrix federation to work, other servers need to connect to yours on port <code>8448</code>. We must expose this port in our main Traefik stack and create a dedicated entrypoint for it.</p> <p>Go to your Traefik stack’s directory (e.g., <code>/opt/containers/traefik-stack</code>).</p> <h3 id="7-1-expose-federation-port">7.1. Expose Federation Port</h3> <p>Edit your main <code>docker-compose.yml</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> nano docker-compose.yml</span></span></code></pre> <p>Add port <code>8448</code> to the <code>ports</code> section of the <code>traefik</code> service:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #85E89D;">services</span><span>:</span></span> <span class="giallo-l"><span style="color: #85E89D;"> traefik</span><span>:</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # ... other settings</span></span> <span class="giallo-l"><span style="color: #85E89D;"> ports</span><span>:</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;80:80&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;443:443&quot;</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> &quot;8448:8448&quot;</span><span style="color: #6A737D;"> # Add this line for Matrix federation</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # ... rest of the settings</span></span></code></pre><h3 id="7-2-create-federation-and-internal-entrypoints">7.2. Create Federation and Internal Entrypoints</h3> <p>Edit your static Traefik configuration (<code>traefik/config/traefik.yml</code>):</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> nano traefik/config/traefik.yml</span></span></code></pre> <p>Add a new <code>synapse</code> entrypoint for federation and a <code>matrix-internal-matrix-client-api</code> entrypoint for internal communication.</p> <p>For recent playbook versions, it is recommended to also define the internal <code>matrix-internal-matrix-client-api</code> entrypoint on port 8008. This port is <strong>not</strong> published to the host and serves as an internal C2S route for bridges and add-ons, preventing errors in the Traefik dashboard.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #85E89D;">entryPoints</span><span>:</span></span> <span class="giallo-l"><span style="color: #85E89D;"> web</span><span>:</span></span> <span class="giallo-l"><span style="color: #85E89D;"> address</span><span>:</span><span style="color: #9ECBFF;"> &quot;:80&quot;</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # ...</span></span> <span class="giallo-l"><span style="color: #85E89D;"> websecure</span><span>:</span></span> <span class="giallo-l"><span style="color: #85E89D;"> address</span><span>:</span><span style="color: #9ECBFF;"> &quot;:443&quot;</span></span> <span class="giallo-l"><span style="color: #85E89D;"> synapse</span><span>:</span><span style="color: #6A737D;"> # For federation</span></span> <span class="giallo-l"><span style="color: #85E89D;"> address</span><span>:</span><span style="color: #9ECBFF;"> &quot;:8448&quot;</span></span> <span class="giallo-l"><span style="color: #85E89D;"> matrix-internal-matrix-client-api</span><span>:</span><span style="color: #6A737D;"> # For internal C2S communication</span></span> <span class="giallo-l"><span style="color: #85E89D;"> address</span><span>:</span><span style="color: #9ECBFF;"> &quot;:8008&quot;</span></span></code></pre><h3 id="7-3-restart-traefik">7.3. Restart Traefik</h3> <p>Apply the changes by restarting your Traefik stack:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/traefik-stack</span></span> <span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose up</span><span style="color: #79B8FF;"> -d</span></span></code></pre><h2 id="8-run-the-matrix-installation">8. Run the Matrix Installation</h2> <p>With all the configuration in place, we can now run the Ansible playbook to set up and install everything.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/matrix</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ansible-playbook</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> inventory/hosts setup.yml</span><span style="color: #79B8FF;"> --tags=setup-all</span></span></code></pre> <p>This command will download all necessary Docker images, generate configuration files, and prepare the services. It may take several minutes.</p> <h2 id="9-start-the-matrix-services">9. Start the Matrix Services</h2> <p>Once the setup is complete, start all the Matrix containers:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ansible-playbook</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> inventory/hosts setup.yml</span><span style="color: #79B8FF;"> --tags=start</span></span></code></pre> <p>After a few moments, all the services you enabled should be running. You can verify this with <code>docker ps</code>.</p> <h2 id="10-verify-the-installation">10. Verify the Installation</h2> <p>After starting the services, it’s crucial to verify that all components are running and communicating correctly.</p> <h3 id="10-1-check-running-containers">10.1. Check Running Containers</h3> <p>First, ensure all enabled services are running. The exact names will vary based on your <code>matrix_domain</code>.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> ps</span><span style="color: #79B8FF;"> --format</span><span style="color: #9ECBFF;"> &#39;{{.Names}}&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -E</span><span style="color: #9ECBFF;"> &#39;synapse|element|sliding|admin&#39;</span></span></code></pre><h3 id="10-2-verify-well-known-delegation-cli">10.2. Verify <code>.well-known</code> Delegation (CLI)</h3> <p>Check if your Nginx server is correctly serving the delegation files for your root domain.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Replace &#39;your-domain.com&#39; with your actual domain</span></span> <span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -s</span><span style="color: #9ECBFF;"> https://your-domain.com/.well-known/matrix/server</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> jq</span></span> <span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -s</span><span style="color: #9ECBFF;"> https://your-domain.com/.well-known/matrix/client</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> jq</span></span></code></pre> <p>Both commands should return a clean JSON output pointing to <code>matrix.your-domain.com</code>.</p> <h3 id="10-3-verify-federation-endpoint-cli">10.3. Verify Federation Endpoint (CLI)</h3> <p>Test if the Synapse federation port (<code>8448</code>) is correctly exposed through Traefik.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Replace &#39;matrix.your-domain.com&#39; with your actual matrix subdomain</span></span> <span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -sS</span><span style="color: #9ECBFF;"> https://matrix.your-domain.com:8448/_matrix/federation/v1/version</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> jq</span></span></code></pre> <p>This should return a JSON object with server information, confirming the federation endpoint is reachable.</p> <h3 id="10-4-verify-crowdsec-bouncer-registration">10.4. Verify CrowdSec Bouncer Registration</h3> <p>Check if the CrowdSec bouncer for Traefik has successfully registered with the CrowdSec agent.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/traefik-stack</span></span> <span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose exec crowdsec cscli bouncers list</span></span></code></pre> <p>You should see the Traefik bouncer in the list with a valid status.</p> <h3 id="10-5-web-based-federation-test">10.5. Web-based Federation Test</h3> <p>Finally, use the official Federation Tester for a comprehensive check.</p> <ol> <li>Go to: <a rel="noopener external" target="_blank" href="https://federationtester.matrix.org/">https://federationtester.matrix.org/</a></li> <li>Enter your server name (e.g., <code>your-domain.com</code>) and run the test.</li> </ol> <p>If everything is configured correctly, you should see a success message.</p> <h2 id="11-create-your-first-user">11. Create Your First User</h2> <p>Use the playbook to register your administrator user.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ PASSWORD SECURITY </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>To avoid leaving your password in your shell’s history, omit the <code>-e 'password=...'</code> part. The playbook will then prompt you to enter the password securely.</p> <p><code>... -e 'username=your-username' -e 'admin=yes'</code></p> </td> </tr> </table> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/matrix</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ansible-playbook</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> inventory/hosts setup.yml</span><span style="color: #79B8FF;"> --tags=register-user -e</span><span style="color: #9ECBFF;"> &#39;username=your-username&#39;</span><span style="color: #79B8FF;"> -e</span><span style="color: #9ECBFF;"> &#39;admin=yes&#39;</span></span></code></pre> <p>You can re-run this command with <code>admin=no</code> to create non-admin users.</p> <h2 id="12-log-in-with-element">12. Log In with Element</h2> <p>Your homeserver is now ready! You can access the Element web client by navigating to <code>https://matrix.your-domain.com</code>.</p> <ol> <li>Click “Sign In”.</li> <li>Your homeserver should be pre-filled. If not, edit it to show your server’s address (<code>matrix.your-domain.com</code>).</li> <li>Log in with the username and password you just created.</li> </ol> <h2 id="13-accessing-the-synapse-admin-ui">13. Accessing the Synapse Admin UI</h2> <p>Because we set <code>matrix_synapse_admin_enabled: true</code> in our <code>vars.yml</code> configuration, a powerful web-based administration interface for Synapse is automatically deployed. This UI is essential for server maintenance and user management.</p> <p>You can access it at: <code>https://matrix.your-domain.com/synapse-admin</code></p> <p>Log in with your Matrix administrator account. From here, you can:</p> <ul> <li>Manage users (deactivate, make admin, etc.).</li> <li>View server statistics and metrics.</li> <li>Explore rooms and manage their settings.</li> </ul> <p>This interface is the primary tool for the day-to-day administration of your homeserver.</p> <h2 id="14-maintenance">14. Maintenance</h2> <h3 id="updating-matrix">Updating Matrix</h3> <p>To update your Matrix server and its components to the latest version:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/matrix</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Pull the latest changes from the git repository</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> git pull</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># It&#39;s a good practice to review the CHANGELOG.md for breaking changes</span></span> <span class="giallo-l"><span style="color: #6A737D;"># sudo nano CHANGELOG.md</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Re-run the setup and start tags to apply updates</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ansible-playbook</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> inventory/hosts setup.yml</span><span style="color: #79B8FF;"> --tags=setup-all,start</span></span></code></pre><h3 id="upgrading-postgresql">Upgrading PostgreSQL</h3> <p>If the playbook notifies you about a new PostgreSQL version being available, you can perform the upgrade with a specific tag.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ BACKUP RECOMMENDED </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Before upgrading the database, ensure you have a recent backup of your data.</p> </td> </tr> </table> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/matrix</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ansible-playbook</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> inventory/hosts setup.yml</span><span style="color: #79B8FF;"> --tags=upgrade-postgres</span></span></code></pre><h3 id="stopping-and-uninstalling">Stopping and Uninstalling</h3> <p>To <strong>stop</strong> all Matrix services:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/matrix</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ansible-playbook</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> inventory/hosts setup.yml</span><span style="color: #79B8FF;"> --tags=stop</span></span></code></pre> <p>To completely <strong>uninstall and delete all data</strong>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/matrix</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ansible-playbook</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> inventory/hosts setup.yml</span><span style="color: #79B8FF;"> --tags=uninstall</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ DATA LOSS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The <code>uninstall</code> tag is destructive and will remove all user data, chat history, and media. Use with extreme caution.</p> </td> </tr> </table> <h2 id="15-troubleshooting">15. Troubleshooting</h2> <p>Below are common issues and quick checks to resolve them.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ TIP: VERIFY ONE LAYER AT A TIME </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>When in doubt, verify DNS → Traefik → Nginx <code>.well-known</code> → Synapse federation endpoint step by step. Isolate the layer that fails.</p> </td> </tr> </table> <h3 id="15-1-federation-test-fails">15.1 Federation test fails</h3> <ul> <li>Ensure port 8448 is exposed by Traefik and the <code>synapse</code> entrypoint exists.</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/traefik-stack</span></span> <span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose ps traefik</span></span> <span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> inspect traefik</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> jq</span><span style="color: #9ECBFF;"> &#39;.[0].NetworkSettings.Ports[&quot;8448/tcp&quot;]&#39;</span></span></code></pre> <ul> <li>Test the federation version endpoint directly:</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -sS</span><span style="color: #9ECBFF;"> https://matrix.your-domain.com:8448/_matrix/federation/v1/version</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> jq</span></span></code></pre><h3 id="15-2-well-known-is-invalid-or-missing">15.2 .well-known is invalid or missing</h3> <ul> <li>Verify the <code>.well-known</code> delegation from your root domain (served by <a href="../nginx_webserver/">Nginx server</a>):</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -s</span><span style="color: #9ECBFF;"> https://your-domain.com/.well-known/matrix/server</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> jq</span></span> <span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -s</span><span style="color: #9ECBFF;"> https://your-domain.com/.well-known/matrix/client</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> jq</span></span></code></pre> <ul> <li>Re-check that the placeholders in <code>conf/nginx.conf</code> were replaced via <code>sed</code> and that CORS headers middleware uses camelCase keys in Traefik labels (e.g., <code>accessControlAllowOriginList</code>).</li> </ul> <h3 id="15-3-traefik-crowdsec-middleware-not-applied">15.3 Traefik/CrowdSec middleware not applied</h3> <ul> <li>Ensure you reference providers correctly: <ul> <li>Security headers: <code>security-headers@file</code></li> <li>CrowdSec bouncer: <code>crowdsec-bouncer@docker</code></li> </ul> </li> </ul> <h3 id="15-4-acme-tls-issues">15.4 ACME/TLS issues</h3> <ul> <li>Inspect Traefik logs for ACME errors and DNS problems:</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose logs</span><span style="color: #79B8FF;"> -n 200</span><span style="color: #9ECBFF;"> traefik</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> tail</span><span style="color: #79B8FF;"> -n 200</span></span></code></pre> <ul> <li>Confirm A/AAAA records for <code>traefik.your-domain.com</code> and <code>matrix.your-domain.com</code> point to your server and that port 443 is reachable.</li> <li><strong>Disable CDN Proxy for Initial Certificate:</strong> If you are using a CDN like Cloudflare, ensure the proxy is disabled (set to “DNS Only” or “grey cloud”) for your domains during the first certificate request. The HTTP-01 challenge requires Let’s Encrypt to reach your server directly. You can re-enable the proxy after the certificate is issued.</li> </ul> <h3 id="15-5-docker-network-not-found">15.5 Docker network not found</h3> <ul> <li>Make sure the external <code>proxy</code> network exists and is used by all services behind Traefik:</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> network ls</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> grep</span><span style="color: #9ECBFF;"> proxy</span><span style="color: #F97583;"> ||</span><span style="color: #B392F0;"> docker</span><span style="color: #9ECBFF;"> network create proxy</span></span></code></pre><h3 id="15-6-permission-problems-in-inventory-host-vars">15.6 Permission problems in inventory/host_vars</h3> <ul> <li>If editing files is cumbersome, you can align ownership (optional):</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> chown</span><span style="color: #79B8FF;"> -R</span><span style="color: #9ECBFF;"> &quot;</span><span>$USER</span><span style="color: #9ECBFF;">&quot;:&quot;</span><span>$USER</span><span style="color: #9ECBFF;">&quot; /opt/containers/matrix/inventory</span></span></code></pre><h3 id="15-7-ansible-venv-not-active">15.7 Ansible/venv not active</h3> <ul> <li>If you installed Ansible in a virtualenv, reactivate it before running playbooks:</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">source</span><span style="color: #9ECBFF;"> ~/.venvs/matrix-ansible/bin/activate</span></span></code></pre><h3 id="15-8-crowdsec-bouncer-not-registered">15.8 CrowdSec bouncer not registered</h3> <ul> <li>Check the bouncer status inside the CrowdSec container (run in your Traefik stack directory):</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose exec crowdsec cscli bouncers list</span></span></code></pre><h2 id="conclusion">Conclusion</h2> <p>You now have a fully functional, federated Matrix Synapse homeserver integrated with your Traefik proxy and Nginx web server. This powerful setup not only gives you control over your own secure communications but is also extensible with numerous bridges and features, allowing you to create a central hub for all your chat services.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;spantaleev&#x2F;matrix-docker-ansible-deploy&#x2F;blob&#x2F;master&#x2F;docs&#x2F;README.md" class="retro-button"> <span class="emoji">📚</span><span class="button-text">PLAYBOOK DOCUMENTATION</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;matrix.org&#x2F;docs&#x2F;" class="retro-button"> <span class="emoji">🛡️</span><span class="button-text">MATRIX DOCUMENTATION</span> </a> </p> Git & GitHub for Beginners: Navigating the Version Control Labyrinth Sat, 07 Feb 2026 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/git-tutorial-cheatsheet/ https://criticalbasics.xyz/posts/git-tutorial-cheatsheet/ <p>Welcome, intrepid coder, to the world of <a rel="noopener external" target="_blank" href="https://git-scm.com/">Git</a> and <a rel="noopener external" target="_blank" href="https://github.com/">GitHub</a>! This guide cuts through the noise to give you a solid understanding of version control, focusing on the practical steps and common pitfalls encountered in daily development. We’ll demystify local Git versus online platforms, walk through essential commands, and tackle the ever-present authentication headaches with solutions drawn from real-world scenarios.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2026-02-07</td><td>Initial Version: Guide created for beginners with practical tips, authentication troubleshooting, and common workflow patterns.</td></tr> </tbody></table> </div> <hr /> <h1 id="1-git-vs-github-a-tale-of-two-systems">1. Git vs. GitHub: A Tale of Two Systems</h1> <p>Understanding the distinction between <a rel="noopener external" target="_blank" href="https://git-scm.com/">Git</a> (the tool) and <a rel="noopener external" target="_blank" href="https://github.com/">GitHub</a> (the service) is foundational.</p> <h3 id="local-git">Local Git</h3> <p><a rel="noopener external" target="_blank" href="https://git-scm.com/">Git</a> is a <strong>version control system</strong> that lives on your computer. It meticulously tracks the history of your project as a series of <strong>commits</strong>.</p> <ul> <li><strong>Repository (Repo)</strong>: This is your project folder, distinguished by a hidden <code>.git/</code> directory.</li> <li><strong>Commit</strong>: A “snapshot” of your changes at a specific point in time.</li> <li><strong>Branch</strong>: An independent line of development (e.g., <code>main</code>, <code>feature/my-new-thing</code>).</li> <li><strong>Remote</strong>: A counterpart of your local repository hosted on a server (e.g., <a rel="noopener external" target="_blank" href="https://github.com/">GitHub</a>).</li> </ul> <h3 id="github-com">GitHub.com</h3> <p><a rel="noopener external" target="_blank" href="https://github.com/">GitHub</a> is a <strong>hosting service</strong> built around Git repositories. It offers a suite of tools for collaborative development:</p> <ul> <li>Stores repositories online (publicly or privately).</li> <li>Facilitates collaboration through Pull Requests, Issues, and Code Reviews.</li> <li>Provides Continuous Integration/Continuous Deployment (CI/CD) with <a rel="noopener external" target="_blank" href="https://docs.github.com/en/actions">GitHub Actions</a>.</li> <li>Can host container images and packages (e.g., <a rel="noopener external" target="_blank" href="https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry">GitHub Container Registry (GHCR)</a>: <code>ghcr.io/...</code>).</li> </ul> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ KEY TAKEAWAY </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Git can function entirely without GitHub. GitHub <em>enhances</em> Git by providing cloud hosting and robust collaboration features.</p> </td> </tr> </table> <hr /> <h1 id="2-open-source-alternatives-to-github">2. Open-Source Alternatives to GitHub</h1> <p>If you prefer self-hosting or exploring other platforms, these are excellent alternatives that all speak the same Git language:</p> <ul> <li><strong><a rel="noopener external" target="_blank" href="https://about.gitlab.com/">GitLab CE/EE</a></strong>: GitLab Community Edition is fully open-source, offering a comprehensive suite of DevOps tools.</li> <li><strong><a rel="noopener external" target="_blank" href="https://gitea.io/">Gitea</a></strong>: A lightweight, self-hostable Git service, popular for its ease of deployment and minimal resource footprint.</li> <li><strong><a rel="noopener external" target="_blank" href="https://forgejo.org/">Forgejo</a></strong>: A community-driven fork of Gitea, focused on open governance.</li> <li><strong><a rel="noopener external" target="_blank" href="https://sourcehut.org/">SourceHut</a></strong>: A minimalist, “Git-first” development platform.</li> </ul> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 UNIVERSAL COMMANDS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Regardless of the platform, your local Git commands remain almost identical. This is the power of Git!</p> </td> </tr> </table> <hr /> <h1 id="3-the-typical-workflow-six-key-concepts-visualized">3. The Typical Workflow: Six Key Concepts &amp; Visualized</h1> <p>To master Git, grasp these six core areas, and visualize their flow.</p> <ul> <li><strong>Working Tree</strong>: The actual files in your project directory, including any uncommitted changes.</li> <li><strong>Staging Area / Index</strong>: A temporary area where you select which changes will be included in your <em>next</em> commit.</li> <li><strong>Commit History</strong>: The chronological record of all your project’s commits.</li> <li><strong>Branch</strong>: The current line of development you are working on.</li> <li><strong>Remote <code>origin</code></strong>: The URL pointing to your online repository (often called <code>origin</code> by default).</li> <li><strong>Push/Pull</strong>: The actions of sending (pushing) or receiving (pulling) changes between your local repository and the remote.</li> </ul> <h3 id="visualizing-the-workflow">Visualizing the Workflow</h3> <p>A simple mental model helps understand the core Git flow:</p> <!-- ASCII-Art Shortcode - Kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: ascii_art() mit ASCII-Kunst als Inhalt --> <pre style="font-family: 'Perfect DOS VGA 437', monospace; line-height: 1.0; color: #e0e0e0; background-color: #121212; padding: 15px; border: 1px solid #666666; overflow: auto; white-space: pre; font-size: 14px;">Working Directory (Your files) ↓ (`git add`) Staging Area (Index) ↓ (`git commit`) Local Repository (Commit history) ↓ (`git push`) Remote Repository ([GitHub](https:&#x2F;&#x2F;github.com&#x2F;), [GitLab](https:&#x2F;&#x2F;about.gitlab.com&#x2F;), etc.) ↓ (`git pull`) (Back to Working Directory for others)</pre> <hr /> <h1 id="4-initial-setup-a-clean-start">4. Initial Setup: A Clean Start</h1> <p>Setting up Git correctly from the beginning prevents many headaches.</p> <h3 id="4-1-set-your-git-identity-for-commits">4.1. Set Your Git Identity (For Commits)</h3> <p>These details define the <strong>author</strong> of your commits; they are <em>not</em> your login credentials for GitHub. The <code>user.name</code> and <code>user.email</code> you set here are what will appear in the commit history on platforms like GitHub.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config</span><span style="color: #79B8FF;"> --global</span><span style="color: #9ECBFF;"> user.name &quot;Your Name&quot;</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config</span><span style="color: #79B8FF;"> --global</span><span style="color: #9ECBFF;"> user.email &quot;your-email@example.com&quot;</span></span></code></pre><h4 id="how-to-check-your-current-git-identity">How to Check Your Current Git Identity</h4> <p>To see what <code>user.name</code> and <code>user.email</code> are currently set for your active repository or globally:</p> <p><strong>For the current repository:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config user.name</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config user.email</span></span></code></pre> <p><strong>Globally (for all repositories):</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config</span><span style="color: #79B8FF;"> --global</span><span style="color: #9ECBFF;"> user.name</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config</span><span style="color: #79B8FF;"> --global</span><span style="color: #9ECBFF;"> user.email</span></span></code></pre><h4 id="how-to-change-your-git-identity">How to Change Your Git Identity</h4> <p>To change your Git identity:</p> <p><strong>Globally (recommended for most users, applies to all new repos):</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config</span><span style="color: #79B8FF;"> --global</span><span style="color: #9ECBFF;"> user.name &quot;Your New Name&quot;</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config</span><span style="color: #79B8FF;"> --global</span><span style="color: #9ECBFF;"> user.email &quot;your-new-email@domain.tld&quot;</span></span></code></pre> <p><strong>For only the current repository (overrides global settings for this repo):</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config user.name &quot;Project Specific Name&quot;</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config user.email &quot;project-email@domain.tld&quot;</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ EXISTING COMMITS RETAIN THEIR AUTHOR </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Changing these settings only affects <strong>future commits</strong>. Commits you have already made will retain the <code>user.name</code> and <code>user.email</code> that were active at the time of their creation. Rewriting history for already-pushed commits is possible but complex and generally not recommended for beginners.</p> </td> </tr> </table> <h3 id="4-2-initialize-or-clone-a-repository">4.2. Initialize or Clone a Repository</h3> <p>There are two main ways to start:</p> <ul> <li><strong>Clone an existing repository</strong>: This is standard for team projects or contributing to open source.<pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Using HTTPS</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> clone https://github.com/ORG/REPO.git</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Using SSH</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> clone git@github.com:ORG/REPO.git</span></span></code></pre></li> <li><strong>Initialize a brand-new project</strong>: If you’re starting a project from scratch on your local machine.<pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #9ECBFF;"> my-new-project</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> my-new-project</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> init</span></span></code></pre>You can then connect it to a remote repository later once you create one online.</li> </ul> <h3 id="4-3-check-your-remotes">4.3. Check Your Remotes</h3> <p>Confirm the remote repository is correctly configured:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> remote</span><span style="color: #79B8FF;"> -v</span></span></code></pre> <hr /> <h1 id="5-essential-commands-your-daily-toolkit">5. Essential Commands: Your Daily Toolkit</h1> <p>Here are the most frequently used Git commands and their purposes.</p> <h3 id="status-overview">Status &amp; Overview</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> status</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> log</span><span style="color: #79B8FF;"> --oneline --decorate -n 20</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> diff</span></span></code></pre><h3 id="stage-files-prepare-for-commit">Stage Files (Prepare for Commit)</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> add .</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Or stage specific files:</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> add path/to/file</span></span></code></pre><h3 id="create-a-commit">Create a Commit</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> commit</span><span style="color: #79B8FF;"> -m</span><span style="color: #9ECBFF;"> &quot;Brief, descriptive message&quot;</span></span></code></pre><h3 id="push-pull-explained">Push / Pull Explained</h3> <ul> <li><code>git push</code>: Sends your local commits to the remote repository.</li> <li><code>git pull</code>: <strong>Fetches</strong> changes from the remote <em>and then</em> <strong>merges</strong> them into your current local branch.</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> push</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> pull</span><span style="color: #6A737D;"> # = git fetch + git merge</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 AVOID ACCIDENTAL MERGE COMMITS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>For a cleaner history, especially when working on a personal branch, consider using <code>git pull --rebase</code>. This fetches remote changes and then re-applies your local commits <em>on top</em> of them, avoiding an explicit merge commit.</p> </td> </tr> </table> <h3 id="branching-typical-workflow">Branching (Typical Workflow)</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> checkout</span><span style="color: #79B8FF;"> -b</span><span style="color: #9ECBFF;"> feature/my-new-feature</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> push</span><span style="color: #79B8FF;"> -u</span><span style="color: #9ECBFF;"> origin feature/my-new-feature</span></span></code></pre><h3 id="mini-example-your-first-commit">Mini-Example: Your First Commit!</h3> <p>Let’s try a complete cycle:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># 1. Create a new directory and initialize Git</span></span> <span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #9ECBFF;"> my-first-repo</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> my-first-repo</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> init</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 2. Create a file</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;Hello, Git World!&quot;</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> index.html</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 3. Check status (it&#39;s untracked)</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> status</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 4. Stage the file</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> add index.html</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 5. Check status again (it&#39;s staged)</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> status</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 6. Commit the file</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> commit</span><span style="color: #79B8FF;"> -m</span><span style="color: #9ECBFF;"> &quot;Add initial homepage with Hello World&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 7. Check log (see your commit)</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> log</span><span style="color: #79B8FF;"> --oneline</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># At this point, you&#39;d typically connect to a remote and push.</span></span> <span class="giallo-l"><span style="color: #6A737D;"># For now, you have a local commit!</span></span></code></pre> <hr /> <h1 id="6-ignoring-files-with-gitignore">6. Ignoring Files with <code>.gitignore</code></h1> <p>Not every file belongs in your repository. Temporary files, build artifacts, and sensitive data should be ignored.</p> <h3 id="why-is-node-modules-or-target-in-my-git">Why is <code>node_modules</code> (or <code>target/</code>) in my Git?!</h3> <p>This is a common beginner question. Files generated by your build system (like <code>node_modules</code> for JavaScript or <code>target/</code> for Rust) should <em>not</em> be committed. They bloat your repository and cause unnecessary merge conflicts.</p> <h3 id="how-to-use-gitignore">How to Use <code>.gitignore</code></h3> <p>Create a file named <code>.gitignore</code> in the root of your repository and list the files or directories you want Git to ignore.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Example .gitignore content</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Node.js dependencies</span></span> <span class="giallo-l"><span style="color: #B392F0;">node_modules/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Logs</span></span> <span class="giallo-l"><span style="color: #F97583;">*</span><span>.log</span></span> <span class="giallo-l"><span style="color: #B392F0;">npm-debug.log*</span></span> <span class="giallo-l"><span style="color: #B392F0;">yarn-debug.log*</span></span> <span class="giallo-l"><span style="color: #B392F0;">yarn-error.log*</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># OS generated files</span></span> <span class="giallo-l"><span style="color: #B392F0;">.DS_Store</span></span> <span class="giallo-l"><span style="color: #B392F0;">.env</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Build artifacts (e.g., for Rust)</span></span> <span class="giallo-l"><span style="color: #B392F0;">target/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Your application&#39;s local settings (if applicable)</span></span> <span class="giallo-l"><span style="color: #B392F0;">config/local.yaml</span></span></code></pre><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># To create and add to .gitignore:</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;node_modules/&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;"> .gitignore</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;*.log&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;"> .gitignore</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> add .gitignore</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> commit</span><span style="color: #79B8FF;"> -m</span><span style="color: #9ECBFF;"> &quot;Add .gitignore to exclude common temporary files&quot;</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 EFFECTIVE .GITIGNORE </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Make sure <code>.gitignore</code> is committed <em>before</em> you add any files that should be ignored. If files are already tracked, adding them to <code>.gitignore</code> won’t untrack them. You’d need <code>git rm --cached &lt;file&gt;</code> first.</p> </td> </tr> </table> <hr /> <h1 id="7-crucial-context-accounts-vs-repository-permissions">7. Crucial Context: Accounts vs. Repository Permissions</h1> <p>This is where many newcomers (and even seasoned pros) stumble.</p> <h3 id="github-account-personal-vs-company-organization-repository">GitHub Account (Personal) vs. Company/Organization Repository</h3> <p>On GitHub, repositories are often owned by an <strong>Organization</strong> (e.g., <code>DELIGHTFUL-corp/my-project</code>).</p> <ul> <li>You log in with a <strong>GitHub User Account</strong> (which might be your personal one).</li> <li>This user account needs <strong>permissions</strong> (e.g., <code>WRITE</code>, <code>MAINTAIN</code>, <code>ADMIN</code>) within the Organization’s repository.</li> <li>Without sufficient permissions, you might be able to read the repository but not push changes.</li> </ul> <h3 id="common-pitfall-the-identity-crisis">Common Pitfall: The Identity Crisis</h3> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ THE STEALTHY &#x27;REPOSITORY NOT FOUND&#x27; ERROR </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>A classic issue: you’re logged into GitHub in your browser with Account A, but Git on your command line is using cached credentials from Account B. This often results in “repository not found” errors for private repos even when you believe you have access.</p> </td> </tr> </table> <p><strong>Symptom:</strong> Your <code>git push</code> fails, even though you “know” you have access to the repository. The error message is often misleading (<code>fatal: repository 'https://github.com/ORG/REPO.git/' not found</code>) rather than an explicit “permission denied.” GitHub frequently returns a <strong>404</strong> (“not found”) for private repositories when permissions are lacking, to avoid leaking the existence of private repos.</p> <hr /> <h1 id="8-authentication-https-vs-ssh-and-why-your-error-happened">8. Authentication: HTTPS vs. SSH (And Why Your Error Happened)</h1> <p>Authentication methods can be a source of confusion.</p> <h3 id="https-token-credentials">HTTPS (Token/Credentials)</h3> <p>With HTTPS, Git requires authentication details. While passwords were used in the past, today it’s almost always:</p> <ul> <li>A <strong><a rel="noopener external" target="_blank" href="https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens">Personal Access Token (PAT)</a></strong>, or</li> <li>The <strong><a rel="noopener external" target="_blank" href="https://cli.github.com/">GitHub CLI</a> (<code>gh</code>)</strong> managing a token for you automatically. The GitHub CLI is an <strong>optional but highly recommended</strong> tool for smoother authentication workflows.</li> </ul> <h4 id="installing-github-cli">Installing GitHub CLI</h4> <p><strong>Debian/Ubuntu:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt update</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt install gh</span></span></code></pre> <p><strong>Arch Linux:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> github-cli</span></span></code></pre> <p><strong>Your specific stumbling block was classic:</strong></p> <ul> <li><code>gh repo view ... viewerPermission</code> correctly showed <code>ADMIN</code> (meaning permissions were there).</li> <li>But <code>git ls-remote origin HEAD</code> reported <code>Repository not found</code>.</li> <li>This often happens when Git uses <strong>incorrect or cached credentials</strong>.</li> </ul> <h3 id="the-fix-from-your-real-world-case">The Fix (from your real-world case)</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gh</span><span style="color: #9ECBFF;"> auth login</span></span> <span class="giallo-l"><span style="color: #B392F0;">gh</span><span style="color: #9ECBFF;"> auth setup-git</span></span></code></pre> <p>This sequence ensures that Git is configured to use the credentials managed by the GitHub CLI for <code>https://github.com/...</code> remotes.</p> <h3 id="ssh-keys">SSH (Keys)</h3> <p>SSH is often more “set it and forget it” once correctly configured:</p> <ul> <li>You add an <a rel="noopener external" target="_blank" href="https://docs.github.com/en/authentication/connecting-to-github-with-ssh">SSH public key</a> to your GitHub account.</li> <li>Your remote URL will look like <code>git@github.com:ORG/REPO.git</code>.</li> <li>SSH authentication is handled by your SSH agent, not Git’s credential storage. This setup avoids credential helper conflicts, making it robust for many users.</li> </ul> <hr /> <h1 id="9-troubleshooting-checklist-when-git-push-acts-up">9. Troubleshooting Checklist: When <code>git push</code> Acts Up</h1> <p>If <code>git push</code> fails, go through this checklist.</p> <h3 id="9-1-is-the-remote-correct">9.1. Is the Remote Correct?</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> remote</span><span style="color: #79B8FF;"> -v</span></span></code></pre><h3 id="9-2-can-you-even-see-the-repository-authenticating-access">9.2. Can You Even “See” the Repository? (Authenticating Access)</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> ls-remote origin HEAD</span></span></code></pre> <p>If this command fails with “repository not found” or “authentication failed,” the issue is almost certainly <strong>authentication, the remote URL, or your permissions</strong>. This is the first diagnostic step for “git push repository not found” problems.</p> <h3 id="9-3-which-github-identity-is-active-gh-cli">9.3. Which GitHub Identity is Active (GH CLI)?</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gh</span><span style="color: #9ECBFF;"> auth status</span></span></code></pre><h3 id="9-4-what-permissions-do-you-have">9.4. What Permissions Do You Have?</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gh</span><span style="color: #9ECBFF;"> repo view ORG/REPO</span><span style="color: #79B8FF;"> --json</span><span style="color: #9ECBFF;"> viewerPermission</span></span></code></pre><h3 id="9-5-if-https-credentials-are-stuck-re-link">9.5. If HTTPS Credentials are Stuck: Re-link</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gh</span><span style="color: #9ECBFF;"> auth setup-git</span></span></code></pre><h3 id="9-6-clear-cached-credentials-if-necessary">9.6. Clear Cached Credentials (If Necessary)</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">printf</span><span style="color: #9ECBFF;"> &quot;protocol=https\nhost=github.com\n\n&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> git</span><span style="color: #9ECBFF;"> credential reject</span></span></code></pre> <hr /> <h1 id="10-your-minimal-daily-workflow">10. Your Minimal Daily Workflow</h1> <p>Once authentication is set up correctly (as it should be now), your daily routine is simple:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># 1. Start by pulling any remote changes (optional, but good practice)</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> pull</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 2. Check what you&#39;ve modified</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> status</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 3. Stage your changes</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> add .</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 4. Commit your changes</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> commit</span><span style="color: #79B8FF;"> -m</span><span style="color: #9ECBFF;"> &quot;Description of your changes&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 5. Push your changes to the remote repository</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> push</span></span></code></pre> <hr /> <h1 id="11-practical-rules-keeping-it-clean-long-term">11. Practical Rules: Keeping it Clean Long-Term</h1> <p>Adhere to these rules for a smoother Git experience.</p> <ul> <li><strong>One Identity Per Purpose</strong>: <ul> <li>GitHub Account (login) = Access &amp; Permissions.</li> <li>Git <code>user.name</code>/<code>user.email</code> = Commit Author (can be your company identity).</li> </ul> </li> <li><strong>For Private/Org Repos</strong>: Always ensure your GitHub user is explicitly part of the Organization’s team with the necessary permissions.</li> <li><strong>When Switching Accounts</strong>: After changing GitHub accounts (e.g., personal to work), always run <code>gh auth status</code> and potentially <code>gh auth setup-git</code> again. This is key to resolving “git authentication failed” issues.</li> <li><strong>When it says “Repository not found”</strong>: First, check <code>git ls-remote origin HEAD</code>. If that fails, it’s time to check your credentials and active account. This specific error often means your authentication is failing for “github 404 private repository” scenarios.</li> </ul> <hr /> <h1 id="12-managing-multiple-git-identities-e-g-work-vs-personal">12. Managing Multiple Git Identities (e.g., Work vs. Personal)</h1> <p>It’s common to work on different projects that require different Git identities (e.g., a work email/name for company projects and a personal one for open-source contributions). Git offers flexible ways to manage this.</p> <p>Git applies configurations in a specific order:</p> <ol> <li><strong>Repository-specific (<code>.git/config</code>):</strong> These settings override all others for the current repository.</li> <li><strong>Global (<code>~/.gitconfig</code>):</strong> These settings apply to all repositories that don’t have their own specific configuration.</li> <li><strong>System-wide (<code>$(prefix)/etc/gitconfig</code>):</strong> Least specific, rarely modified directly.</li> </ol> <h3 id="option-a-simple-set-identity-per-repository">Option A (Simple): Set Identity Per Repository</h3> <p>The easiest way to use different identities is to set them directly within each project’s folder. This overrides your global settings only for that specific repository.</p> <ol> <li><strong>Set your default global identity</strong> (e.g., your personal one, or the one you use most often):<pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config</span><span style="color: #79B8FF;"> --global</span><span style="color: #9ECBFF;"> user.name &quot;Your Default Name&quot;</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config</span><span style="color: #79B8FF;"> --global</span><span style="color: #9ECBFF;"> user.email &quot;your-default@mail.tld&quot;</span></span></code></pre></li> <li><strong>Navigate to a specific project folder</strong> (e.g., a work project).</li> <li><strong>Set the identity for <em>only this repository</em>:</strong><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config user.name &quot;Work Name&quot;</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config user.email &quot;work@company.com&quot;</span></span></code></pre>This creates/modifies the <code>.git/config</code> file in that repository.</li> </ol> <p>To verify the local settings:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config</span><span style="color: #79B8FF;"> --local</span><span style="color: #9ECBFF;"> user.name</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> config</span><span style="color: #79B8FF;"> --local</span><span style="color: #9ECBFF;"> user.email</span></span></code></pre><h3 id="option-b-advanced-conditional-includes-for-directories">Option B (Advanced): Conditional Includes for Directories</h3> <p>If you organize your projects into separate top-level directories (e.g., <code>~/work/company-projects/</code> and <code>~/personal-projects/</code>), you can use Git’s <code>includeIf</code> directive. This automatically applies different configurations based on the path of the repository.</p> <ol> <li> <p><strong>Define your default global identity</strong> in <code>~/.gitconfig</code> (e.g., your personal one):</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #6A737D;"># ~/.gitconfig</span></span> <span class="giallo-l"><span style="color: #B392F0;">[user]</span></span> <span class="giallo-l"><span style="color: #F97583;"> name</span><span> = Dude (Personal)</span></span> <span class="giallo-l"><span style="color: #F97583;"> email</span><span> = dude.personal@mail.tld</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">[includeIf &quot;gitdir:~/work/delightful/&quot;]</span></span> <span class="giallo-l"><span style="color: #F97583;"> path</span><span> = ~/.gitconfig-delightful</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">[includeIf &quot;gitdir:~/personal-projects/&quot;]</span></span> <span class="giallo-l"><span style="color: #F97583;"> path</span><span> = ~/.gitconfig-personal</span></span></code></pre> <p><em>Note: The <code>gitdir:</code> path should end with a <code>/</code> to indicate a directory. Make sure these paths exist on your system.</em></p> </li> <li> <p><strong>Create separate configuration files</strong> for each specific context.</p> <p><strong><code>~/.gitconfig-delightful</code>:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #B392F0;">[user]</span></span> <span class="giallo-l"><span style="color: #F97583;"> name</span><span> = DELIGHTFUL Inc.</span></span> <span class="giallo-l"><span style="color: #F97583;"> email</span><span> = dude.work@delightful.tld</span></span></code></pre> <p><strong><code>~/.gitconfig-personal</code>:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #B392F0;">[user]</span></span> <span class="giallo-l"><span style="color: #F97583;"> name</span><span> = Dude (Open Source)</span></span> <span class="giallo-l"><span style="color: #F97583;"> email</span><span> = dude.opensource@mail.tld</span></span></code></pre></li> </ol> <p>Now, when you enter a repository within <code>~/work/delightful/</code>, Git will automatically use the <code>DELIGHTFUL Inc.</code> identity. When you’re in <code>~/personal-projects/</code>, it will use <code>Dude (Open Source)</code>. Any other repository will fall back to the default <code>Dude (Personal)</code>.</p> <h3 id="what-if-you-use-multiple-github-accounts-not-just-identities">What if You Use Multiple GitHub Accounts (not just identities)?</h3> <p>If you manage entirely separate GitHub accounts (e.g., <code>github.com/my-personal-account</code> and <code>github.com/my-work-account</code>), you’ll also need to configure <strong>separate SSH keys and SSH host aliases</strong> in your <code>~/.ssh/config</code> file. This tells Git which SSH key to use when connecting to <code>github.com</code> for specific projects. This setup is more advanced and beyond the scope of this beginner tutorial, but it’s important to be aware of it.</p> <!-- Retro-Trennlinie Shortcode - Kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: retro_divider(style="dots") --> <!-- Styles: dots, double, dashed, solid, shadow --> <hr size="2" noshade color="#666666" style="margin: 15px 0; border-style: double;"> <h2 id="conclusion">Conclusion</h2> <p>You’re now equipped with the knowledge to navigate Git and GitHub with confidence! We’ve covered the fundamentals, delved into the crucial authentication challenges, and provided a clear path to troubleshooting common issues like “git push repository not found.” Understanding how to manage your Git identity, especially across multiple projects, will streamline your workflow significantly. Version control can seem daunting, but with these principles and tools, you’ll be committing and collaborating like a pro in no time.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;git-scm.com&#x2F;doc" class="retro-button"> <span class="emoji">📚</span><span class="button-text">OFFICIAL GIT DOCUMENTATION</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;docs.github.com&#x2F;" class="retro-button"> <span class="emoji">📦</span><span class="button-text">GITHUB DOCUMENTATION</span> </a> </p> Self-hosting Immich with Docker, Traefik, and CrowdSec Thu, 15 Jan 2026 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/immich/ https://criticalbasics.xyz/posts/immich/ <p><a rel="noopener external" target="_blank" href="https://immich.app/">Immich</a> is currently the most powerful open-source alternative to Google Photos. It offers high-performance backup, AI-driven face recognition, and a polished mobile app. This guide focuses on a robust deployment using Docker Compose, integrating it into our <strong><a href="../traefik-v3-crowdsec-tutorial/">existing Traefik v3 reverse proxy</a></strong> and securing it with the CrowdSec IPS.</p> <p>By placing Immich behind Traefik, we benefit from automatic TLS certificates and a central entry point for our mobile devices, while CrowdSec protects our personal memories from brute-force and bot attacks.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2026-01-15</td><td><strong>Initial Version:</strong> Immich v1.12x+, Traefik v3 integration, pgvector, and specific CrowdSec bypass notes for mobile sync.</td></tr> </tbody></table> </div> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>This deployment assumes you have followed our foundational security stack guide. Immich is resource-intensive, especially during the initial scan of your library.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ HARD REQUIREMENT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The following steps will not work correctly without the Traefik stack running as described in the prerequisite guide:</p> <ul> <li><strong><a href="../traefik-v3-crowdsec-tutorial/">Traefik v3 and CrowdSec with Docker Compose</a></strong>: This provides the <code>proxy</code> network and the <code>crowdsec-bouncer</code> middleware.</li> </ul> </td> </tr> </table> <p><strong>System Recommendations:</strong></p> <ul> <li><strong>RAM:</strong> Minimum 4GB (8GB+ recommended for AI/Machine Learning).</li> <li><strong>Storage:</strong> A large dedicated disk or mount point for your photo library.</li> <li><strong>Domain:</strong> A subdomain like <code>photos.your-domain.com</code>.</li> </ul> <h2 id="2-directory-structure">2. Directory Structure</h2> <p>Immich requires several volumes for its database, machine learning cache, and the actual photo library.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Create the main directory</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> /opt/containers/immich</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/immich</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Create directories for data persistence</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> volumes/db</span><span style="color: #6A737D;"> # Postgres data</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> volumes/library</span><span style="color: #6A737D;"> # Your actual photos/videos</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> volumes/model-cache</span><span style="color: #6A737D;"> # AI models</span></span></code></pre><h2 id="3-configuration">3. Configuration</h2> <p>Immich uses a <code>.env</code> file for core settings and a <code>docker-compose.yml</code> for service orchestration.</p> <h3 id="3-1-generate-database-password">3.1. Generate Database Password</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span>DB_PASSWORD</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">openssl</span><span style="color: #9ECBFF;"> rand</span><span style="color: #79B8FF;"> -hex 32</span><span>)</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;Your Immich DB password: </span><span>$DB_PASSWORD</span><span style="color: #9ECBFF;">&quot;</span></span></code></pre><h3 id="3-2-environment-variables-env">3.2. Environment Variables (<code>.env</code>)</h3> <p>Create the <code>.env</code> file. Replace placeholders with your values.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee .env</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> EOF</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># --- Database ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">DB_PASSWORD=</span><span>$DB_PASSWORD</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">DB_USERNAME=immich</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">DB_DATABASE_NAME=immich</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"># --- System ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">TZ=Europe/Vienna</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">IMMICH_VERSION=release</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"># --- Library Location ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Ensure this path has sufficient space (ideally a dedicated disk)</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">UPLOAD_LOCATION=./volumes/library</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"># --- Domain ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">DOMAIN_NAME=photos.your-domain.com</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><h3 id="3-3-docker-compose-docker-compose-yml">3.3. Docker Compose (<code>docker-compose.yml</code>)</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee docker-compose.yml</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">services:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> immich-server:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: immich_server</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ${UPLOAD_LOCATION}:/usr/src/app/upload</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - /etc/localtime:/etc/localtime:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> env_file:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - .env</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> depends_on:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - redis</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - database</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - proxy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - immich-net</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> labels:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.immich.rule=Host(`${DOMAIN_NAME}`)&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.immich.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.immich.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # See Section 4.3 for opting out of CrowdSec if needed</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.immich.middlewares=security-headers@file,crowdsec-bouncer@docker&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.services.immich.loadbalancer.server.port=2283&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> immich-machine-learning:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: immich_machine_learning</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./volumes/model-cache:/cache</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> env_file:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - .env</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - immich-net</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> redis:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: immich_redis</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: redis:6.2-alpine</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - immich-net</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> database:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: immich_postgres</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: tensorchord/pgvecto-rs:pg16-v0.2.0</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> environment:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> POSTGRES_PASSWORD: ${DB_PASSWORD}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> POSTGRES_USER: ${DB_USERNAME}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> POSTGRES_DB: ${DB_DATABASE_NAME}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./volumes/db:/var/lib/postgresql/data</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - immich-net</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> external: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> immich-net:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> driver: bridge</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><h2 id="4-hardware-security-tuning">4. Hardware &amp; Security Tuning</h2> <h3 id="4-1-hardware-acceleration-optional">4.1. Hardware Acceleration (Optional)</h3> <p>Using an iGPU or GPU speeds up video transcoding and AI processing significantly.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 TRANSCODING &amp; ML </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>To enable Intel QuickSync, add the following to both <code>immich-server</code> (for video) and <code>immich-machine-learning</code> (for AI) in your <code>docker-compose.yml</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #85E89D;">devices</span><span>:</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> /dev/dri:/dev/dri</span></span></code></pre> </td> </tr> </table> <h3 id="4-2-mobile-apps-crowdsec">4.2. Mobile Apps &amp; CrowdSec</h3> <p>Immich mobile apps (especially on iOS) perform many rapid requests during background synchronization.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ MOBILE SYNC &amp; FALSE POSITIVES </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>If you experience “Connection Lost” or sync issues in the mobile app, check your CrowdSec decisions (<code>cscli decisions list</code>). Frequent background requests can sometimes trigger rate-limiting or bot-detection scenarios.</p> </td> </tr> </table> <h3 id="4-3-running-immich-without-crowdsec-optional">4.3. Running Immich without CrowdSec (Optional)</h3> <p>If you find that the CrowdSec middleware frequently interferes with your mobile backups, you can choose to bypass it for Immich specifically while keeping your other services protected.</p> <p>To disable CrowdSec for Immich, update the labels in your <code>docker-compose.yml</code> by removing <code>crowdsec-bouncer@docker</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #6A737D;"># In the immich-server labels section:</span></span> <span class="giallo-l"><span>-</span><span style="color: #9ECBFF;"> &quot;traefik.http.routers.immich.middlewares=security-headers@file&quot;</span></span></code></pre> <p>For more details on why you might want to do this, see:</p> <ul> <li><strong><a href="../traefik-v3-crowdsec-tutorial/#5-2-scenario-2-service-bypassing-crowdsec-special-case">Scenario 2: Service Bypassing CrowdSec</a></strong></li> </ul> <h2 id="5-maintenance-backup">5. Maintenance &amp; Backup</h2> <h3 id="updating-immich">Updating Immich</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/immich</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose pull</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose up</span><span style="color: #79B8FF;"> -d</span></span></code></pre><h3 id="backup-strategy">Backup Strategy</h3> <p><strong>Gezieltes Database Backup:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Export only the &#39;immich&#39; database for a cleaner dump</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose exec</span><span style="color: #79B8FF;"> -t</span><span style="color: #9ECBFF;"> database pg_dump</span><span style="color: #79B8FF;"> -U</span><span style="color: #9ECBFF;"> immich immich</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> immich_db_backup_</span><span>$(</span><span style="color: #B392F0;">date</span><span style="color: #9ECBFF;"> +%F</span><span>)</span><span style="color: #9ECBFF;">.sql</span></span></code></pre><h2 id="conclusion">Conclusion</h2> <p>You now have a secure, high-performance photo management system. By integrating Immich with Traefik and CrowdSec (or selectively bypassing it for sync reliability), you achieve a “Google Photos” experience while maintaining full control over your private data.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;immich.app&#x2F;docs&#x2F;overview&#x2F;introduction" class="retro-button"> <span class="emoji">📚</span><span class="button-text">OFFICIAL IMMICH DOCS</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;immich-app&#x2F;immich" class="retro-button"> <span class="emoji">📦</span><span class="button-text">IMMICH GITHUB</span> </a> </p> BIOS & Firmware Update on Framework 13 (AMD Ryzen AI 300) under Arch Linux Wed, 14 Jan 2026 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/framework-bios-update/ https://criticalbasics.xyz/posts/framework-bios-update/ <p>The Framework Laptop 13 (AMD Ryzen AI 300 Series) is a prime example of hardware designed with Linux in mind. Instead of needing a Windows environment or a separate bootable USB stick, Framework leverages the <strong>Linux Vendor Firmware Service (LVFS)</strong>. This guide outlines the exact, reproducible workflow to keep your system up to date using <code>fwupd</code> on Arch Linux.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2026-01-14</td><td><strong>Initial Version:</strong> Full protocol for Framework 13 (AMD Ryzen AI 300) BIOS updates.</td></tr> </tbody></table> </div> <hr /> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>Before starting the process, ensure your environment meets these requirements:</p> <ul> <li><strong>Hardware:</strong> Framework Laptop 13 (AMD Ryzen AI 300 Series, e.g., AI 9 HX 370).</li> <li><strong>Power:</strong> Power adapter <strong>must be connected</strong> and charging.</li> <li><strong>Partitioning:</strong> EFI System Partition (ESP) must be mounted (usually at <code>/boot</code> or <code>/efi</code>).</li> </ul> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ MANDATORY POWER CONNECTION </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The BIOS flash will refuse to start if the laptop is running on battery. Ensure your power cable is securely plugged in before proceeding.</p> </td> </tr> </table> <hr /> <h2 id="2-understanding-fwupd-lvfs">2. Understanding fwupd &amp; LVFS</h2> <p>Framework officially supports firmware updates via:</p> <ol> <li><strong>fwupd</strong>: The Firmware Update Daemon that manages the installation.</li> <li><strong>LVFS</strong>: The online repository where vendors upload their firmware.</li> </ol> <p>The process uses <strong>UEFI Capsules</strong>. <code>fwupd</code> stages the update on your EFI partition, and the actual “flashing” happens during the next reboot within the UEFI environment, not while Linux is running.</p> <hr /> <h2 id="3-installation">3. Installation</h2> <p>Install the necessary tools on Arch Linux using <code>pacman</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> fwupd fwupd-efi</span></span></code></pre> <p>The <code>fwupd.service</code> is a static systemd service. It doesn’t need to be “enabled”; it starts automatically when called. You can verify its status:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">systemctl</span><span style="color: #9ECBFF;"> status fwupd.service</span></span></code></pre> <hr /> <h2 id="4-refreshing-firmware-metadata">4. Refreshing Firmware Metadata</h2> <p>First, update the local database of available firmware from LVFS:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> fwupdmgr refresh</span></span></code></pre> <p>If prompted to enable the LVFS remote, confirm with <strong>Y</strong>.</p> <hr /> <h2 id="5-checking-for-updates">5. Checking for Updates</h2> <p>List all available updates for your hardware:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> fwupdmgr get-updates</span></span></code></pre> <p>You will likely see several entries, such as:</p> <ul> <li><strong>System Firmware</strong> (The BIOS/UEFI)</li> <li><strong>Fingerprint Sensor Firmware</strong></li> <li><strong>UEFI dbx</strong> (Secure Boot revocation list)</li> </ul> <hr /> <h2 id="6-performing-the-update">6. Performing the Update</h2> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ SAFETY FIRST </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>During the update:</p> <ul> <li>Do <strong>not</strong> power off the machine.</li> <li>Do <strong>not</strong> close the lid.</li> <li>Be patient. The screen may stay black for several minutes.</li> </ul> </td> </tr> </table> <p>Start the update process:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> fwupdmgr update</span></span></code></pre><h3 id="what-to-expect">What to expect:</h3> <ol> <li><strong>Fingerprint Sensor:</strong> This usually updates instantly without a reboot.</li> <li><strong>System Firmware (BIOS):</strong> This is the core update. <code>fwupd</code> will schedule it for the next boot.</li> <li><strong>UEFI dbx:</strong> Updates the Secure Boot blacklist. <em>(Note: If you use a custom Secure Boot setup with your own keys, review this step carefully before confirming.)</em></li> </ol> <hr /> <h2 id="7-the-reboot-flash-process">7. The Reboot &amp; Flash Process</h2> <p>After the command finishes, <code>fwupd</code> will prompt you to restart:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">A</span><span style="color: #9ECBFF;"> reboot is required to complete the update.</span></span></code></pre> <p><strong>What happens during reboot:</strong></p> <ul> <li>The system enters a special firmware update mode.</li> <li>The screen might remain black, and fans might spin up loudly.</li> <li><strong>Do not interrupt this.</strong> There might not be a visible progress bar depending on the specific firmware version.</li> </ul> <p>The system will automatically reboot into Arch Linux once the flash is complete.</p> <hr /> <h2 id="8-verifying-success">8. Verifying Success</h2> <p>Once back in your terminal, verify that all devices are on the latest version:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">fwupdmgr</span><span style="color: #9ECBFF;"> get-devices</span></span></code></pre> <p>Alternatively, check the version directly in the BIOS by pressing <strong>F2</strong> during startup. You should see the updated version number (e.g., <code>0.0.3.5</code>).</p> <hr /> <h2 id="summary">Summary</h2> <p>Updating firmware on a Framework laptop is a seamless experience that respects the user’s choice of OS:</p> <p>✅ Full BIOS update support under Linux ✅ No USB-Stick or Windows required ✅ Safe, transactional updates via UEFI Capsules ✅ Officially supported by Framework</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;knowledgebase.frame.work&#x2F;en_us&#x2F;framework-laptop-13-bios-and-driver-releases-amd-ryzen-ai-300-series-r1wqKAs1e" class="retro-button"> <span class="emoji">🔧</span><span class="button-text">OFFICIAL FRAMEWORK BIOS RELEASES</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;wiki.archlinux.org&#x2F;title&#x2F;Fwupd" class="retro-button"> <span class="emoji">📚</span><span class="button-text">ARCH WIKI: FWUPD</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;fwupd.org" class="retro-button"> <span class="emoji">🌐</span><span class="button-text">FWUPD PROJECT HOME</span> </a> </p> Enhancing Ranger with exiftool: Advanced Image Metadata Viewing Mon, 12 Jan 2026 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/ranger-exiftool-integration/ https://criticalbasics.xyz/posts/ranger-exiftool-integration/ <p>For photographers, designers, and anyone working with digital media, having quick access to file metadata is essential. This guide shows you how to integrate the powerful <code>exiftool</code> utility with the ranger file manager, allowing you to view comprehensive metadata for images and other media files without leaving your terminal.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2026-01-12</td><td><strong>Shortcut Update:</strong> Switched metadata shortcut from <code>ei</code> to <code>ii</code> (inspect/media prefix)</td></tr> <tr><td>2025-07-18</td><td><strong>Initial Version:</strong> Created guide for integrating exiftool with ranger</td></tr> </tbody></table> </div> <hr /> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>Before we begin, make sure you have the following tools installed:</p> <ul> <li><strong>ranger</strong>: The terminal file manager</li> <li><strong>exiftool</strong>: A powerful utility for reading, writing, and manipulating metadata</li> </ul> <h3 id="installation-on-various-distributions">Installation on Various Distributions</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># For Debian/Ubuntu</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt update</span><span> &amp;&amp;</span><span style="color: #B392F0;"> sudo</span><span style="color: #9ECBFF;"> apt install ranger libimage-exiftool-perl</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># For Arch Linux</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> ranger perl-image-exiftool</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># For Fedora</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> dnf install ranger perl-Image-ExifTool</span></span></code></pre> <hr /> <h2 id="2-creating-the-custom-exif-info-command">2. Creating the Custom exif_info Command</h2> <p>The integration requires adding a custom command to ranger that will use <code>exiftool</code> to display metadata for the selected file.</p> <h3 id="2-1-create-or-edit-commands-py">2.1. Create or Edit commands.py</h3> <p>First, navigate to your ranger configuration directory and create or edit the <code>commands.py</code> file:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.config/ranger</span></span> <span class="giallo-l"><span style="color: #B392F0;">touch</span><span style="color: #9ECBFF;"> ~/.config/ranger/commands.py</span></span></code></pre> <p>If you don’t have a <code>commands.py</code> file yet, you can generate a template with:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">ranger</span><span style="color: #79B8FF;"> --copy-config=commands</span></span></code></pre><h3 id="2-2-add-the-exif-info-command">2.2. Add the exif_info Command</h3> <p>Open the <code>commands.py</code> file in your favorite text editor and add the following code:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span style="color: #F97583;">from</span><span> ranger.api.commands</span><span style="color: #F97583;"> import</span><span> Command</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> mimetypes</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> os</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> shlex</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> shutil</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> subprocess</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">class</span><span style="color: #B392F0;"> exif_info</span><span>(</span><span style="color: #B392F0;">Command</span><span>):</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> :exif_info</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> Shows file metadata using exiftool</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span> f</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> self</span><span>.fm.thisfile</span></span> <span class="giallo-l"><span style="color: #F97583;"> if not</span><span> f:</span></span> <span class="giallo-l"><span style="color: #F97583;"> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> filename</span><span style="color: #F97583;"> =</span><span> f.path</span></span> <span class="giallo-l"><span style="color: #F97583;"> if not</span><span> filename</span><span style="color: #F97583;"> or</span><span> os.path.isdir(filename):</span></span> <span class="giallo-l"><span style="color: #F97583;"> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> mime</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> None</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> shutil.which(</span><span style="color: #9ECBFF;">&quot;file&quot;</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> try</span><span>:</span></span> <span class="giallo-l"><span> mime</span><span style="color: #F97583;"> =</span><span> subprocess.check_output(</span></span> <span class="giallo-l"><span> [</span><span style="color: #9ECBFF;">&quot;file&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;--mime-type&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;-Lb&quot;</span><span>, filename],</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> text</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> stderr</span><span style="color: #F97583;">=</span><span>subprocess.</span><span style="color: #79B8FF;">DEVNULL</span><span>,</span></span> <span class="giallo-l"><span> ).strip()</span></span> <span class="giallo-l"><span style="color: #F97583;"> except</span><span style="color: #79B8FF;"> Exception</span><span>:</span></span> <span class="giallo-l"><span> mime</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> None</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if not</span><span> mime:</span></span> <span class="giallo-l"><span> mime, _</span><span style="color: #F97583;"> =</span><span> mimetypes.guess_type(filename)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> is_media</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> False</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> mime:</span></span> <span class="giallo-l"><span> is_media</span><span style="color: #F97583;"> =</span><span> (</span></span> <span class="giallo-l"><span> mime.startswith((</span><span style="color: #9ECBFF;">&quot;image/&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;video/&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;audio/&quot;</span><span>))</span></span> <span class="giallo-l"><span style="color: #F97583;"> or</span><span> mime</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &quot;application/pdf&quot;</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> is_media:</span></span> <span class="giallo-l"><span> q</span><span style="color: #F97583;"> =</span><span> shlex.quote(filename)</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.execute_command(</span><span style="color: #F97583;">f</span><span style="color: #9ECBFF;">&quot;exiftool </span><span style="color: #79B8FF;">{</span><span>q</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;"> | less&quot;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span><span>:</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.display_file()</span></span></code></pre> <p>This command will:</p> <ol> <li>Detect whether the selected file is an image, video, audio file, or PDF (using <code>file --mime-type</code> when available, with an extension-based fallback)</li> <li>Run <code>exiftool</code> on media/PDF files and pipe the output to <code>less</code> for easy viewing</li> <li>Fall back to ranger’s default preview (<code>display_file()</code>) for all other file types</li> </ol> <hr /> <h2 id="3-creating-a-keyboard-shortcut">3. Creating a Keyboard Shortcut</h2> <p>Now that we have our custom command, let’s create a keyboard shortcut to invoke it easily.</p> <h3 id="3-1-edit-rc-conf">3.1. Edit rc.conf</h3> <p>Open your ranger configuration file:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">vim</span><span style="color: #9ECBFF;"> ~/.config/ranger/rc.conf</span></span></code></pre> <p>If you don’t have this file yet, you can generate it with:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">ranger</span><span style="color: #79B8FF;"> --copy-config=rc</span></span></code></pre><h3 id="3-2-add-the-keyboard-mapping">3.2. Add the Keyboard Mapping</h3> <p>Add the following line to map the <code>exif_info</code> command to a keyboard shortcut. In this example, we’ll use <code>ii</code> (which stands for “inspect info”):</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>map ii exif_info</span></span></code></pre> <p>We use <code>i</code> as a generic <strong>inspect / media prefix</strong> to group all image and media-related actions and avoid conflicts with ranger’s built-in <code>o</code> (order) commands.</p> <p>This shortcut is easy to remember as <code>ii</code> stands for “inspect info” - which is exactly what this command does: it shows you detailed metadata information about your files.</p> <div class="styled-table-container shortcut-table"> <table><thead><tr><th>Shortcut</th><th>Description</th></tr></thead><tbody> <tr><td><code>ii</code></td><td>Show detailed metadata for the selected file using exiftool</td></tr> </tbody></table> </div> <hr /> <h2 id="4-advanced-configuration">4. Advanced Configuration</h2> <h3 id="4-1-using-with-different-file-types">4.1. Using with Different File Types</h3> <p>One of the advantages of this implementation is that it targets media-related formats and avoids running exiftool on unrelated file types. The command will automatically use exiftool for:</p> <ul> <li>Common image formats (JPG, PNG, GIF, TIFF, etc.)</li> <li>RAW camera formats (CR2, NEF, ARW, DNG, etc.)</li> <li>Video files (MP4, MOV, AVI, MKV, etc.)</li> <li>Document formats (PDF, etc.)</li> <li>Audio files (MP3, FLAC, etc.)</li> </ul> <p>For everything else, it will fall back to ranger’s normal file preview.</p> <h3 id="4-2-format-the-output">4.2. Format the Output</h3> <p>You can customize how the metadata is displayed by modifying the command that calls <code>exiftool</code>. For example, to show only specific tags:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span>q</span><span style="color: #F97583;"> =</span><span> shlex.quote(filename)</span></span> <span class="giallo-l"><span style="color: #79B8FF;">self</span><span>.fm.execute_command(</span><span style="color: #F97583;">f</span><span style="color: #9ECBFF;">&quot;exiftool -DateTimeOriginal -Make -Model -LensModel -ExposureTime -FNumber -ISO </span><span style="color: #79B8FF;">{</span><span>q</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;"> | less&quot;</span><span>)</span></span></code></pre><h3 id="4-3-create-a-colorized-output">4.3. Create a Colorized Output</h3> <p>For a more visually appealing output, you can use <code>bat</code> instead of <code>less</code> if you have it installed:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span>q</span><span style="color: #F97583;"> =</span><span> shlex.quote(filename)</span></span> <span class="giallo-l"><span style="color: #79B8FF;">self</span><span>.fm.execute_command(</span><span style="color: #F97583;">f</span><span style="color: #9ECBFF;">&quot;exiftool </span><span style="color: #79B8FF;">{</span><span>q</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;"> | bat --style=plain --color=always | less -R&quot;</span><span>)</span></span></code></pre> <hr /> <h2 id="5-usage">5. Usage</h2> <p>Once everything is set up, you can use your new metadata viewing capability:</p> <ol> <li>Open ranger in your terminal</li> <li>Navigate to an image or media file</li> <li>Press your configured shortcut (e.g., <code>ii</code>)</li> <li>Browse through the metadata information</li> <li>Press <code>q</code> to exit the viewer and return to ranger</li> </ol> <hr /> <h2 id="6-practical-examples">6. Practical Examples</h2> <h3 id="6-1-photography-workflow">6.1. Photography Workflow</h3> <p>For photographers, this integration is particularly useful for quickly checking:</p> <ul> <li>Camera settings (aperture, shutter speed, ISO)</li> <li>Lens information</li> <li>Date and time the photo was taken</li> <li>GPS coordinates (if available)</li> <li>Copyright information</li> </ul> <h3 id="6-2-batch-processing">6.2. Batch Processing</h3> <p>You can combine this with other ranger commands to create a powerful workflow. For example, you could:</p> <ol> <li>Use <code>zi</code> (if you have the <a href="/posts/ranger-fzf-bat-integration/">fzf integration</a>) to quickly find images</li> <li>Use <code>ii</code> to check their metadata</li> <li>Use ranger’s tagging system to organize files based on metadata information</li> </ol> <h3 id="6-3-checking-file-integrity">6.3. Checking File Integrity</h3> <p>For downloaded files or files received from others, you can quickly check:</p> <ul> <li>Creation and modification dates</li> <li>Software used to create the file</li> <li>Embedded comments or descriptions</li> <li>File integrity information</li> </ul> <hr /> <h2 id="7-troubleshooting">7. Troubleshooting</h2> <h3 id="7-1-command-not-found">7.1. Command Not Found</h3> <p>If you get a “Command not found” error when trying to use the shortcut:</p> <ul> <li>Make sure you’ve saved the <code>commands.py</code> file correctly</li> <li>Restart ranger to load the new command</li> <li>Check that <code>exiftool</code> is installed and in your PATH</li> </ul> <h3 id="7-2-no-metadata-displayed">7.2. No Metadata Displayed</h3> <p>If no metadata is displayed for a file:</p> <ul> <li>The file might not contain any metadata</li> <li>The file format might not be supported by exiftool</li> <li>There might be permission issues with the file</li> </ul> <p>Try running <code>exiftool</code> directly on the file to see if it works outside of ranger:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">exiftool</span><span style="color: #9ECBFF;"> path/to/your/file</span></span></code></pre> <hr /> <h2 id="summary">Summary</h2> <p>With this integration, you’ve enhanced ranger’s capabilities for working with digital media files:</p> <p>✅ Quick access to comprehensive file metadata ✅ Support for a wide range of file formats ✅ Customizable keyboard shortcuts ✅ Seamless integration with your terminal workflow</p> <p>This setup is particularly valuable for photographers, designers, and anyone who works with digital media files regularly. It combines the file management power of ranger with the detailed metadata analysis capabilities of exiftool.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;exiftool.org&#x2F;" class="retro-button"> <span class="emoji">📚</span><span class="button-text">EXIFTOOL DOCUMENTATION</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;ranger&#x2F;ranger&#x2F;wiki&#x2F;Custom-Commands" class="retro-button"> <span class="emoji">🔧</span><span class="button-text">RANGER CUSTOM COMMANDS</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;exiftool.org&#x2F;TagNames&#x2F;" class="retro-button"> <span class="emoji">🏷️</span><span class="button-text">EXIFTOOL TAG NAMES</span> </a> </p> <h2 id="related-ranger-guides">Related Ranger Guides</h2> <p>Enhance your ranger experience with these additional tutorials:</p> <ul> <li><a href="/posts/ranger-fzf-bat-integration/">Ranger and fzf Integration</a> - Add powerful fuzzy search capabilities</li> <li><a href="/posts/ranger-compression-workflow/">File Compression Workflow</a> - Create and extract archives easily</li> <li><a href="/posts/ranger-media-preview-configuration/">Advanced Media Preview Configuration</a> - Customize file previews for various formats</li> <li><a href="/posts/ranger-sxiv-integration/">Ranger and sxiv Integration</a> - Create a seamless image viewing workflow</li> </ul> A Modern Image Optimization Workflow in ranger (with Rofi, ImageMagick & WebP) Mon, 12 Jan 2026 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/ranger-image-optimization/ https://criticalbasics.xyz/posts/ranger-image-optimization/ <p>For many power users, the terminal is not a limitation but a productivity multiplier. Yet image optimization is often one of the last steps still handled by heavyweight GUI tools.</p> <p>This guide shows you how to build a <strong>fully terminal-based image optimization workflow</strong> around <strong>ranger</strong>, combining ImageMagick, modern image optimizers, and a Rofi-driven preset menu. The result is a fast, reproducible setup that scales from simple social media exports to high-quality WebP graphics — without ever leaving your file manager.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2026-01-12</td><td><strong>Shortcut Update:</strong> Switched optimization shortcut from <code>oi</code> to <code>io</code> (inspect/media prefix)</td></tr> <tr><td>2026-01-09</td><td><strong>Initial Version:</strong> Created guide for image optimization workflow with Rofi presets</td></tr> </tbody></table> </div> <hr /> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>This guide assumes a Linux system with a keyboard-focused workflow. Ensure you have the following tools installed:</p> <ul> <li><strong>ranger</strong>: The terminal file manager</li> <li><strong>ImageMagick</strong>: The image processing backend</li> <li><strong>pngquant</strong>: Lossy PNG optimization</li> <li><strong>oxipng</strong>: Lossless PNG optimization</li> <li><strong>rofi</strong>: Interactive preset menu</li> <li><strong>libwebp</strong>: WebP support</li> </ul> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ NOTE ON IMAGEMAGICK VERSIONS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>This workflow supports both ImageMagick 6 (<code>convert</code>) and ImageMagick 7 (<code>magick</code>). On modern systems, ImageMagick 7 is preferred for better performance and syntax consistency. The script automatically detects which version is available.</p> </td> </tr> </table> <h3 id="1-1-installation-examples">1.1. Installation Examples</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Arch Linux</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> ranger imagemagick pngquant oxipng rofi libwebp</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Debian / Ubuntu</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt update</span><span> &amp;&amp;</span><span style="color: #B392F0;"> sudo</span><span style="color: #9ECBFF;"> apt install ranger imagemagick pngquant oxipng rofi libwebp</span></span></code></pre> <hr /> <h2 id="2-design-goals-processing-strategy">2. Design Goals &amp; Processing Strategy</h2> <p>Before diving into the code, it is important to understand the design principles behind this setup:</p> <ul> <li><strong>Non-destructive</strong>: Original images are never modified.</li> <li><strong>Preset-driven</strong>: No manual tweaking of parameters during daily use.</li> <li><strong>Pixel-safe where required</strong>: Graphics and screenshots are handled differently from photos.</li> <li><strong>Privacy-aware</strong>: Metadata is stripped by default.</li> <li><strong>Fast access</strong>: One keybinding opens all optimization options.</li> </ul> <h3 id="2-1-photos-vs-graphics">2.1. Photos vs Graphics</h3> <p>A critical distinction is made between two image categories:</p> <ul> <li><strong>Photos (JPEG/PNG)</strong>: Lossy compression is acceptable. Target: small file size for web/social platforms.</li> <li><strong>Graphics / UI / Screenshots</strong>: Pixel integrity matters. Target: lossless or near-lossless processing.</li> </ul> <hr /> <h2 id="3-implementation-in-commands-py">3. Implementation in commands.py</h2> <p>The code below should be added to your ranger configuration. It uses CommandLoader to run heavy processing in the background, keeping the ranger UI responsive.</p> <h3 id="3-1-edit-commands-py">3.1. Edit commands.py</h3> <p>Open your ranger configuration directory:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">vim</span><span style="color: #9ECBFF;"> ~/.config/ranger/commands.py</span></span></code></pre><h3 id="3-2-add-the-optimization-logic">3.2. Add the Optimization Logic</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span style="color: #F97583;">from</span><span> ranger.api.commands</span><span style="color: #F97583;"> import</span><span> Command</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> os</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> shutil</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> shlex</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> subprocess</span></span> <span class="giallo-l"><span style="color: #F97583;">from</span><span> ranger.core.loader</span><span style="color: #F97583;"> import</span><span> CommandLoader</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">class</span><span style="color: #B392F0;"> scale_base</span><span>(</span><span style="color: #B392F0;">Command</span><span>):</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;&quot;&quot; Backend logic for image optimization &quot;&quot;&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> optimize</span><span>(self, target_width, quality, mode</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;lossy&#39;</span><span>, suffix</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;&#39;</span><span>, force_fmt</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">None</span><span>, </span></span> <span class="giallo-l"><span> keep_meta</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">False</span><span>, webp_lossless</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">False</span><span>, do_colorspace</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>):</span></span> <span class="giallo-l"><span> cwd</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> self</span><span>.fm.thisdir</span></span> <span class="giallo-l"><span> marked_files</span><span style="color: #F97583;"> =</span><span> cwd.get_selection()</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if not</span><span> marked_files:</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.notify(</span><span style="color: #9ECBFF;">&quot;No files selected!&quot;</span><span>,</span><span style="color: #FFAB70;"> bad</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> output_dir</span><span style="color: #F97583;"> =</span><span> cwd.path</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> image_exts</span><span style="color: #F97583;"> =</span><span> (</span><span style="color: #9ECBFF;">&#39;.jpg&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.jpeg&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.png&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.webp&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.tif&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.tiff&#39;</span><span>)</span></span> <span class="giallo-l"><span> images</span><span style="color: #F97583;"> =</span><span> [f</span><span style="color: #F97583;"> for</span><span> f</span><span style="color: #F97583;"> in</span><span> marked_files</span><span style="color: #F97583;"> if</span><span> f.path.lower().endswith(image_exts)]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if not</span><span> images:</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.notify(</span><span style="color: #9ECBFF;">&quot;No images found!&quot;</span><span>,</span><span style="color: #FFAB70;"> bad</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> magick_bin</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &#39;magick&#39;</span><span style="color: #F97583;"> if</span><span> shutil.which(</span><span style="color: #9ECBFF;">&#39;magick&#39;</span><span>)</span><span style="color: #F97583;"> else</span><span> (</span><span style="color: #9ECBFF;">&#39;convert&#39;</span><span style="color: #F97583;"> if</span><span> shutil.which(</span><span style="color: #9ECBFF;">&#39;convert&#39;</span><span>)</span><span style="color: #F97583;"> else</span><span style="color: #79B8FF;"> None</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if not</span><span> magick_bin:</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.notify(</span><span style="color: #9ECBFF;">&quot;Error: ImageMagick missing!&quot;</span><span>,</span><span style="color: #FFAB70;"> bad</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> pngquant_bin</span><span style="color: #F97583;"> =</span><span> shutil.which(</span><span style="color: #9ECBFF;">&#39;pngquant&#39;</span><span>)</span></span> <span class="giallo-l"><span> oxipng_bin</span><span style="color: #F97583;"> =</span><span> shutil.which(</span><span style="color: #9ECBFF;">&#39;oxipng&#39;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.notify(</span><span style="color: #F97583;">f</span><span style="color: #9ECBFF;">&quot;Starting optimization (</span><span style="color: #79B8FF;">{</span><span>suffix</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">)...&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> for</span><span> f</span><span style="color: #F97583;"> in</span><span> images:</span></span> <span class="giallo-l"><span> base</span><span style="color: #F97583;"> =</span><span> os.path.basename(f.path)</span></span> <span class="giallo-l"><span> name, raw_ext</span><span style="color: #F97583;"> =</span><span> os.path.splitext(base)</span></span> <span class="giallo-l"><span> src_ext</span><span style="color: #F97583;"> =</span><span> raw_ext.lower()</span></span> <span class="giallo-l"><span> out_ext</span><span style="color: #F97583;"> =</span><span> force_fmt</span><span style="color: #F97583;"> if</span><span> force_fmt</span><span style="color: #F97583;"> else</span><span> src_ext</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> final_suffix</span><span style="color: #F97583;"> =</span><span> suffix</span><span style="color: #F97583;"> if</span><span> suffix</span><span style="color: #F97583;"> else f</span><span style="color: #9ECBFF;">&quot;_w</span><span style="color: #79B8FF;">{</span><span>target_width</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">_</span><span style="color: #79B8FF;">{</span><span>mode</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span> out_name</span><span style="color: #F97583;"> = f</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;">{</span><span>name</span><span style="color: #79B8FF;">}{</span><span>final_suffix</span><span style="color: #79B8FF;">}{</span><span>out_ext</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span> dest</span><span style="color: #F97583;"> =</span><span> os.path.join(output_dir, out_name)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Avoid overwriting</span></span> <span class="giallo-l"><span> counter</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> 1</span></span> <span class="giallo-l"><span style="color: #F97583;"> while</span><span> os.path.exists(dest):</span></span> <span class="giallo-l"><span> out_name</span><span style="color: #F97583;"> = f</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;">{</span><span>name</span><span style="color: #79B8FF;">}{</span><span>final_suffix</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">_</span><span style="color: #79B8FF;">{</span><span>counter</span><span style="color: #79B8FF;">}{</span><span>out_ext</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span> dest</span><span style="color: #F97583;"> =</span><span> os.path.join(output_dir, out_name)</span></span> <span class="giallo-l"><span> counter</span><span style="color: #F97583;"> +=</span><span style="color: #79B8FF;"> 1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> cmd_im</span><span style="color: #F97583;"> =</span><span> [magick_bin, f.path,</span><span style="color: #9ECBFF;"> &#39;-auto-orient&#39;</span><span>]</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> target_width</span><span style="color: #F97583;"> &gt;</span><span style="color: #79B8FF;"> 0</span><span>:</span></span> <span class="giallo-l"><span> cmd_im.extend([</span><span style="color: #9ECBFF;">&#39;-resize&#39;</span><span>,</span><span style="color: #F97583;"> f</span><span style="color: #9ECBFF;">&#39;</span><span style="color: #79B8FF;">{</span><span>target_width</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">x&gt;&#39;</span><span>])</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> do_colorspace:</span></span> <span class="giallo-l"><span> cmd_im.extend([</span><span style="color: #9ECBFF;">&#39;-colorspace&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;sRGB&#39;</span><span>])</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> do_strip_in_im</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> True</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> keep_meta:</span></span> <span class="giallo-l"><span> do_strip_in_im</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> False</span></span> <span class="giallo-l"><span style="color: #F97583;"> elif</span><span> out_ext</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &#39;.png&#39;</span><span style="color: #F97583;"> and</span><span> mode</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &#39;hq&#39;</span><span style="color: #F97583;"> and</span><span> oxipng_bin:</span></span> <span class="giallo-l"><span> do_strip_in_im</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> False</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> do_strip_in_im:</span></span> <span class="giallo-l"><span> cmd_im.append(</span><span style="color: #9ECBFF;">&#39;-strip&#39;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> out_ext</span><span style="color: #F97583;"> in</span><span> [</span><span style="color: #9ECBFF;">&#39;.jpg&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.jpeg&#39;</span><span>]:</span></span> <span class="giallo-l"><span> cmd_im.extend([</span><span style="color: #9ECBFF;">&#39;-quality&#39;</span><span>,</span><span style="color: #79B8FF;"> str</span><span>(quality)])</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> mode</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &#39;lossy&#39;</span><span>:</span></span> <span class="giallo-l"><span> cmd_im.extend([</span><span style="color: #9ECBFF;">&#39;-sampling-factor&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;4:2:0&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;-interlace&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;Plane&#39;</span><span>])</span></span> <span class="giallo-l"><span> cmd_im.append(dest)</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.loader.add(CommandLoader(</span><span style="color: #FFAB70;">args</span><span style="color: #F97583;">=</span><span>cmd_im,</span><span style="color: #FFAB70;"> descr</span><span style="color: #F97583;">=f</span><span style="color: #9ECBFF;">&quot;JPG </span><span style="color: #79B8FF;">{</span><span>mode</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">: </span><span style="color: #79B8FF;">{</span><span>base</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">&quot;</span><span>,</span><span style="color: #FFAB70;"> read</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>))</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> elif</span><span> out_ext</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &#39;.webp&#39;</span><span>:</span></span> <span class="giallo-l"><span> cmd_im.extend([</span><span style="color: #9ECBFF;">&#39;-define&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;webp:method=6&#39;</span><span>])</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> webp_lossless:</span></span> <span class="giallo-l"><span> cmd_im.extend([</span><span style="color: #9ECBFF;">&#39;-define&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;webp:lossless=true&#39;</span><span>])</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span><span>:</span></span> <span class="giallo-l"><span> cmd_im.extend([</span><span style="color: #9ECBFF;">&#39;-quality&#39;</span><span>,</span><span style="color: #79B8FF;"> str</span><span>(quality)])</span></span> <span class="giallo-l"><span> cmd_im.extend([</span><span style="color: #9ECBFF;">&#39;-define&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;webp:alpha-quality=90&#39;</span><span>])</span></span> <span class="giallo-l"><span> cmd_im.append(dest)</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.loader.add(CommandLoader(</span><span style="color: #FFAB70;">args</span><span style="color: #F97583;">=</span><span>cmd_im,</span><span style="color: #FFAB70;"> descr</span><span style="color: #F97583;">=f</span><span style="color: #9ECBFF;">&quot;WebP: </span><span style="color: #79B8FF;">{</span><span>base</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">&quot;</span><span>,</span><span style="color: #FFAB70;"> read</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>))</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> elif</span><span> out_ext</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &#39;.png&#39;</span><span>:</span></span> <span class="giallo-l"><span> cmd_im.append(dest)</span></span> <span class="giallo-l"><span> safe_im_cmd</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &quot; &quot;</span><span>.join(shlex.quote(arg)</span><span style="color: #F97583;"> for</span><span> arg</span><span style="color: #F97583;"> in</span><span> cmd_im)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> full_cmd</span><span style="color: #F97583;"> =</span><span> safe_im_cmd</span></span> <span class="giallo-l"><span> descr</span><span style="color: #F97583;"> = f</span><span style="color: #9ECBFF;">&quot;PNG (IM): </span><span style="color: #79B8FF;">{</span><span>base</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> mode</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &#39;lossy&#39;</span><span style="color: #F97583;"> and</span><span> pngquant_bin:</span></span> <span class="giallo-l"><span> cmd_pq</span><span style="color: #F97583;"> =</span><span> [pngquant_bin,</span><span style="color: #9ECBFF;"> &#39;--force&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;--skip-if-larger&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;--speed&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;3&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;--quality=65-85&#39;</span><span>, dest]</span></span> <span class="giallo-l"><span> safe_pq_cmd</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &quot; &quot;</span><span>.join(shlex.quote(arg)</span><span style="color: #F97583;"> for</span><span> arg</span><span style="color: #F97583;"> in</span><span> cmd_pq)</span></span> <span class="giallo-l"><span> full_cmd</span><span style="color: #F97583;"> = f</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;">{</span><span>safe_im_cmd</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;"> &amp;&amp; </span><span style="color: #79B8FF;">{</span><span>safe_pq_cmd</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span> descr</span><span style="color: #F97583;"> = f</span><span style="color: #9ECBFF;">&quot;PNG Lossy: </span><span style="color: #79B8FF;">{</span><span>base</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> elif</span><span> mode</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &#39;hq&#39;</span><span style="color: #F97583;"> and</span><span> oxipng_bin:</span></span> <span class="giallo-l"><span> cmd_oxi</span><span style="color: #F97583;"> =</span><span> [oxipng_bin,</span><span style="color: #9ECBFF;"> &#39;-o&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;2&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;--strip&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;safe&#39;</span><span>, dest]</span></span> <span class="giallo-l"><span> safe_oxi_cmd</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &quot; &quot;</span><span>.join(shlex.quote(arg)</span><span style="color: #F97583;"> for</span><span> arg</span><span style="color: #F97583;"> in</span><span> cmd_oxi)</span></span> <span class="giallo-l"><span> full_cmd</span><span style="color: #F97583;"> = f</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;">{</span><span>safe_im_cmd</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;"> &amp;&amp; </span><span style="color: #79B8FF;">{</span><span>safe_oxi_cmd</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span> descr</span><span style="color: #F97583;"> = f</span><span style="color: #9ECBFF;">&quot;PNG HQ: </span><span style="color: #79B8FF;">{</span><span>base</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.loader.add(CommandLoader(</span><span style="color: #FFAB70;">args</span><span style="color: #F97583;">=</span><span>[</span><span style="color: #9ECBFF;">&#39;sh&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;-c&#39;</span><span>, full_cmd],</span><span style="color: #FFAB70;"> descr</span><span style="color: #F97583;">=</span><span>descr,</span><span style="color: #FFAB70;"> read</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>))</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> else</span><span>:</span></span> <span class="giallo-l"><span> cmd_im.append(dest)</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.loader.add(CommandLoader(</span><span style="color: #FFAB70;">args</span><span style="color: #F97583;">=</span><span>cmd_im,</span><span style="color: #FFAB70;"> descr</span><span style="color: #F97583;">=f</span><span style="color: #9ECBFF;">&quot;Convert: </span><span style="color: #79B8FF;">{</span><span>base</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">&quot;</span><span>,</span><span style="color: #FFAB70;"> read</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>))</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span style="color: #79B8FF;"> True</span><span>:</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # --- PRESETS ---</span></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_web</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">1920</span><span>,</span><span style="color: #79B8FF;"> 82</span><span>,</span><span style="color: #9ECBFF;"> &#39;lossy&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_web&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_web_xl</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">2560</span><span>,</span><span style="color: #79B8FF;"> 82</span><span>,</span><span style="color: #9ECBFF;"> &#39;lossy&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_webXL&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_web_hq</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">1920</span><span>,</span><span style="color: #79B8FF;"> 92</span><span>,</span><span style="color: #9ECBFF;"> &#39;hq&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_webHQ&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_blog</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">1400</span><span>,</span><span style="color: #79B8FF;"> 82</span><span>,</span><span style="color: #9ECBFF;"> &#39;lossy&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_blog&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_thumb</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">600</span><span>,</span><span style="color: #79B8FF;"> 75</span><span>,</span><span style="color: #9ECBFF;"> &#39;lossy&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_thumb&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_ig_feed</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">1080</span><span>,</span><span style="color: #79B8FF;"> 85</span><span>,</span><span style="color: #9ECBFF;"> &#39;lossy&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_ig&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_ig_portrait</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">1350</span><span>,</span><span style="color: #79B8FF;"> 85</span><span>,</span><span style="color: #9ECBFF;"> &#39;lossy&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_ig4x5&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_story</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">1080</span><span>,</span><span style="color: #79B8FF;"> 85</span><span>,</span><span style="color: #9ECBFF;"> &#39;lossy&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_story&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_linkedin</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">1200</span><span>,</span><span style="color: #79B8FF;"> 85</span><span>,</span><span style="color: #9ECBFF;"> &#39;lossy&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_li&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_meta_ads</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">1200</span><span>,</span><span style="color: #79B8FF;"> 85</span><span>,</span><span style="color: #9ECBFF;"> &#39;lossy&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_ads&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_jpeg_email</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">1280</span><span>,</span><span style="color: #79B8FF;"> 80</span><span>,</span><span style="color: #9ECBFF;"> &#39;lossy&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_email&quot;</span><span>,</span><span style="color: #FFAB70;"> force_fmt</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;.jpg&#39;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_webp_hq</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">1920</span><span>,</span><span style="color: #79B8FF;"> 85</span><span>,</span><span style="color: #9ECBFF;"> &#39;lossy&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_web&quot;</span><span>,</span><span style="color: #FFAB70;"> force_fmt</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;.webp&#39;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_webp_lossless</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">0</span><span>,</span><span style="color: #79B8FF;"> 0</span><span>,</span><span style="color: #9ECBFF;"> &#39;hq&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_graphic&quot;</span><span>,</span><span style="color: #FFAB70;"> force_fmt</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;.webp&#39;</span><span>,</span><span style="color: #FFAB70;"> webp_lossless</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>,</span><span style="color: #FFAB70;"> do_colorspace</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">False</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_webp_no_resize</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">0</span><span>,</span><span style="color: #79B8FF;"> 82</span><span>,</span><span style="color: #9ECBFF;"> &#39;lossy&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_webp&quot;</span><span>,</span><span style="color: #FFAB70;"> force_fmt</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;.webp&#39;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_png_graphic</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">0</span><span>,</span><span style="color: #79B8FF;"> 0</span><span>,</span><span style="color: #9ECBFF;"> &#39;hq&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_graphic&quot;</span><span>,</span><span style="color: #FFAB70;"> force_fmt</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;.png&#39;</span><span>,</span><span style="color: #FFAB70;"> do_colorspace</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">False</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> scale_strip_only</span><span>(</span><span style="color: #B392F0;">scale_base</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.optimize(</span><span style="color: #79B8FF;">0</span><span>,</span><span style="color: #79B8FF;"> 0</span><span>,</span><span style="color: #9ECBFF;"> &#39;hq&#39;</span><span>,</span><span style="color: #9ECBFF;"> &quot;_stripped&quot;</span><span>,</span><span style="color: #FFAB70;"> keep_meta</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">False</span><span>,</span><span style="color: #FFAB70;"> do_colorspace</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">False</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # --- ROFI MENU ---</span></span> <span class="giallo-l"><span style="color: #F97583;"> class</span><span style="color: #B392F0;"> image_optimization_menu</span><span>(</span><span style="color: #B392F0;">Command</span><span>):</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;&quot;&quot; Rofi Menu for Image Optimization &quot;&quot;&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span> menu_structure</span><span style="color: #F97583;"> =</span><span> [</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;--- WEB ---&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;true&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;Web Standard (1920px)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_web&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;Web XL (2560px)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_web_xl&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;Web HQ (1920px)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_web_hq&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;Blog (1400px)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_blog&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;Thumbnail (600px)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_thumb&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;--- SOCIAL ---&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;true&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;IG Feed (1080px)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_ig_feed&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;IG Portrait (1350px)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_ig_portrait&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;IG Story/Reel (1080px)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_story&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;LinkedIn (1200px)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_linkedin&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;Meta Ads (1200px)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_meta_ads&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;JPEG Email (1280px)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_jpeg_email&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;--- MODERN/TOOLS ---&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;true&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;WebP HQ (1920px)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_webp_hq&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;WebP Lossless (Grafik)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_webp_lossless&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;WebP Convert (Original Size)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_webp_no_resize&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;PNG Graphic (Original, no sRGB)&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_png_graphic&quot;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #9ECBFF;">&quot;Strip Metadata Only&quot;</span><span>,</span><span style="color: #9ECBFF;"> &quot;scale_strip_only&quot;</span><span>)</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #F97583;"> if not</span><span> shutil.which(</span><span style="color: #9ECBFF;">&#39;rofi&#39;</span><span>):</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.notify(</span><span style="color: #9ECBFF;">&quot;Rofi missing!&quot;</span><span>,</span><span style="color: #FFAB70;"> bad</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> options_str</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &quot;</span><span style="color: #79B8FF;">\n</span><span style="color: #9ECBFF;">&quot;</span><span>.join([item[</span><span style="color: #79B8FF;">0</span><span>]</span><span style="color: #F97583;"> for</span><span> item</span><span style="color: #F97583;"> in</span><span> menu_structure])</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> try</span><span>:</span></span> <span class="giallo-l"><span> p</span><span style="color: #F97583;"> =</span><span> subprocess.Popen(</span></span> <span class="giallo-l"><span> [</span><span style="color: #9ECBFF;">&#39;rofi&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;-dmenu&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;-p&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;Optimize&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;-i&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;-lines&#39;</span><span>,</span><span style="color: #79B8FF;"> str</span><span>(</span><span style="color: #79B8FF;">len</span><span>(menu_structure))],</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> stdin</span><span style="color: #F97583;">=</span><span>subprocess.</span><span style="color: #79B8FF;">PIPE</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> stdout</span><span style="color: #F97583;">=</span><span>subprocess.</span><span style="color: #79B8FF;">PIPE</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> stderr</span><span style="color: #F97583;">=</span><span>subprocess.</span><span style="color: #79B8FF;">PIPE</span><span>,</span></span> <span class="giallo-l"><span style="color: #FFAB70;"> text</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> stdout, _</span><span style="color: #F97583;"> =</span><span> p.communicate(</span><span style="color: #FFAB70;">input</span><span style="color: #F97583;">=</span><span>options_str)</span></span> <span class="giallo-l"><span> selection</span><span style="color: #F97583;"> =</span><span> stdout.strip()</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if not</span><span> selection:</span></span> <span class="giallo-l"><span style="color: #F97583;"> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> for</span><span> label, cmd</span><span style="color: #F97583;"> in</span><span> menu_structure:</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> label</span><span style="color: #F97583;"> ==</span><span> selection:</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> cmd</span><span style="color: #F97583;"> !=</span><span style="color: #9ECBFF;"> &quot;true&quot;</span><span>:</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.execute_console(cmd)</span></span> <span class="giallo-l"><span style="color: #F97583;"> break</span></span> <span class="giallo-l"><span style="color: #F97583;"> except</span><span style="color: #79B8FF;"> Exception</span><span style="color: #F97583;"> as</span><span> e:</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.notify(</span><span style="color: #F97583;">f</span><span style="color: #9ECBFF;">&quot;Error: </span><span style="color: #79B8FF;">{</span><span>e</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">&quot;</span><span>,</span><span style="color: #FFAB70;"> bad</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> return</span></span> <span class="giallo-l"></span></code></pre> <hr /> <h2 id="4-creating-keyboard-shortcuts">4. Creating Keyboard Shortcuts</h2> <p>Now, let’s map the interactive menu to a shortcut.</p> <h3 id="4-1-edit-rc-conf">4.1. Edit rc.conf</h3> <p>Open your rc.conf:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">vim</span><span style="color: #9ECBFF;"> ~/.config/ranger/rc.conf</span></span></code></pre><h3 id="4-2-add-the-mapping">4.2. Add the Mapping</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span># Image Optimization Menu</span></span> <span class="giallo-l"><span>map io image_optimization_menu</span></span></code></pre> <p>We use <code>i</code> as a generic <strong>inspect / media prefix</strong> to group all image and media-related actions and avoid conflicts with ranger’s built-in <code>o</code> (order) commands.</p> <div class="styled-table-container shortcut-table"> <table><thead><tr><th>Shortcut</th><th>Description</th></tr></thead><tbody> <tr><td>io</td><td>Open Rofi menu to select image optimization preset</td></tr> </tbody></table> </div> <hr /> <h2 id="5-preset-overview">5. Preset Overview</h2> <p>The workflow provides curated presets for real-world scenarios:</p> <ul> <li><strong>Web Standard (1920px)</strong>: Balanced compression for websites.</li> <li><strong>Web XL (2560px)</strong>: Extra-wide output for large screens.</li> <li><strong>Web HQ (1920px)</strong>: Minimal compression for high-quality portfolios.</li> <li><strong>Blog (1400px)</strong>: Cleaner sizing for article layouts.</li> <li><strong>Thumbnail (600px)</strong>: Small previews.</li> <li><strong>Instagram Feed (1080px)</strong>: Optimized for Instagram’s upload limits.</li> <li><strong>IG Portrait (1350px)</strong>: 4:5 portrait-friendly sizing.</li> <li><strong>IG Story/Reel (1080px)</strong>: Vertical-first exports.</li> <li><strong>LinkedIn (1200px)</strong>: Social sharing format.</li> <li><strong>Meta Ads (1200px)</strong>: Ad-friendly sizing.</li> <li><strong>JPEG Email (1280px)</strong>: Compatibility-first export.</li> <li><strong>WebP HQ</strong>: Modern lossy format for superior size-to-quality ratio.</li> <li><strong>WebP Lossless (Graphic)</strong>: Lossless WebP for pixel-perfect graphics.</li> <li><strong>WebP Convert (Original Size)</strong>: Convert without resizing.</li> <li><strong>PNG Graphic (Original, no sRGB)</strong>: Preserve pixel values and skip sRGB conversion.</li> <li><strong>Strip Metadata</strong>: Removes EXIF/GPS data without changing pixel values.</li> </ul> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 WHY ROFI? </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Rofi provides fuzzy search and instant feedback. It fits perfectly into window manager workflows and avoids the need to memorize dozens of separate keybindings.</p> </td> </tr> </table> <hr /> <h2 id="6-practical-use-cases">6. Practical Use Cases</h2> <h3 id="6-1-content-publishing">6.1. Content Publishing</h3> <ol> <li>Navigate to your image folder in ranger.</li> <li>Mark images with Space.</li> <li>Press <code>io</code> and select <strong>Web Standard</strong>.</li> <li>Optimized files appear in the same folder as the originals.</li> </ol> <h3 id="6-2-privacy-stripping">6.2. Privacy Stripping</h3> <p>Before sharing photos online, mark them and run <strong>Strip Metadata Only</strong> to ensure no GPS or camera information is leaked.</p> <hr /> <h2 id="7-troubleshooting">7. Troubleshooting</h2> <h3 id="7-1-images-appear-rotated">7.1. Images appear rotated</h3> <p>The script uses <code>-auto-orient</code> before processing. This ensures that the orientation tag is respected even when metadata is stripped.</p> <h3 id="7-2-colors-look-different">7.2. Colors look different</h3> <p>Web presets normalize images to sRGB. If you need to preserve a specific color profile, use the <strong>Strip Only</strong> or <strong>PNG Graphic</strong> presets which skip colorspace conversion.</p> <hr /> <h2 id="8-summary">8. Summary</h2> <p>With this integration, you’ve transformed ranger into a high-performance image processing station:</p> <ul> <li>✅ Batch processing of multiple images</li> <li>✅ Searchable Rofi menu for all presets</li> <li>✅ Background execution via CommandLoader</li> <li>✅ Support for modern formats like WebP</li> <li>✅ Optimized for web, social media, and privacy</li> </ul> <p>This setup combines the simplicity of ranger with the industrial-grade power of ImageMagick, ensuring your images are always perfectly optimized for any platform.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;imagemagick.org&#x2F;script&#x2F;command-line-options.php" class="retro-button"> <span class="emoji">📚</span><span class="button-text">IMAGEMAGICK CLI DOCS</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;shinchiro&#x2F;mpv-scripts" class="retro-button"> <span class="emoji">🔧</span><span class="button-text">MORE RANGER TOOLS</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;pngquant.org&#x2F;" class="retro-button"> <span class="emoji">🖼️</span><span class="button-text">PNGQUANT HOME</span> </a> </p> <hr /> <h2 id="9-related-ranger-guides">9. Related Ranger Guides</h2> <ul> <li><strong><a href="https://criticalbasics.xyz/posts/ranger-fzf-bat-integration/">Ranger and fzf Integration</a></strong>: Search files at lightning speed</li> <li><strong><a href="https://criticalbasics.xyz/posts/ranger-exiftool-integration/">Image Metadata Viewing with exiftool</a></strong>: View EXIF data before optimizing</li> <li><strong><a href="https://criticalbasics.xyz/posts/ranger-compression-workflow/">File Compression Workflow</a></strong>: Archive your optimized assets</li> <li><strong><a href="https://criticalbasics.xyz/posts/ranger-media-preview-configuration/">Advanced Media Preview Configuration</a></strong>: Better previews for WebP files</li> </ul> Turning on Samsung M51 without Power Button: The Heimdall Method Tue, 09 Dec 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/samsung-m51-heimdall-start/ https://criticalbasics.xyz/posts/samsung-m51-heimdall-start/ <p>When the power button of a Samsung Galaxy smartphone breaks, the device often seems like a lost cause once the battery runs empty or it turns off. A frustrating detail: Without a working power button, the device often shows no charging animation when plugged in, but rather stays on a black screen—it appears “dead” even though the battery is charging.</p> <p>This guide demonstrates a reliable workaround: We force the device into <strong>Download Mode</strong> using a button combination and use the open-source tool <strong>Heimdall</strong> on Linux to force a reboot.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ COMPATIBILITY </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>This guide was specifically verified with a <strong>Samsung Galaxy M51</strong>. However, the method works with almost all Samsung devices that have physical volume keys due to the underlying technology:</p> <ul> <li><strong>Galaxy S-Series</strong> (e.g., S7 to S21)</li> <li><strong>Galaxy A-Series</strong> (e.g., A51, A52, A21s)</li> <li><strong>Galaxy M-Series</strong></li> <li><strong>Galaxy Tab Tablets</strong></li> </ul> </td> </tr> </table> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-12-09</td><td><strong>Update &amp; Refinement:</strong> Updated to Heimdall 2.2.2, added troubleshooting section, and clarified distinction between Warning Screen and Download Mode.</td></tr> <tr><td>2025-12-08</td><td><strong>Initial Version:</strong> Guide created based on successful tests with a Samsung Galaxy M51.</td></tr> </tbody></table> </div> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>Before we begin, ensure you have access to a Linux PC. This guide specifically references Arch Linux, but the commands are easily transferable to Debian/Ubuntu.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ IMPORTANT: ROOT &amp; BATTERY </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <ol> <li><strong>No Root on Phone needed:</strong> Your smartphone does <em>not</em> need to be rooted. We only need <code>sudo</code> rights on the <strong>PC</strong> to access the USB interface.</li> <li><strong>Charge Battery:</strong> Ensure the device has been on the charger for at least 15 minutes, even if the display remained black.</li> <li><strong>Data Cable:</strong> Use a fully functional USB data cable, not a charge-only cable.</li> </ol> </td> </tr> </table> <h2 id="2-forcing-download-mode">2. Forcing Download Mode</h2> <p>Since the power button is non-functional, we utilize a service button combination. This step is performed while the device is powered off.</p> <ol> <li><strong>Disconnect Cable:</strong> Ensure the USB cable is <em>not</em> connected to the smartphone (but is already plugged into the PC).</li> <li><strong>Hold Buttons:</strong> Press and hold both <strong>Volume Up (Vol+)</strong> and <strong>Volume Down (Vol-)</strong> simultaneously.</li> <li><strong>Connect:</strong> While holding both buttons, plug the USB cable into the smartphone.</li> </ol> <p>The display should now light up and show a turquoise <strong>Warning Screen</strong> (<code>Warning! A custom OS can cause...</code>).</p> <p><strong>Note:</strong> This is <em>not</em> Download Mode yet.</p> <ol start="4"> <li><strong>Confirm:</strong> Now press the <strong>Vol Up</strong> key once. Only now does the device switch to the actual <strong>Download Mode</strong>. The screen will display a large “Downloading…”.</li> </ol> <h2 id="3-heimdall-setup">3. Heimdall Setup</h2> <p>We use the tool <code>heimdall</code>, an open-source alternative to Samsung’s Odin.</p> <h3 id="3-1-installation">3.1. Installation</h3> <p>On Arch Linux, install the package as follows (tested with version 2.2.2):</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> heimdall</span></span></code></pre> <p>For Debian/Ubuntu users, the command is usually <code>sudo apt install heimdall-flash</code>.</p> <h3 id="3-2-verify-connection">3.2. Verify Connection</h3> <p>Check if your PC recognizes the smartphone in Download Mode.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">heimdall</span><span style="color: #9ECBFF;"> detect</span></span></code></pre> <p>The expected output should be:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>Device detected</span></span></code></pre> <p><em>(If an error occurs here, see Section 5 “Troubleshooting”.)</em></p> <h2 id="4-triggering-the-reboot">4. Triggering the Reboot</h2> <p>Now for the crucial step. We send a command to the smartphone that usually cleanly terminates a flashing session.</p> <p>Run the following command in your terminal:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> heimdall close-pc-screen</span></span></code></pre><h3 id="the-result">The Result</h3> <p>You should see a success message in the terminal:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>Attempting to close connect to pc screen...</span></span> <span class="giallo-l"><span>Rebooting device...</span></span> <span class="giallo-l"><span>Attempt complete</span></span></code></pre> <p>The smartphone screen will immediately turn black and restart. Since we are no longer in the special maintenance mode, the Android system will boot up normally—without needing the power button.</p> <h2 id="5-troubleshooting">5. Troubleshooting</h2> <p>If it doesn’t work right away, here are the common pitfalls:</p> <p><strong>Problem: <code>heimdall detect</code> shows “Failed to detect compatible device”</strong></p> <ul> <li><strong>Solution A (Cable):</strong> The most common issue is low-quality USB cables. Try a different one, ideally the original Samsung cable.</li> <li><strong>Solution B (Permissions):</strong> Missing <code>udev</code> rules might be the cause. Try running the command with admin privileges: <code>sudo heimdall detect</code>.</li> </ul> <p><strong>Problem: <code>libusb error</code> or <code>Claiming interface failed</code></strong></p> <ul> <li><strong>Solution:</strong> Another process is blocking the USB port. Unplug the cable, wait 5 seconds, and plug it back in. Ensure no other software (like ModemManager) is trying to access the device.</li> </ul> <p><strong>Problem: Device reboots back into Download Mode</strong></p> <ul> <li><strong>Solution:</strong> In rare cases, one of the volume buttons might be stuck physically. Ensure the keys are not jammed.</li> </ul> <h2 id="6-technical-background">6. Technical Background</h2> <p>Why does this work?</p> <ul> <li><strong>Hardware Design:</strong> Samsung devices have a hardware trigger (<code>Vol+</code> &amp; <code>Vol-</code> + USB Insert) that activates <em>before</em> the main bootloader. This allows technicians to access the device even with corrupted software or broken physical buttons.</li> <li><strong>The Protocol:</strong> The command <code>close-pc-screen</code> sends a specific <strong>End-of-Session command</strong> to the bootloader. The bootloader interprets this as “Maintenance successfully finished” and initiates a regular system reboot.</li> </ul> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;git.sr.ht&#x2F;~grimler&#x2F;Heimdall" class="retro-button"> <span class="emoji">📦</span><span class="button-text">HEIMDALL SOURCE CODE</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;wiki.archlinux.org&#x2F;title&#x2F;Android_flashing#Heimdall" class="retro-button"> <span class="emoji">📚</span><span class="button-text">ARCH WIKI: HEIMDALL</span> </a> </p> Deploying Mox Mail Server with Traefik and Docker Compose: A Lightweight Mailcow Alternative Wed, 12 Nov 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/mox-e-mail-server/ https://criticalbasics.xyz/posts/mox-e-mail-server/ <p>This guide provides a straightforward method for deploying <strong><a rel="noopener external" target="_blank" href="https://www.xmox.nl/">Mox</a></strong>, a modern and resource-efficient mail server, and integrating it into an existing Traefik stack. Mox is an excellent all-in-one alternative to more complex solutions like <strong><a href="../mailcow-mailserver/">Mailcow</a></strong>, as it bundles services like SMTP, IMAP, webmail, and spam filtering into a single, easy-to-manage application. By leveraging our <strong><a href="../traefik-v3-crowdsec-tutorial/">Traefik and CrowdSec setup</a></strong>, you can secure its web administration interface right from the start.</p> <p>Mox aims to simplify self-hosted email, making it accessible for users who want to maintain control over their digital communications without the complexity of configuring multiple services.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-11-12</td><td><strong>Initial Version:</strong> Guide created for integrating Mox with the Traefik v3 stack.</td></tr> </tbody></table> </div> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>This tutorial assumes you have a fully operational Traefik v3 and CrowdSec environment. This setup is essential for routing, TLS, and security.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ HARD REQUIREMENT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The following steps will not work correctly without the Traefik stack running as described in the prerequisite guide.</p> <ul> <li><strong><a href="../traefik-v3-crowdsec-tutorial/">Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack</a></strong>: This is the foundation for our public-facing reverse proxy and security.</li> </ul> </td> </tr> </table> <p>You will also need:</p> <ul> <li>A domain name for your mail server.</li> <li>The ability to add and modify DNS records (specifically <code>A</code> and <code>MX</code> records) for your domain.</li> <li><code>sudo</code> or root access to your server.</li> </ul> <h2 id="2-directory-structure">2. Directory Structure</h2> <p>First, we’ll create a dedicated directory for the Mox configuration and data. This keeps your project isolated and organized.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> /opt/containers/mox</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/mox</span></span></code></pre><h2 id="3-configuration">3. Configuration</h2> <p>We will now create the necessary environment, Docker Compose, and Dockerfile.</p> <h3 id="3-1-environment-file-env">3.1. Environment File (<code>.env</code>)</h3> <p>This file will store variables specific to your setup.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee .env</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">TZ=Europe/Berlin</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">DOMAIN_NAME=your-domain.com</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">MOX_ADMIN_EMAIL=admin@your-domain.com</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre> <p>Be sure to replace <code>your-domain.com</code> with your actual domain and adjust the timezone if necessary.</p> <h3 id="3-2-dockerfile-build-from-source">3.2. Dockerfile (Build from Source)</h3> <p>To ensure we are running the latest, most secure version directly from the developer, we will build the Mox image ourselves instead of using a community-maintained image.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ WHY BUILD FROM SOURCE? </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Building the image directly from the official GitHub repository guarantees you have the latest stable release with no third-party modifications.</p> </td> </tr> </table> <p>Create the <code>Dockerfile</code> in your <code>/opt/containers/mox</code> directory:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee Dockerfile</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Stage 1: Build the Go binary</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">FROM golang:1.22-alpine AS builder</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">RUN apk add --no-cache git</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">RUN git clone https://github.com/mjl-/mox.git /src/mox</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">WORKDIR /src/mox</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Build a smaller, optimized binary without debug symbols</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">RUN go build -trimpath -ldflags=&quot;-s -w&quot; ./cmd/mox</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Stage 2: Create the final, minimal image</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">FROM alpine:latest</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">RUN apk add --no-cache ca-certificates</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">COPY --from=builder /src/mox/mox /usr/local/bin/mox</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Create a dedicated, non-root user for the service</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">RUN adduser -D -h /data mox</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">USER mox</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">WORKDIR /data</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">VOLUME /data</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EXPOSE 25 465 587 993 80</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">ENTRYPOINT [&quot;mox&quot;]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><h3 id="3-3-docker-compose-docker-compose-yml">3.3. Docker Compose (<code>docker-compose.yml</code>)</h3> <p>This file defines the Mox service and tells Traefik how to route traffic to it.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee docker-compose.yml</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">version: &quot;3.9&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">services:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> mox:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> build: .</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: mox</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> environment:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - TZ=${TZ}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./data:/data</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - proxy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> healthcheck:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> test: [&quot;CMD&quot;, &quot;mox&quot;, &quot;version&quot;]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> interval: 60s</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> timeout: 10s</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> retries: 3</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> labels:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.mox.rule=Host(`mail.${DOMAIN_NAME}`)&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.mox.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.mox.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.services.mox.loadbalancer.server.port=80&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.services.mox.loadbalancer.server.scheme=http&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.mox.middlewares=security-headers@file,crowdsec-bouncer@docker&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> external: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre> <p><strong>Configuration Explained:</strong></p> <ul> <li><code>build: .</code>: Tells Docker Compose to build an image from the local <code>Dockerfile</code>.</li> <li><strong>Security:</strong> The container runs as a dedicated, non-privileged user (<code>mox</code>) for enhanced security.</li> <li><code>healthcheck:</code> Periodically checks if the Mox service is running correctly, providing a clear status in <code>docker ps</code>.</li> <li><code>loadbalancer.server.port=80</code> &amp; <code>scheme=http</code>: Traefik handles public HTTPS and communicates with Mox internally via standard HTTP, centralizing TLS management.</li> <li><code>middlewares=...crowdsec-bouncer@docker</code>: Secures the web UI with our CrowdSec bouncer.</li> </ul> <h2 id="4-dns-configuration">4. DNS Configuration</h2> <p>For your mail server to be reachable, you need to configure your domain’s DNS records.</p> <ol> <li> <p><strong>A Record:</strong> Point the subdomain for Mox to your server’s IP address.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>mail.your-domain.com. A &lt;your_server_ip&gt;</span></span></code></pre></li> <li> <p><strong>MX Record:</strong> After setup, set an MX record to direct email for your domain to the Mox server.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>your-domain.com. MX 10 mail.your-domain.com.</span></span></code></pre></li> </ol> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 SPF, DKIM, AND DMARC RECORDS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>When you complete the Mox setup wizard, it will display the necessary DNS <code>TXT</code> records for SPF, DKIM, and DMARC. Adding these records to your domain is crucial for ensuring proper mail delivery and building a good sender reputation.</p> </td> </tr> </table> <h2 id="5-launch-and-set-up-mox">5. Launch and Set Up Mox</h2> <p>With the configuration in place, you can now build and start the container.</p> <ol> <li> <p><strong>Build and Start the Service:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># From within the /opt/containers/mox directory</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose up</span><span style="color: #79B8FF;"> -d --build</span></span></code></pre> <p>The <code>--build</code> flag is important for the first launch and whenever you want to update Mox.</p> </li> <li> <p><strong>Access the Admin Wizard:</strong> Navigate to your Mox admin interface in a web browser: <strong><code>https://mail.your-domain.com/admin</code></strong></p> <p>On your first visit, Mox presents an interactive setup wizard to guide you through the initial configuration.</p> </li> </ol> <h2 id="6-updating-mox">6. Updating Mox</h2> <p>Because we are building the image from the source code, updating is a simple process of rebuilding the image and restarting the container.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/mox</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Pull the latest source code and rebuild the image</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose build</span><span style="color: #79B8FF;"> --pull --no-cache</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Restart the container with the new image</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose up</span><span style="color: #79B8FF;"> -d --force-recreate --remove-orphans</span></span></code></pre> <p>The latest Mox version will be automatically pulled from GitHub during the build step.</p> <h2 id="7-maintenance-and-backups">7. Maintenance and Backups</h2> <p>A key advantage of Mox is its simplicity in maintenance.</p> <h3 id="built-in-backups">Built-in Backups</h3> <p>Mox includes a command to back up its entire configuration and mail data into a single file.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Execute this command to create a backup inside the container</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker exec</span><span style="color: #79B8FF;"> -it</span><span style="color: #9ECBFF;"> mox mox backup /data/backup.tgz</span></span></code></pre> <p>You can then copy this file out of the container volume for off-site storage.</p> <h3 id="volume-backup">Volume Backup</h3> <p>For a complete backup strategy, you should also regularly back up the entire <code>./data</code> volume using tools like <code>rsync</code> or <code>restic</code>.</p> <h2 id="8-resource-profile">8. Resource Profile</h2> <p>Mox is exceptionally efficient, making it a great choice for servers with limited resources.</p> <ul> <li><strong>RAM:</strong> Typically idles around 200-300 MB and rarely exceeds 500 MB under load.</li> <li><strong>CPU:</strong> CPU usage is minimal, usually under 1%.</li> <li><strong>Performance:</strong> On small VPS systems (1 vCPU / 1 GB RAM), Mox remains highly responsive even under a light daily mail load (e.g., 100-200 messages per day).</li> </ul> <h2 id="conclusion">Conclusion</h2> <p>You have successfully deployed Mox using a secure, best-practice approach. By building the image from the official source and leveraging Traefik for proper TLS termination, you have a modern, resource-efficient, and secure solution for self-hosting your own email. This setup gives you full control over your data with minimal maintenance overhead.</p> <p><em>Note: Mox is under active development by <a rel="noopener external" target="_blank" href="https://github.com/mjl-">Marten van Leeuwen</a>. Check the <a rel="noopener external" target="_blank" href="https://github.com/mjl-/mox/releases">Mox Releases page</a> for the latest changelog before rebuilding your image.</em></p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;www.xmox.nl&#x2F;docs&#x2F;" class="retro-button"> <span class="emoji">📚</span><span class="button-text">MOX DOCUMENTATION</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;mjl-&#x2F;mox" class="retro-button"> <span class="emoji">📦</span><span class="button-text">MOX GITHUB REPOSITORY</span> </a> </p> Deploying Lemmy with Docker, Traefik, and Nginx Thu, 30 Oct 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/lemmy/ https://criticalbasics.xyz/posts/lemmy/ <p>This guide provides a comprehensive walkthrough for deploying a secure and scalable Lemmy instance. We will use the official deployment pattern, which includes an Nginx container as an internal reverse proxy to manage application-specific routing. This entire stack is placed behind our modern Traefik v3 reverse proxy, which handles TLS, security, and public-facing routing.</p> <p>This “proxy-behind-a-proxy” architecture is highly recommended as it simplifies Traefik’s configuration and makes your Lemmy instance more robust and easier to update, closely following the official deployment standards.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-10-30</td><td>Fixed mixed-content issues by enabling HTTPS settings and proper proxy headers in Lemmy behind Traefik.</td></tr> <tr><td>2025-09-26</td><td><strong>Initial Version:</strong> Guide created using the official Nginx internal proxy method for maximum compatibility and update safety, integrated with the Traefik v3 stack.</td></tr> </tbody></table> </div> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>This guide builds upon a secure Docker environment. Before you begin, you must have a fully functional Traefik v3 and CrowdSec stack.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ HARD REQUIREMENT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The following steps will not work correctly without the Traefik stack running as described in the prerequisite guide.</p> <ul> <li><strong><a href="../traefik_v3_crowdsec_tutorial/">Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack</a></strong>: This is the foundation for our public-facing reverse proxy and security.</li> </ul> </td> </tr> </table> <p>You will also need:</p> <ul> <li>A dedicated subdomain for your Lemmy instance (e.g., <code>lemmy.your-domain.com</code>) pointed to your server’s IP address.</li> <li><code>sudo</code> or root access.</li> <li>The <code>openssl</code> utility for generating secrets (<code>sudo apt install openssl</code>).</li> </ul> <h2 id="2-directory-structure">2. Directory Structure</h2> <p>First, create a dedicated directory for your Lemmy configuration and data. This structure will hold all necessary config files.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Create the main directory</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> /opt/containers/lemmy</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/lemmy</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Create directories for persistent data and configs</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> volumes/pictrs</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> volumes/postgres</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> config</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> chown</span><span style="color: #79B8FF;"> -R</span><span style="color: #9ECBFF;"> 991:991 volumes/pictrs</span></span> <span class="giallo-l"></span></code></pre><h2 id="3-configuration">3. Configuration</h2> <p>We will now create all the necessary configuration files for Nginx, PostgreSQL, Lemmy, and Docker Compose.</p> <h3 id="3-1-generate-secrets">3.1. Generate Secrets</h3> <p>Let’s generate strong, unique secrets for the database, image service, and admin account.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Generate a strong password for the Postgres database</span></span> <span class="giallo-l"><span>POSTGRES_PASSWORD</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">openssl</span><span style="color: #9ECBFF;"> rand</span><span style="color: #79B8FF;"> -hex 32</span><span>)</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;Your Postgres password is: </span><span>$POSTGRES_PASSWORD</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Generate a strong API key for Pictrs</span></span> <span class="giallo-l"><span>PICTRS_API_KEY</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">openssl</span><span style="color: #9ECBFF;"> rand</span><span style="color: #79B8FF;"> -hex 32</span><span>)</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;Your Pictrs API key is: </span><span>$PICTRS_API_KEY</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Generate a strong password for the Lemmy admin user</span></span> <span class="giallo-l"><span>LEMMY_ADMIN_PASSWORD</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">openssl</span><span style="color: #9ECBFF;"> rand</span><span style="color: #79B8FF;"> -hex 32</span><span>)</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;Your Lemmy Admin password is: </span><span>$LEMMY_ADMIN_PASSWORD</span><span style="color: #9ECBFF;">&quot;</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ SAVE THESE SECRETS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Copy these generated values into a temporary text file. You will need to paste them into the configuration files in the upcoming steps.</p> </td> </tr> </table> <h3 id="3-2-nginx-configuration-config-nginx-conf">3.2. Nginx Configuration (<code>config/nginx.conf</code>)</h3> <p>This file contains the internal routing logic that directs traffic to either the Lemmy UI, the backend, or the image store based on the request path and headers.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee config/nginx.conf</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">worker_processes 1;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">events {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> worker_connections 1024;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">http {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> upstream lemmy { server &quot;lemmy:8536&quot;; }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> upstream lemmy-ui { server &quot;lemmy-ui:1234&quot;; }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> server {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> listen 1236;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> listen 8536;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> server_name lemmy.criticalbasics.xyz;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> server_tokens off;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> gzip on;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> gzip_types text/css application/javascript image/svg+xml;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> gzip_vary on;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> client_max_body_size 20M;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> add_header X-Frame-Options SAMEORIGIN;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> add_header X-Content-Type-Options nosniff;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> add_header X-XSS-Protection &quot;1; mode=block&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> location / {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> set $proxpass &quot;http://lemmy-ui&quot;;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> if ($http_accept = &quot;application/activity+json&quot;) { set $proxpass &quot;http://lemmy&quot;; }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> if ($http_accept = &quot;application/ld+json; profile=\&quot;https://www.w3.org/ns/activitystreams\&quot;&quot;) { set $proxpass &quot;http://lemmy&quot;; }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> if ($request_method = POST) { set $proxpass &quot;http://lemmy&quot;; }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_pass $proxpass;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> rewrite ^(.+)/+$ $1 permanent;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_set_header X-Real-IP $remote_addr;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_set_header Host $host;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_set_header X-Forwarded-Ssl on;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> location ~ ^/(api|pictrs|feeds|inbox|outbox|nodeinfo|version|socket\.io|federation|\.well-known) {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_pass &quot;http://lemmy&quot;;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_http_version 1.1;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_set_header Upgrade $http_upgrade;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_set_header Connection &quot;upgrade&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_set_header X-Real-IP $remote_addr;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_set_header Host $host;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_set_header X-Forwarded-Ssl on;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy_redirect off;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><h3 id="3-3-postgresql-configuration">3.3. PostgreSQL Configuration</h3> <p>For better performance, we’ll provide a custom configuration file for PostgreSQL.</p> <h4 id="config-custom-conf-performance-tuning"><code>config/custom.conf</code> (Performance Tuning)</h4> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee config/custom.conf</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Generated by https://pgtune.leopard.in.ua</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># DB Version: 16, OS: linux, RAM: 12 GB, CPUs: 16, Storage: ssd</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">max_connections = 200</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">shared_buffers = 3GB</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">effective_cache_size = 9GB</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">maintenance_work_mem = 768MB</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">checkpoint_completion_target = 0.9</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">wal_buffers = 16MB</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">default_statistics_target = 100</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">random_page_cost = 1.1</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">effective_io_concurrency = 200</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">work_mem = 3932kB</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">min_wal_size = 1GB</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">max_wal_size = 8GB</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">max_worker_processes = 16</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">max_parallel_workers_per_gather = 4</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">max_parallel_workers = 16</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">max_parallel_maintenance_workers = 4</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><h4 id="config-pg-hba-conf-authentication-rules"><code>config/pg_hba.conf</code> (Authentication Rules)</h4> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee config/pg_hba.conf</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># TYPE DATABASE USER ADDRESS METHOD</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">local all all trust</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">host all all 0.0.0.0/0 md5</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">host all all ::/0 md5</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><h3 id="3-4-lemmy-configuration-config-lemmy-hjson">3.4. Lemmy Configuration (<code>config/lemmy.hjson</code>)</h3> <p>This file controls the Lemmy application itself.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee config/lemmy.hjson</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">{</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> database: {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> user: &quot;lemmy&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> password: &quot;PASTE-YOUR-POSTGRES-PASSWORD-HERE&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> host: &quot;postgres&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> port: 5432</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> database: &quot;lemmy&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> pictrs: {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> url: &quot;http://pictrs:8080/&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> api_key: &quot;PASTE-YOUR-PICTRS-API-KEY-HERE&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> email: {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> smtp_server: &quot;your-mail-server.com:587&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> smtp_login: &quot;lemmy@your-domain.com&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> smtp_password: &quot;PASTE-YOUR-EMAIL-PASSWORD-HERE&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> smtp_from_address: &quot;Lemmy &lt;lemmy@your-domain.com&gt;&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> tls_type: &quot;starttls&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> setup: {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> admin_username: &quot;admin&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> admin_password: &quot;PASTE-YOUR-LEMMY-ADMIN-PASSWORD-HERE&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> site_name: &quot;My Lemmy Instance&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> admin_email: &quot;your-admin@example.com&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> hostname: &quot;lemmy.your-domain.com&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> bind: &quot;0.0.0.0&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> port: 8536</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> tls_enabled: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><h3 id="3-5-docker-compose-docker-compose-yml">3.5. Docker Compose (<code>docker-compose.yml</code>)</h3> <p>This file ties all the services together. Notice that only the <code>lemmy-proxy</code> service has Traefik labels and is exposed to the external <code>proxy</code> network.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee docker-compose.yml</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">services:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> lemmy-proxy:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: nginx:stable-alpine</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: lemmy-proxy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./config/nginx.conf:/etc/nginx/nginx.conf:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> depends_on:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - lemmy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - lemmy-ui</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - pictrs</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - proxy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - lemmy-net</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> labels:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.lemmy.rule=Host(`lemmy.your-domain.com`)&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.lemmy.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.lemmy.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.lemmy.middlewares=security-headers@file,crowdsec-bouncer@docker&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.services.lemmy.loadbalancer.server.port=8536&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.docker.network=proxy&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> lemmy:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: dessalines/lemmy:0.19.3</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> hostname: lemmy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: lemmy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> environment:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - RUST_LOG=warn,lemmy_server=info</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./config/lemmy.hjson:/config/config.hjson:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> depends_on:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - postgres</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - pictrs</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - lemmy-net</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> lemmy-ui:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: dessalines/lemmy-ui:0.19.3</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: lemmy-ui</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> hostname: lemmy-ui</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> environment:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - LEMMY_UI_LEMMY_INTERNAL_HOST=lemmy:8536</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - LEMMY_UI_LEMMY_EXTERNAL_HOST=lemmy.your-domain.com</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - LEMMY_UI_HTTPS=true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> depends_on:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - lemmy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - lemmy-net</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> pictrs:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: asonix/pictrs:0.5.1</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> hostname: pictrs</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: pictrs</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> environment:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - PICTRS__API_KEY=PASTE-YOUR-PICTRS-API-KEY-HERE</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - RUST_LOG=info</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> user: 991:991</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./volumes/pictrs:/mnt</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - lemmy-net</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> postgres:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: postgres:16-alpine</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> hostname: postgres</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: postgres</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> environment:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - POSTGRES_USER=lemmy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - POSTGRES_PASSWORD=PASTE-YOUR-POSTGRES-PASSWORD-HERE</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - POSTGRES_DB=lemmy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./volumes/postgres:/var/lib/postgresql/data</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./config/custom.conf:/etc/postgresql/postgresql.conf:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./config/pg_hba.conf:/var/lib/postgresql/data/pg_hba.conf:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - lemmy-net</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> external: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> lemmy-net:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> driver: bridge</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><h3 id="3-6-update-configuration-with-your-values">3.6. Update Configuration with Your Values</h3> <p>Carefully replace all placeholders in the files you just created.</p> <ol> <li><strong>Domain Name:</strong> In <code>config/nginx.conf</code>, <code>config/lemmy.hjson</code>, and <code>docker-compose.yml</code>, replace all instances of <code>lemmy.your-domain.com</code> with your actual domain.</li> <li><strong>Secrets:</strong> In <code>config/lemmy.hjson</code> and <code>docker-compose.yml</code>, paste the secrets you generated in step 3.1. Ensure the Postgres password and Pictrs API key are identical where required.</li> <li><strong>Email Settings:</strong> In <code>config/lemmy.hjson</code>, update the <code>email</code> section with your SMTP server details.</li> </ol> <h2 id="4-launch-the-stack">4. Launch the Stack</h2> <p>With all configuration files in place, you can start your Lemmy instance.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># From within the /opt/containers/lemmy directory</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose up</span><span style="color: #79B8FF;"> -d</span></span></code></pre> <p>The first launch will take a few minutes as Docker downloads all the necessary images. You can monitor the progress with:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose logs</span><span style="color: #79B8FF;"> -f</span></span></code></pre> <p>Press <code>CTRL+C</code> to exit the logs view once the services are stable.</p> <h2 id="5-verify-the-installation">5. Verify the Installation</h2> <ol> <li> <p><strong>Check Running Containers:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> ps</span><span style="color: #79B8FF;"> --format</span><span style="color: #9ECBFF;"> &#39;{{.Names}}&#39;</span></span></code></pre> <p>You should see <code>lemmy-proxy</code>, <code>lemmy</code>, <code>lemmy-ui</code>, <code>pictrs</code>, and <code>postgres</code> running.</p> </li> <li> <p><strong>Access Your Site:</strong> Open a web browser and navigate to <code>https://lemmy.your-domain.com</code>. You should see the Lemmy welcome page.</p> </li> <li> <p><strong>Log In as Admin:</strong> Log in using the admin username (<code>admin</code>) and the strong password you generated for it. You can now begin administering your instance.</p> </li> </ol> <h2 id="6-maintenance">6. Maintenance</h2> <h3 id="updating-lemmy">Updating Lemmy</h3> <p>Updating is now safer. You typically only need to update the image tags in <code>docker-compose.yml</code> for <code>lemmy</code>, <code>lemmy-ui</code>, and <code>pictrs</code>.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/lemmy</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Pull the new images defined in your compose file</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose pull</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Restart the stack with the new images</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose up</span><span style="color: #79B8FF;"> -d --remove-orphans</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 CHECK RELEASE NOTES </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Always consult the official Lemmy release notes before updating for any special instructions or potential changes to configuration files like <code>nginx.conf</code>.</p> </td> </tr> </table> <h3 id="backing-up">Backing Up</h3> <p>A complete backup consists of the database and the uploaded images.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># From your /opt/containers/lemmy directory</span></span> <span class="giallo-l"><span style="color: #6A737D;"># 1. Stop services to ensure data consistency</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose stop lemmy lemmy-ui lemmy-proxy</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 2. Back up the database</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose exec</span><span style="color: #79B8FF;"> -T</span><span style="color: #9ECBFF;"> postgres pg_dump</span><span style="color: #79B8FF;"> -U</span><span style="color: #9ECBFF;"> lemmy</span><span style="color: #79B8FF;"> -d</span><span style="color: #9ECBFF;"> lemmy</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> gzip</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> lemmy_db_backup_</span><span>$(</span><span style="color: #B392F0;">date</span><span style="color: #9ECBFF;"> +%F</span><span>)</span><span style="color: #9ECBFF;">.sql.gz</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 3. Back up the images</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tar</span><span style="color: #79B8FF;"> -czvf</span><span style="color: #9ECBFF;"> pictrs_backup_</span><span>$(</span><span style="color: #B392F0;">date</span><span style="color: #9ECBFF;"> +%F</span><span>)</span><span style="color: #9ECBFF;">.tar.gz volumes/pictrs</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 4. Restart services</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose start</span></span></code></pre><h2 id="conclusion">Conclusion</h2> <p>You have now deployed a production-ready Lemmy instance using a robust and maintainable architecture. By combining the power of Traefik for edge routing and security with the official Nginx proxy for internal application logic, your instance is scalable, secure, and easy to manage for years to come.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;join-lemmy.org&#x2F;docs&#x2F;en&#x2F;administration&#x2F;from_scratch.html" class="retro-button"> <span class="emoji">📚</span><span class="button-text">OFFICIAL LEMMY DOCS</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;LemmyNet&#x2F;lemmy-docker" class="retro-button"> <span class="emoji">📦</span><span class="button-text">OFFICIAL DOCKER REPO</span> </a> </p> Deploying Mastodon with Docker and a Modern Traefik Stack Thu, 30 Oct 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/mastodon/ https://criticalbasics.xyz/posts/mastodon/ <p>This guide provides a step-by-step walkthrough for deploying a production-ready Mastodon instance. We will use the official Mastodon Docker images and configure them to run securely behind our modern Traefik v3 reverse proxy, which handles TLS, security headers, and threat protection via CrowdSec.</p> <p>This setup ensures a robust, scalable, and secure social media platform that you control.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-10-30</td><td><strong>Initial Version:</strong> Guide created, adapting the official Mastodon Docker setup for a modern Traefik v3 and CrowdSec security stack.</td></tr> </tbody></table> </div> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>This guide builds upon a secure and pre-existing Docker environment. Before you begin, you must have a fully functional Traefik v3 and CrowdSec stack.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ HARD REQUIREMENT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The following steps will not work correctly without the Traefik stack running as described in the prerequisite guide.</p> <ul> <li><strong><a href="../traefik-v3-crowdsec-tutorial/">Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack</a></strong>: This is the foundation for our public-facing reverse proxy and security.</li> </ul> </td> </tr> </table> <p>You will also need:</p> <ul> <li>A dedicated domain for your Mastodon instance (e.g., <code>mastodon.your-domain.com</code>) pointed to your server’s IP address.</li> <li><code>sudo</code> or root access.</li> <li>A functional email (SMTP) server for sending transactional emails.</li> </ul> <h2 id="2-directory-structure">2. Directory Structure</h2> <p>First, create a dedicated directory for your Mastodon configuration and data. This structure will hold all necessary files and persistent data.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Create the main directory</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> /opt/containers/mastodon</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/mastodon</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Create directories for persistent data</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> postgres redis public/system</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Mastodon runs as user 991. We need to set the correct permissions.</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> chown</span><span style="color: #79B8FF;"> -R</span><span style="color: #9ECBFF;"> 991:991 public/system</span></span></code></pre><h2 id="3-configuration">3. Configuration</h2> <p>Configuring Mastodon involves generating a configuration file using an interactive wizard and then creating our Docker Compose file to orchestrate the services.</p> <h3 id="3-1-docker-compose-docker-compose-yml">3.1. Docker Compose (<code>docker-compose.yml</code>)</h3> <p>First, create the <code>docker-compose.yml</code> file. We create this file <em>before</em> running the setup wizard so that Docker knows which image to use.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee docker-compose.yml</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">services:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> db:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: postgres:14-alpine</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> shm_size: 256mb</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - mastodon-net</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> healthcheck:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> test: [&#39;CMD&#39;, &#39;pg_isready&#39;, &#39;-U&#39;, &#39;postgres&#39;]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./postgres:/var/lib/postgresql/data</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> environment:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &#39;POSTGRES_HOST_AUTH_METHOD=trust&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> redis:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: redis:7-alpine</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - mastodon-net</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> healthcheck:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> test: [&#39;CMD&#39;, &#39;redis-cli&#39;, &#39;ping&#39;]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./redis:/data</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> web:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: ghcr.io/mastodon/mastodon:v4.4.8</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: mastodon-web</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> env_file: .env.production</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> command: bash -c &quot;rm -f /mastodon/tmp/pids/server.pid; bundle exec rails s -p 3000&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - proxy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - mastodon-net</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> healthcheck:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> test: [&#39;CMD-SHELL&#39;, &#39;wget -q --spider --proxy=off localhost:3000/health || exit 1&#39;]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> depends_on:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - db</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - redis</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> user: 991:991</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./public/system:/mastodon/public/system</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> labels:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.mastodon-web.rule=Host(`${MASTODON_HOST}`)&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.mastodon-web.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.mastodon-web.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.mastodon-web.middlewares=security-headers@file,crowdsec-bouncer@docker&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.services.mastodon-web.loadbalancer.server.port=3000&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.docker.network=proxy&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> streaming:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: ghcr.io/mastodon/mastodon:v4.4.8 # Note: Since v4.3.0, streaming is part of the main image</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: mastodon-streaming</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> env_file: .env.production</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> command: node ./streaming</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - proxy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - mastodon-net</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> healthcheck:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> test: [&#39;CMD-SHELL&#39;, &#39;wget -q --spider --proxy=off localhost:4000/api/v1/streaming/health || exit 1&#39;]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> depends_on:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - db</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - redis</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> labels:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.mastodon-streaming.rule=Host(`${MASTODON_HOST}`) &amp;&amp; PathPrefix(`/api/v1/streaming`)&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.mastodon-streaming.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.mastodon-streaming.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.mastodon-streaming.middlewares=security-headers@file,crowdsec-bouncer@docker&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.services.mastodon-streaming.loadbalancer.server.port=4000&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.docker.network=proxy&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> sidekiq:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: ghcr.io/mastodon/mastodon:v4.4.8</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: mastodon-sidekiq</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> env_file: .env.production</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> command: bundle exec sidekiq</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> depends_on:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - db</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - redis</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - mastodon-net</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./public/system:/mastodon/public/system</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> healthcheck:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> test: [&#39;CMD-SHELL&#39;, &quot;ps aux | grep &#39;[s]idekiq&#39; || false&quot;]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> user: 991:991</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> external: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> mastodon-net:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> driver: bridge</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ A NOTE ON DATABASE SECURITY </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The <code>POSTGRES_HOST_AUTH_METHOD=trust</code> setting is convenient and generally safe within an isolated Docker network where no ports are exposed to the outside world. It allows other containers within the same <code>docker-compose.yml</code> to connect without a password. For production environments with stricter security requirements, you should configure proper password-based authentication.</p> </td> </tr> </table> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 TRAEFIK LABELS EXPLAINED </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The <code>labels</code> section is crucial. It tells our Traefik proxy how to handle requests for Mastodon.</p> <ul> <li><strong><code>tls.certresolver=tls_resolver</code></strong>: This uses the Let’s Encrypt resolver we defined in our main Traefik stack.</li> <li><strong><code>middlewares=security-headers@file,crowdsec-bouncer@docker</code></strong>: This is the key integration. It applies our predefined security headers and protects the instance with the CrowdSec bouncer, blocking malicious IPs.</li> </ul> </td> </tr> </table> <h3 id="3-2-environment-file-env">3.2. Environment File (<code>.env</code>)</h3> <p>Create a simple <code>.env</code> file to store your domain name. The <code>docker-compose.yml</code> will use this.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee .env</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">MASTODON_HOST=mastodon.your-domain.com</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ IMPORTANT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Replace <code>mastodon.your-domain.com</code> with your actual domain. This file is separate from the main Mastodon configuration (<code>.env.production</code>) that we will generate next.</p> </td> </tr> </table> <h3 id="3-3-mastodon-setup-wizard">3.3. Mastodon Setup Wizard</h3> <p>Mastodon provides an interactive setup wizard to generate its main configuration file (<code>.env.production</code>). Let’s run it.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># This command runs the setup task in a temporary container</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose run</span><span style="color: #79B8FF;"> --rm</span><span style="color: #9ECBFF;"> web bundle exec rake mastodon:setup</span></span></code></pre> <p>The wizard will ask you a series of questions. Here are some recommendations:</p> <ul> <li><strong>Domain name</strong>: Enter the same domain you used in your <code>.env</code> file (e.g., <code>mastodon.your-domain.com</code>).</li> <li><strong>Single user mode?</strong>: <code>n</code> (unless you want a private, single-person instance).</li> <li><strong>Are you using Docker?</strong>: <code>y</code>. This will correctly set the database and Redis hostnames.</li> <li><strong>Database host</strong>: It should default to <code>db</code>. Press Enter.</li> <li><strong>Redis host</strong>: It should default to <code>redis</code>. Press Enter.</li> <li><strong>SMTP settings</strong>: Provide the details for your email server. Mastodon needs this to send confirmation emails.</li> <li><strong>Save configuration?</strong>: <code>y</code>. This will create the <code>.env.production</code> file.</li> </ul> <h2 id="4-launch-the-stack">4. Launch the Stack</h2> <p>Now that all configuration is in place, you can start your Mastodon instance.</p> <h3 id="4-1-initial-database-migration">4.1. Initial Database Migration</h3> <p>Before the first full launch, we need to prepare the database.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Run the database migration in a temporary container</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose run</span><span style="color: #79B8FF;"> --rm</span><span style="color: #9ECBFF;"> web rails db:migrate</span></span></code></pre><h3 id="4-2-start-all-services">4.2. Start All Services</h3> <p>With the database ready, bring the entire stack online.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose up</span><span style="color: #79B8FF;"> -d</span></span></code></pre> <p>The first launch will take a few minutes as Docker downloads the images. You can monitor the progress with <code>sudo docker compose logs -f</code>.</p> <h2 id="5-post-installation-steps">5. Post-Installation Steps</h2> <p>Your instance is running, but you need to create an admin account.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Use this command to create an admin user interactively</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose run</span><span style="color: #79B8FF;"> --rm</span><span style="color: #9ECBFF;"> web tootctl accounts create YOUR_USERNAME</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> --email</span><span style="color: #9ECBFF;"> YOUR_EMAIL@example.com</span><span style="color: #79B8FF;"> --confirmed --role</span><span style="color: #9ECBFF;"> Admin</span></span></code></pre> <p>Replace <code>YOUR_USERNAME</code> and <code>YOUR_EMAIL@example.com</code> with your desired credentials. You will be prompted to set a password.</p> <p>You can now navigate to <code>https://mastodon.your-domain.com</code> and log in with your new admin account.</p> <h2 id="6-maintenance">6. Maintenance</h2> <h3 id="updating-mastodon">Updating Mastodon</h3> <p>Updating is a straightforward process. First, check the official Mastodon release notes for any special instructions.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/mastodon</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Update the image tags in your docker-compose.yml to the new version</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Pull the new images</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose pull</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Stop the services before migrating the database</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose down</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Run database migrations required by the new version</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose run</span><span style="color: #79B8FF;"> --rm</span><span style="color: #9ECBFF;"> web rails db:migrate</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Start the stack again</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose up</span><span style="color: #79B8FF;"> -d --remove-orphans</span></span></code></pre><h3 id="backing-up">Backing Up</h3> <p>A complete backup consists of the database, user-uploaded files, and Redis data.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/mastodon</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 1. Back up the database</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose exec</span><span style="color: #79B8FF;"> -T</span><span style="color: #9ECBFF;"> db pg_dump</span><span style="color: #79B8FF;"> -U</span><span style="color: #9ECBFF;"> postgres</span><span style="color: #79B8FF;"> -d</span><span style="color: #9ECBFF;"> mastodon_production</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> gzip</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> mastodon_db_backup_</span><span>$(</span><span style="color: #B392F0;">date</span><span style="color: #9ECBFF;"> +%F</span><span>)</span><span style="color: #9ECBFF;">.sql.gz</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 2. Back up user-uploaded files</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tar</span><span style="color: #79B8FF;"> -czvf</span><span style="color: #9ECBFF;"> mastodon_files_backup_</span><span>$(</span><span style="color: #B392F0;">date</span><span style="color: #9ECBFF;"> +%F</span><span>)</span><span style="color: #9ECBFF;">.tar.gz public/system</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 3. Back up Redis data</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tar</span><span style="color: #79B8FF;"> -czvf</span><span style="color: #9ECBFF;"> mastodon_redis_backup_</span><span>$(</span><span style="color: #B392F0;">date</span><span style="color: #9ECBFF;"> +%F</span><span>)</span><span style="color: #9ECBFF;">.tar.gz redis</span></span></code></pre><h2 id="conclusion">Conclusion</h2> <p>You have successfully deployed a production-ready Mastodon instance. By leveraging Docker for containerization and integrating with a modern Traefik and CrowdSec stack, your instance is not only scalable and easy to manage but also benefits from robust, centralized security and TLS management.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;docs.joinmastodon.org&#x2F;admin&#x2F;install&#x2F;" class="retro-button"> <span class="emoji">📚</span><span class="button-text">OFFICIAL MASTODON DOCS</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;mastodon&#x2F;mastodon" class="retro-button"> <span class="emoji">📦</span><span class="button-text">OFFICIAL GITHUB REPO</span> </a> </p> Deploying Mailcow with Docker and Traefik for a Full E-Mail Stack Fri, 03 Oct 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/mailcow-mailserver/ https://criticalbasics.xyz/posts/mailcow-mailserver/ <p>Mailcow is a powerful and flexible open-source mail server suite that allows you to manage your email communications securely and efficiently. With Mailcow, you can create multiple email domains and accounts, manage users, and leverage features like spam filtering and encryption, giving you full control over your email infrastructure. This guide will show you how to set up Mailcow using Docker Compose behind an existing Traefik reverse proxy.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-10-03</td><td><strong>Major Revision:</strong> Corrected <code>certdumper</code> command, simplified Traefik labels, and fixed critical <code>mailcow.conf</code> networking settings to resolve 404 errors. Enhanced troubleshooting for network conflicts.</td></tr> <tr><td>2025-09-18</td><td><strong>Initial Version:</strong> First version of this guide was created.</td></tr> </tbody></table> </div> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>This guide assumes you have a fully functional server environment with the following components already set up:</p> <ul> <li><strong><a href="../traefik-v3-crowdsec-tutorial/">Traefik v3 and CrowdSec with Docker Compose</a></strong>: This is the foundation for our reverse proxy, security, and certificate management.</li> <li><strong>Docker and Docker Compose</strong>: Must be installed on your server.</li> <li><strong>Required Tools</strong>: You will need <code>git</code> and <code>jq</code>. Install them with:<pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt update</span><span> &amp;&amp;</span><span style="color: #B392F0;"> sudo</span><span style="color: #9ECBFF;"> apt install</span><span style="color: #79B8FF;"> -y</span><span style="color: #9ECBFF;"> git jq</span></span></code></pre></li> <li><code>sudo</code> or root access.</li> </ul> <h2 id="2-directory-structure">2. Directory Structure</h2> <p>First, create a dedicated directory for your Mailcow installation.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ PATH CONSISTENCY </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>This guide uses <code>/opt/containers/mailcow/</code> as the primary directory for the Mailcow stack. The Traefik stack is assumed to be in <code>/opt/containers/traefik-stack/</code>, consistent with our <a href="../traefik-v3-crowdsec-tutorial/">Traefik v3 tutorial</a>. If your paths differ, be sure to adjust them in all configuration files and commands throughout this guide.</p> </td> </tr> </table> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> /opt/containers/mailcow</span></span></code></pre><h2 id="3-clone-the-mailcow-repository">3. Clone the Mailcow Repository</h2> <p>Clone the latest version of the Mailcow Dockerized project from GitHub into the directory you just created.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> git clone https://github.com/mailcow/mailcow-dockerized /opt/containers/mailcow</span></span></code></pre><h2 id="4-generate-the-configuration-file">4. Generate the Configuration File</h2> <p>Navigate into the new directory and run the configuration generation script.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/mailcow</span></span> <span class="giallo-l"><span style="color: #B392F0;">./generate_config.sh</span></span></code></pre> <p>You will be prompted for the following information:</p> <ul> <li><strong>Mail server hostname (FQDN):</strong> Enter the fully qualified domain name for your mail server, for example, <code>mail.your-domain.com</code>.</li> <li><strong>Timezone:</strong> Press Enter to accept the default or provide your own.</li> <li><strong>Available Branches:</strong> Press <code>1</code> to select the master branch.</li> </ul> <h2 id="5-configure-for-traefik-integration">5. Configure for Traefik Integration</h2> <p>To make Mailcow work with our external Traefik instance, we need to create an override file and modify the main configuration.</p> <h3 id="5-1-create-docker-compose-override-yml">5.1. Create <code>docker-compose.override.yml</code></h3> <p>This file contains all our customizations, telling Mailcow to use the external <code>proxy</code> network and defining labels for Traefik to route traffic correctly. It also sets up a <code>certdumper</code> service, which is crucial for sharing Traefik’s Let’s Encrypt certificates with Mailcow’s services (Postfix and Dovecot).</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ HOW THE CERTDUMPER WORKS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The <code>certdumper</code> is essential. It extracts certificates from Traefik’s <code>acme.json</code> and saves them as <code>.pem</code> files that Postfix and Dovecot can read. The command <code> --restart-containers mailcowdockerized-postfix-mailcow-1,...</code> is critical; it restarts the mail services by their full Docker container name after a certificate is updated, ensuring the new certificate is loaded immediately.</p> </td> </tr> </table> <p>Create the file:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee /opt/containers/mailcow/docker-compose.override.yml</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> name: proxy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> external: true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">services:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> certdumper:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: ghcr.io/kereis/traefik-certs-dumper:latest</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> network_mode: none</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Correct command to restart containers by their full name. Mailcow&#39;s project name is &quot;mailcowdockerized&quot;.</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> command: --restart-containers mailcowdockerized-postfix-mailcow-1,mailcowdockerized-dovecot-mailcow-1</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Adjust this path to match YOUR Traefik stack&#39;s certificate location</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - /opt/containers/traefik-stack/traefik/certs:/traefik:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - /var/run/docker.sock:/var/run/docker.sock:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./data/assets/ssl:/output:rw</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> environment:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> DOMAIN: ${MAILCOW_HOSTNAME}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Adjust this to match YOUR Traefik acme file name</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ACME_FILE_PATH: &quot;/traefik/acme.json&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> healthcheck:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> test: [&quot;CMD&quot;, &quot;/usr/bin/healthcheck&quot;]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> interval: 30s</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> timeout: 10s</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> retries: 5</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> nginx-mailcow:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # We use !reset to completely remove the default port bindings set by Mailcow.</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ports: !reset</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - proxy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> labels:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.docker.network=proxy&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # HTTPS Router (Secure)</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # The HTTP to HTTPS redirect is handled globally by our Traefik setup, so we only need the secure router.</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.nginx-mailcow-secure.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.nginx-mailcow-secure.rule=Host(`mail.your-domain.com`) || Host(`autodiscover.your-domain.com`) || Host(`autoconfig.your-domain.com`) || Host(`mta-sts.your-domain.com`)&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.nginx-mailcow-secure.tls=true&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.nginx-mailcow-secure.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.nginx-mailcow-secure.service=nginx-mailcow&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.nginx-mailcow-secure.middlewares=security-headers@file,crowdsec-bouncer@docker&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Service Definition: Point to Mailcow&#39;s internal Nginx port.</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # This must be 80, as we are NOT changing the internal ports in mailcow.conf</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.services.nginx-mailcow.loadbalancer.server.port=80&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ CROWDSEC BOUNCER SCOPE </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The <code>crowdsec-bouncer@docker</code> middleware only protects the HTTP/HTTPS endpoints routed through Traefik (like the Mailcow UI and SOGo). It does <strong>not</strong> protect mail services like SMTP, IMAP, or POP3, as their traffic does not pass through the Traefik router. To harden these mail protocols, you need to configure CrowdSec to parse their log files (e.g., using the <code>crowdsecurity/postfix</code> and <code>crowdsecurity/dovecot</code> collections on the host).</p> </td> </tr> </table> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ IMPORTANT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>You must replace <code>your-domain.com</code> with your actual domain name. You can do this manually or with the following command:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> sed</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> &quot;s/your-domain.com/your-actual-domain.com/g&quot; docker-compose.override.yml</span></span></code></pre> </td> </tr> </table> <h3 id="5-2-adjust-mailcow-conf">5.2. Adjust <code>mailcow.conf</code></h3> <p>Next, edit the main configuration file. There are only <strong>two changes</strong> needed here.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> nano /opt/containers/mailcow/mailcow.conf```</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">&lt;!</span><span style="color: #B392F0;">--</span><span style="color: #9ECBFF;"> Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre</span><span style="color: #79B8FF;"> --</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;">&lt;!</span><span style="color: #B392F0;">--</span><span style="color: #9ECBFF;"> Verwendung: infobox(</span><span>type</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;info&quot;,</span><span> title</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;Titel&quot;) mit Inhalt der Box</span><span style="color: #79B8FF;"> --</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;">&lt;!</span><span style="color: #B392F0;">--</span><span style="color: #9ECBFF;"> Types: info, warning, tip, note</span><span style="color: #79B8FF;"> --</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">table</span><span> class</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;retro-infobox&quot;</span><span> width</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;100%&quot;</span><span> cellspacing</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;0&quot;</span><span> cellpadding</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;10&quot;</span><span> border</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;1&quot;</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">tr</span><span style="color: #9ECBFF;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">td</span><span style="color: #9ECBFF;"> bgcolor=&quot;#eeeeee&quot; style=&quot;color: #000000; font-weight: bold;&quot;</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"><span style="color: #B392F0;"> ℹ️</span><span style="color: #9ECBFF;"> </span></span> <span class="giallo-l"><span style="color: #B392F0;"> CRITICAL:</span><span style="color: #9ECBFF;"> DO NOT CHANGE PORTS OR BINDINGS!</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">/td</span><span style="color: #9ECBFF;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">/tr</span><span style="color: #9ECBFF;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">tr</span><span style="color: #9ECBFF;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">td</span><span style="color: #9ECBFF;"> bgcolor=&quot;#000000&quot; style=&quot;color: #ffffff;&quot;</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">p</span><span style="color: #9ECBFF;">&gt;Do</span><span style="color: #F97583;"> &lt;</span><span style="color: #9ECBFF;">strong</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;">not</span><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">/strong</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;"> change</span><span style="color: #F97583;"> &lt;</span><span style="color: #9ECBFF;">code</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;">HTTP_PORT</span><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">/code</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;">,</span><span style="color: #F97583;"> &lt;</span><span style="color: #9ECBFF;">code</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;">HTTPS_PORT</span><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">/code</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;">,</span><span style="color: #F97583;"> &lt;</span><span style="color: #9ECBFF;">code</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;">HTTP_BIND</span><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">/code</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;">, or</span><span style="color: #F97583;"> &lt;</span><span style="color: #9ECBFF;">code</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;">HTTPS_BIND</span><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">/code</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;">. Leaving them at their default values is crucial. Changing</span><span style="color: #F97583;"> &lt;</span><span style="color: #9ECBFF;">code</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;">HTTP_BIND</span><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">/code</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;"> to</span><span style="color: #F97583;"> &lt;</span><span style="color: #9ECBFF;">code</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;">127.0.0.1</span><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">/code</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;"> will prevent Traefik from reaching the Mailcow web UI, resulting in a</span><span style="color: #F97583;"> &lt;</span><span style="color: #9ECBFF;">strong</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;">404 Not Found error</span><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">/strong</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;">. The internal ports do not conflict with Traefik because they are inside the Docker network, not on the host.</span><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">/p</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">/td</span><span style="color: #9ECBFF;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">/tr</span><span style="color: #9ECBFF;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">/table</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">1.</span><span style="color: #79B8FF;"> **</span><span style="color: #9ECBFF;">Disable Mailcow&#39;s Let&#39;s Encrypt:</span><span style="color: #79B8FF;">**</span><span style="color: #9ECBFF;"> Traefik is responsible for all certificate management. This is the most important change.</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ```</span><span style="color: #B392F0;">ini</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Find this line:</span></span> <span class="giallo-l"><span> SKIP_LETS_ENCRYPT</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">n</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Change it to:</span></span> <span class="giallo-l"><span> SKIP_LETS_ENCRYPT</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">y</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ```</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">2.</span><span style="color: #79B8FF;"> **</span><span style="color: #9ECBFF;">Add SAN for Internal TLS:</span><span style="color: #79B8FF;">**</span><span style="color: #9ECBFF;"> This helps internal services correctly recognize the hostname on the certificate provided by the `</span><span style="color: #B392F0;">certdumper</span><span style="color: #9ECBFF;">`</span><span style="color: #79B8FF;">.</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ```</span><span style="color: #B392F0;">ini</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Find this line (it may be commented out):</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # ADDITIONAL_SAN=</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Change it to:</span></span> <span class="giallo-l"><span> ADDITIONAL_SAN</span><span style="color: #F97583;">=</span><span>${MAILCOW_HOSTNAME}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ```</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">Save</span><span style="color: #9ECBFF;"> and close the file. No other changes are needed in this file.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;">### 5.3. Activate MTA-STS</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">MTA-STS</span><span style="color: #9ECBFF;"> (Mail Transfer Agent-Strict Transport Security) is a security standard that helps prevent man-in-the-middle attacks by ensuring emails are transmitted over secure TLS connections.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">&lt;!</span><span style="color: #B392F0;">--</span><span style="color: #9ECBFF;"> Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre</span><span style="color: #79B8FF;"> --</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;">&lt;!</span><span style="color: #B392F0;">--</span><span style="color: #9ECBFF;"> Verwendung: infobox(</span><span>type</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;info&quot;,</span><span> title</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;Titel&quot;) mit Inhalt der Box</span><span style="color: #79B8FF;"> --</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;">&lt;!</span><span style="color: #B392F0;">--</span><span style="color: #9ECBFF;"> Types: info, warning, tip, note</span><span style="color: #79B8FF;"> --</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">table</span><span> class</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;retro-infobox&quot;</span><span> width</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;100%&quot;</span><span> cellspacing</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;0&quot;</span><span> cellpadding</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;10&quot;</span><span> border</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;1&quot;</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">tr</span><span style="color: #9ECBFF;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">td</span><span style="color: #9ECBFF;"> bgcolor=&quot;#ccffcc&quot; style=&quot;color: #000000; font-weight: bold;&quot;</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"><span style="color: #B392F0;"> 💡</span><span style="color: #9ECBFF;"> </span></span> <span class="giallo-l"><span style="color: #B392F0;"> EASIER</span><span style="color: #9ECBFF;"> ALTERNATIVE: USE THE MAILCOW UI</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">/td</span><span style="color: #9ECBFF;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">/tr</span><span style="color: #9ECBFF;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">tr</span><span style="color: #9ECBFF;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">td</span><span style="color: #9ECBFF;"> bgcolor=&quot;#000000&quot; style=&quot;color: #ffffff;&quot;</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">p</span><span style="color: #9ECBFF;">&gt;Instead of creating the policy file by hand, you can navigate to</span><span style="color: #F97583;"> &lt;</span><span style="color: #9ECBFF;">strong</span><span style="color: #F97583;">&gt;</span><span style="color: #9ECBFF;">System -&amp;</span><span style="color: #B392F0;">gt</span><span style="color: #9ECBFF;">;</span><span style="color: #B392F0;"> Configuration</span><span style="color: #9ECBFF;"> -&amp;</span><span style="color: #B392F0;">gt</span><span style="color: #9ECBFF;">;</span><span style="color: #B392F0;"> MTA-STS</span><span style="color: #9ECBFF;">&lt;/strong&gt; in the Mailcow UI after setup. The UI provides a generator that creates the correct policy and DNS records for you, which is less error-prone. The manual method below is still valid if you prefer it.</span><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">/p</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">/td</span><span style="color: #9ECBFF;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;"> &lt;</span><span style="color: #B392F0;">/tr</span><span style="color: #9ECBFF;">&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">/table</span><span style="color: #F97583;">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">If</span><span style="color: #9ECBFF;"> you choose the manual route, create the required directory:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">```</span><span style="color: #B392F0;">bash</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> /opt/containers/mailcow/data/web/.well-known/</span></span></code></pre> <p>Now, create the policy file with a simple <code>enforce</code> policy. This file will be served by Mailcow’s web server.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee /opt/containers/mailcow/data/web/.well-known/mta-sts.txt</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">version: STSv1</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">mode: enforce</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">max_age: 15552000</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">mx: mail.your-domain.com</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ IMPORTANT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>You must replace <code>your-domain.com</code> with your actual domain name in the file above. You can do this with the following command:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> sed</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> &quot;s/your-domain.com/your-actual-domain.com/g&quot; /opt/containers/mailcow/data/web/.well-known/mta-sts.txt</span></span></code></pre> </td> </tr> </table> <h2 id="6-launch-mailcow">6. Launch Mailcow</h2> <p>You can now start the Mailcow stack.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/mailcow</span></span> <span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose up</span><span style="color: #79B8FF;"> -d</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 TROUBLESHOOTING TIPS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <ul> <li><strong>Pool Overlaps</strong>: If you see an error like <code>Pool overlaps with other one on this address space</code>, another Docker network is using Mailcow’s default IP range. You can fix this permanently by editing <code>mailcow.conf</code> and setting <code>IPV4_NETWORK</code> to an unused subnet prefix (e.g., <code>IPV4_NETWORK=172.25.1</code>). Mailcow will correctly append <code>.0/24</code> to create the network.</li> <li><strong>RAM Usage</strong>: On a VPS with limited memory, you can disable resource-intensive services by setting <code>SKIP_FTS=y</code> (disables full-text search in Solr) or <code>SKIP_CLAMD=y</code> (disables the ClamAV antivirus engine) in <code>mailcow.conf</code>. This reduces security and functionality, so use it with caution.</li> <li><strong>IPv6 Issues</strong>: Some Mailcow versions had startup issues when <code>ENABLE_IPV6=y</code> was set. If you face problems, check the official Mailcow blog for release notes and patches.</li> </ul> </td> </tr> </table> <h2 id="7-dns-configuration">7. DNS Configuration</h2> <p>Correct DNS setup is critical for a mail server to function.</p> <h3 id="7-1-reverse-dns-ptr-record">7.1. Reverse DNS (PTR Record)</h3> <p>Your server’s Reverse DNS (PTR) record for both IPv4 and IPv6 must match the hostname you configured in <code>mailcow.conf</code> (<code>mail.your-domain.com</code>). This is usually set in your server provider’s control panel and is essential for not being marked as spam, especially by major providers like Gmail.</p> <h3 id="7-2-dns-records">7.2. DNS Records</h3> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ USING CLOUDFLARE? </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>If you are using Cloudflare for your DNS, all mail-related records (including <code>mail</code>, <code>imap</code>, <code>smtp</code>, <code>autodiscover</code>, <code>autoconfig</code>, and <code>mta-sts</code>) <strong>must</strong> be set to “DNS only” (grey cloud). Cloudflare’s proxy (orange cloud) only supports web protocols like HTTP/HTTPS and will break mail services. For more details, see the <a rel="noopener external" target="_blank" href="https://developers.cloudflare.com/dns/manage-dns-records/proxied-dns-records/#supported-ports">official Cloudflare documentation</a>.</p> </td> </tr> </table> <p>In your domain’s DNS management panel, add the following records. We start with a non-restrictive DMARC policy (<code>p=none</code>) to prevent legitimate emails from being rejected during the initial setup.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ GMAIL &amp; YAHOO SENDER REQUIREMENTS (2024) </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>As of 2024, major providers like Gmail and Yahoo enforce stricter sender policies:</p> <ul> <li><strong>All Senders</strong>: Must have either SPF or DKIM configured.</li> <li><strong>Bulk Senders</strong> (5,000+ emails/day): Must have SPF, DKIM, <strong>and</strong> a DMARC policy. They also require one-click unsubscribe links and must maintain a low spam complaint rate.</li> </ul> <p>Failing to meet these requirements will result in your emails being rejected. For more details, see the official announcements from <a rel="noopener external" target="_blank" href="https://blog.google/products/gmail/gmail-security-authentication-spam-protection/">Google</a> and <a rel="noopener external" target="_blank" href="https://blog.postmaster.yahooinc.com/post/730172167494483968/more-secure-less-spam">Yahoo</a>.</p> </td> </tr> </table> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ DMARC STAGED ROLLOUT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Starting with <code>p=none</code> is the safest approach. This allows you to monitor email traffic via the reports sent to your <code>rua</code> address without affecting mail delivery.</p> <ol> <li><strong>Monitor</strong>: Keep <code>p=none</code> for a few weeks and analyze the reports to ensure all legitimate sending sources are correctly authenticated with SPF and DKIM.</li> <li><strong>Quarantine</strong>: Once you are confident, switch to <code>p=quarantine</code>. This tells receiving servers to treat failing emails with suspicion (e.g., by sending them to the spam folder).</li> <li><strong>Reject</strong>: After another monitoring period, you can move to the final policy, <code>p=reject</code>, which instructs receivers to block emails that fail DMARC checks.</li> </ol> </td> </tr> </table> <table><thead><tr><th>Name</th><th>Type</th><th>Value</th></tr></thead><tbody> <tr><td>mail</td><td>A</td><td>your-server-ip</td></tr> <tr><td>mail</td><td>AAAA</td><td>your-server-ipv6</td></tr> <tr><td>autodiscover</td><td>CNAME</td><td>mail.your-domain.com.</td></tr> <tr><td>autoconfig</td><td>CNAME</td><td>mail.your-domain.com.</td></tr> <tr><td>imap</td><td>CNAME</td><td>mail.your-domain.com.</td></tr> <tr><td>pop3</td><td>CNAME</td><td>mail.your-domain.com.</td></tr> <tr><td>smtp</td><td>CNAME</td><td>mail.your-domain.com.</td></tr> <tr><td>@</td><td>MX 10</td><td>mail.your-domain.com.</td></tr> <tr><td><strong>SPF</strong></td><td></td><td></td></tr> <tr><td>@</td><td>TXT</td><td><code>v=spf1 mx a -all</code></td></tr> </tbody></table> <p><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 SPF FINE-TUNING </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The <code>v=spf1 mx a -all</code> record is a safe default. The <code>a</code> part authorizes the server’s main IP address (from the <code>A</code> record) to send mail. If you only send mail from Mailcow, you can make this slightly stricter by using <code>v=spf1 mx -all</code>, which only authorizes servers listed in your <code>MX</code> records.</p> </td> </tr> </table> | <strong>DMARC</strong> | | | | _dmarc | TXT | <code>v=DMARC1; p=none; rua=mailto:admin@your-domain.com</code> | | <strong>MTA-STS</strong> | | | | mta-sts | A | your-server-ip | | mta-sts | AAAA | your-server-ipv6 | | _mta-sts | TXT | <code>v=STSv1; id=2025091801</code> | | _smtp._tls | TXT | <code>v=TLSRPTv1; rua=mailto:admin@your-domain.com</code> | | <strong>Service Records</strong> | | | | _autodiscover._tcp | SRV | <code>0 1 443 mail.your-domain.com.</code> | | _caldavs._tcp | SRV | <code>0 1 443 mail.your-domain.com.</code> | | _caldavs._tcp | TXT | <code>"path=/SOGo/dav/"</code> | | _carddavs._tcp | SRV | <code>0 1 443 mail.your-domain.com.</code> | | _carddavs._tcp | TXT | <code>"path=/SOGo/dav/"</code> | | _imaps._tcp | SRV | <code>0 1 993 mail.your-domain.com.</code> | | _pop3s._tcp | SRV | <code>0 1 995 mail.your-domain.com.</code> | | _submission._tcp | SRV | <code>0 1 587 mail.your-domain.com.</code> | | _smtps._tcp | SRV | <code>0 1 465 mail.your-domain.com.</code> |</p> <p>A DKIM record will be added later after it’s generated by Mailcow.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ UNUSED SRV RECORDS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>This guide only lists SRV records for encrypted services (IMAPS, POP3S, etc.). If you decide not to offer certain services (e.g., POP3), you should also omit their corresponding SRV records to prevent clients from attempting to connect to them.</p> </td> </tr> </table> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ DNS RECORD NOTES </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <ul> <li><strong>A vs. CNAME for <code>mta-sts</code></strong>: We use <code>A</code>/<code>AAAA</code> records for <code>mta-sts</code> pointing directly to the server’s IP. While a <code>CNAME</code> pointing to <code>mail.your-domain.com</code> is also valid, using <code>A</code>/<code>AAAA</code> records avoids potential edge cases with some DNS resolvers.</li> <li><strong>Trailing Dots</strong>: Note the trailing dot (<code>.</code>) at the end of hostnames in <code>MX</code> and <code>SRV</code> records (e.g., <code>mail.your-domain.com.</code>). This signifies that the name is fully qualified. Some DNS providers add this automatically, while others require you to add it manually.</li> </ul> </td> </tr> </table> <h2 id="8-firewall-configuration">8. Firewall Configuration</h2> <p>Your firewall must allow traffic on several ports for email services to be reachable.</p> <table><thead><tr><th>Port</th><th>Service</th><th>Protocol</th></tr></thead><tbody> <tr><td>25</td><td>SMTP</td><td>TCP</td></tr> <tr><td>587</td><td>Submission</td><td>TCP</td></tr> <tr><td>465</td><td>SMTPS</td><td>TCP</td></tr> <tr><td>143</td><td>IMAP</td><td>TCP</td></tr> <tr><td>993</td><td>IMAPS</td><td>TCP</td></tr> <tr><td>110</td><td>POP3</td><td>TCP</td></tr> <tr><td>995</td><td>POP3S</td><td>TCP</td></tr> <tr><td>4190</td><td>ManageSieve</td><td>TCP</td></tr> </tbody></table> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 PROTOCOL HYGIENE </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>For better security, consider disabling protocols you don’t need. For example, if all your clients use IMAP, you can keep the POP3 ports (110, 995) closed. It is also best practice to enforce encrypted connections, favoring Submission (587) and IMAPS (993) over their unencrypted counterparts.</p> </td> </tr> </table> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ RESERVED INTERNAL PORTS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Mailcow uses several ports internally (e.g., 8081, 9081, 65510). Avoid using these for your own services on the Docker host to prevent conflicts.</p> </td> </tr> </table> <p>Use <code>ufw</code> to open these ports:</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ DOCKER BYPASSES UFW RULES </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>By default, Docker manipulates <code>iptables</code> directly and <strong>bypasses UFW rules</strong>, meaning your container ports might be exposed even if <code>ufw</code> is configured to block them. There are two effective ways to mitigate this:</p> <ol> <li><strong>Bind Services to Localhost (Recommended)</strong>: As we did in <code>mailcow.conf</code> with <code>HTTP_BIND</code>, binding services to <code>127.0.0.1</code> ensures they are never exposed externally by Docker. This is the most secure approach.</li> <li><strong>Modify UFW’s Configuration</strong>: For services that must be exposed, you can edit <code>/etc/ufw/after.rules</code> to correctly manage traffic from Docker’s network. This is more complex but necessary for direct external access. For more details, see the official <a rel="noopener external" target="_blank" href="https://docs.docker.com/network/packet-filtering-firewalls/">Docker documentation on packet filtering</a>.</li> </ol> </td> </tr> </table> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 25/tcp</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 587/tcp</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 465/tcp</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 143/tcp</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 993/tcp</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 110/tcp</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 995/tcp</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 4190/tcp</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw status</span></span></code></pre><h2 id="9-initial-mailcow-setup">9. Initial Mailcow Setup</h2> <p>Navigate to your Mailcow UI at <code>https://mail.your-domain.com</code>.</p> <ul> <li><strong>Default Username:</strong> <code>admin</code></li> <li><strong>Default Password:</strong> <code>moohoo</code></li> </ul> <p>First, change the administrator password under <strong>System -&gt; Configuration -&gt; Edit</strong>.</p> <h3 id="9-1-add-your-domain">9.1. Add Your Domain</h3> <p>Go to <strong>Email -&gt; Configuration</strong> and click <strong>“Add domain”</strong>. Enter your main domain (e.g., <code>your-domain.com</code>, not <code>mail.your-domain.com</code>).</p> <h3 id="9-2-generate-dkim-key">9.2. Generate DKIM Key</h3> <p>A DKIM key is essential for email authentication.</p> <ol> <li> <p>Go to <strong>System -&gt; Configuration</strong>.</p> </li> <li> <p>Navigate to the <strong>Options -&gt; ARC/DKIM keys</strong> tab.</p> </li> <li> <p>A 2048-bit key should already be generated for your domain. Copy the public key text from the text box.</p> </li> <li> <p>Go back to your DNS provider and add a new TXT record:</p> <ul> <li><strong>Name:</strong> <code>dkim._domainkey</code></li> <li><strong>Value:</strong> Paste the entire copied key, including the <code>v=DKIM1;k=rsa;p=...</code> part.</li> </ul> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 LONG DKIM RECORDS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Some DNS providers have a 255-character limit for a single TXT record string. If your 2048-bit DKIM key is longer, you may need to split it into multiple quoted strings. Many providers handle this automatically, but if you encounter issues, check your provider’s documentation on how to format long TXT records.</p> </td> </tr> </table> </li> </ol> <h2 id="10-testing-and-verification">10. Testing and Verification</h2> <p>After waiting for DNS propagation, thoroughly test your setup.</p> <h3 id="10-1-internal-dns-and-certificate-check">10.1. Internal DNS and Certificate Check</h3> <ul> <li><strong>Mailcow DNS Check</strong>: In the Mailcow UI, go to <strong>Email -&gt; Configuration -&gt; DNS</strong> next to your domain for an internal check of your records.</li> <li><strong>Verify Certificates</strong>: Ensure that the certificates from Traefik have been correctly passed to Mailcow’s services. Run these commands, replacing <code>mail.your-domain.com</code> with your mail server’s FQDN:<pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Check SMTP certificate</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;Q&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> openssl</span><span style="color: #9ECBFF;"> s_client</span><span style="color: #79B8FF;"> -starttls</span><span style="color: #9ECBFF;"> smtp</span><span style="color: #79B8FF;"> -crlf -connect</span><span style="color: #9ECBFF;"> mail.your-domain.com:587</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Check IMAP certificate</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;Q&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> openssl</span><span style="color: #9ECBFF;"> s_client</span><span style="color: #79B8FF;"> -starttls</span><span style="color: #9ECBFF;"> imap</span><span style="color: #79B8FF;"> -crlf -connect</span><span style="color: #9ECBFF;"> mail.your-domain.com:143</span></span></code></pre>In the output, look for a certificate chain issued by a trusted authority. For Let’s Encrypt, the chain typically starts with <code>ISRG Root X1</code>. The key is to confirm it is <strong>not</strong> a self-signed certificate. If you see a self-signed certificate (where the issuer matches the subject), it indicates a problem with the <code>certdumper</code> service or its path mappings. In that case, check the certdumper logs:<pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/mailcow</span></span> <span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose logs certdumper</span></span></code></pre></li> </ul> <h3 id="10-2-external-testing-tools">10.2. External Testing Tools</h3> <ul> <li><strong>mail-tester.com</strong>: Send an email to the address provided on their site to get a score out of 10.</li> <li><strong>mxtoolbox.com</strong>: Provides various checks for your mail server.</li> <li><strong>checktls.com/TestReceiver</strong>: Use this to specifically verify your MTA-STS configuration.</li> </ul> <h2 id="11-create-mailboxes-and-log-in">11. Create Mailboxes and Log In</h2> <p>Under <strong>Email -&gt; Mailboxes</strong>, you can add new users. Once a user is created, the primary way to access the webmail interface (SOGo) is by clicking <strong>Apps -&gt; Webmail</strong> from within the Mailcow UI. While you can also try going directly to <code>https://mail.your-domain.com/SOGo/</code>, be aware that recent Mailcow versions may redirect unauthenticated access back to the main login page.</p> <h2 id="12-conclusion">12. Conclusion</h2> <p>You have now successfully deployed a full-featured Mailcow e-mail server. By leveraging Docker for containerization and Traefik for reverse proxying and certificate management, you have a secure, robust, and maintainable mail solution. This setup provides you with complete control over your email, enhanced security through features like MTA-STS, and the flexibility to manage multiple domains and users with ease.</p> <h2 id="13-further-reading">13. Further Reading</h2> <p>For more detailed information, refer to the official Mailcow documentation:</p> <ul> <li><strong>Reverse Proxy Overview:</strong> <a rel="noopener external" target="_blank" href="https://docs.mailcow.email/post_installation/reverse-proxy/r_p/">docs.mailcow.email/post_installation/reverse-proxy/r_p/</a></li> <li><strong>IP Bindings:</strong> <a rel="noopener external" target="_blank" href="https://docs.mailcow.email/">docs.mailcow.email</a></li> <li><strong>MTA-STS Setup:</strong> <a rel="noopener external" target="_blank" href="https://docs.mailcow.email/">docs.mailcow.email</a></li> </ul> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;www.mail-tester.com&#x2F;" class="retro-button"> <span class="emoji">🛡️</span><span class="button-text">TEST YOUR EMAIL SCORE</span> </a> Deploying the Nextcloud Talk High-Performance Backend with Docker Sun, 21 Sep 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/nextcloud-talk-high-performance-backend/ https://criticalbasics.xyz/posts/nextcloud-talk-high-performance-backend/ <p>This guide will walk you through deploying the official Nextcloud Talk High-Performance Backend (HPBE). This backend, which includes a signaling server (Spreed), a STUN/TURN server (Coturn), and a WebRTC MCU (Janus), significantly improves the performance and reliability of video calls, especially for multiple participants.</p> <p>This setup is designed to integrate seamlessly with an existing Traefik v3 reverse proxy, making it a powerful addition to your self-hosted infrastructure.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-09-21</td><td><strong>Initial Version:</strong> Guide created, focusing on Docker Compose deployment and Traefik v3 integration.</td></tr> </tbody></table> </div> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>This guide is part of a series and builds upon a secure Docker environment. Before you begin, you must have a fully functional Traefik v3 and CrowdSec stack.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ HARD REQUIREMENT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The following steps will not work correctly without the Traefik stack running as described in the prerequisite guide.</p> <ul> <li><strong><a href="../traefik-v3-crowdsec-tutorial/">Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack</a></strong>: This is the foundation for our reverse proxy and security.</li> </ul> </td> </tr> </table> <p>You will also need:</p> <ul> <li>Docker and Docker Compose installed on your server.</li> <li>A dedicated subdomain for the signaling server (e.g., <code>signaling.your-domain.com</code>) pointed to your server’s IP address.</li> <li><code>sudo</code> or root access.</li> <li>The <code>git</code> utility installed (<code>sudo apt install git</code>).</li> <li>Firewall ports <code>80</code>, <code>443</code>, <code>3478/tcp</code>, <code>3478/udp</code> open. The ports <code>3478</code> are required by the Coturn (TURN) server.</li> </ul> <h3 id="1-1-firewall-configuration-ufw-example">1.1. Firewall Configuration (UFW Example)</h3> <p>If you are using <code>ufw</code> (Uncomplicated Firewall), you can open the required ports with the following commands:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 3478/tcp</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 3478/udp</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Example with media range 20000–20100 (choose any suitable range)</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 20000:20100/udp</span><span style="color: #6A737D;"> # match your Janus media range</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Only if you enable TURNS (section 3.4):</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 5349/tcp</span><span style="color: #6A737D;"> # required for TURNS</span></span> <span class="giallo-l"><span style="color: #6A737D;"># sudo ufw allow 5349/udp # optional; enable only if you need UDP on 5349</span></span></code></pre> <p>Note: Choose a media port range that is allowed by your provider/network. The exact same range must be configured in both <code>docker-compose.yml</code> (Janus service <code>ports</code>) and <code>janus/janus.jcfg</code> (media min/max).</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ SECURITY NOTE &amp; CROWDSEC INTEGRATION </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The TURN ports (<code>3478</code>) are exposed directly and are not protected by the Traefik CrowdSec Bouncer. Securing them should be done at the host level.</p> <p>For advanced protection against abuse (e.g., brute-force attacks on the TURN server), you can feed Coturn’s logs into CrowdSec. This is achieved by configuring Docker’s logging driver for the <code>coturn</code> service and telling CrowdSec where to find these logs.</p> <ol> <li> <p><strong>Configure CrowdSec to read Docker logs:</strong> Open the acquisition file from the prerequisite guide and append the following YAML document. This tells CrowdSec to read the logs for the container named <code>coturn</code>.</p> <p>File to edit: <code>/opt/containers/traefik-stack/crowdsec/config/acquis.yaml</code></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #B392F0;">---</span></span> <span class="giallo-l"><span style="color: #85E89D;">source</span><span>:</span><span style="color: #9ECBFF;"> docker</span></span> <span class="giallo-l"><span style="color: #85E89D;">container_name_regexp</span><span>:</span></span> <span class="giallo-l"><span> -</span><span style="color: #9ECBFF;"> ^coturn$</span></span> <span class="giallo-l"><span style="color: #85E89D;">labels</span><span>:</span></span> <span class="giallo-l"><span style="color: #85E89D;"> type</span><span>:</span><span style="color: #9ECBFF;"> coturn</span></span></code></pre></li> <li> <p><strong>Restart CrowdSec:</strong> For the new acquisition configuration to take effect, restart the CrowdSec container in your Traefik stack.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Navigate to your Traefik stack directory and restart only CrowdSec</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/traefik-stack</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose restart crowdsec</span></span></code></pre></li> </ol> <p>CrowdSec will now automatically parse the logs for the <code>coturn</code> container. The <code>coturn</code> service in <code>docker-compose.yml</code> should also be configured with a logging driver to enable log rotation.</p> <p>If you use the CrowdSec Firewall Bouncer (iptables/nftables), ensure the Janus media UDP range (e.g., <code>20000–20100/udp</code>), Coturn relay range (<code>30000–30100/udp</code>), and TURN ports (<code>3478/tcp</code>, <code>3478/udp</code> and, if enabled, <code>5349/tcp</code> [required], <code>5349/udp</code> [optional]) are explicitly allowed and not blocked by bouncer rules.</p> </td> </tr> </table> <h3 id="1-2-resource-planning">1.2. Resource Planning</h3> <p>The High-Performance Backend, especially the Janus MCU, can be resource-intensive during video calls. For a small group of users (e.g., 3-5 concurrent participants in a call), plan for at least <strong>1-2 dedicated CPU cores and 2-4 GB of RAM</strong> for the HPBE stack. For larger deployments, monitor your resource usage and scale accordingly. To keep an eye on performance, regularly check resource usage with tools like <code>htop</code>, <code>docker stats</code>, or a more comprehensive monitoring stack like Prometheus and Grafana.</p> <h2 id="2-directory-structure-and-download">2. Directory Structure and Download</h2> <p>First, we will clone the official repository, which contains all the necessary Docker configurations.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Navigate to your main containers directory</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Clone the repository</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> git clone https://github.com/strukturag/nextcloud-spreed-signaling.git nextcloud-hpbe</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Enter the new directory</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> nextcloud-hpbe</span></span></code></pre><h2 id="3-configuration-files">3. Configuration Files</h2> <p>This setup uses two main configuration files: <code>docker-compose.yml</code> for defining the services and <code>server.conf</code> for the signaling server itself. All configuration values will be hardcoded directly into these files for simplicity and clarity.</p> <h3 id="3-1-docker-compose-file-docker-compose-yml">3.1. Docker Compose File (<code>docker-compose.yml</code>)</h3> <p>Create the <code>docker-compose.yml</code> file. This version uses a hardcoded configuration and is optimized for Traefik v3.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee docker-compose.yml</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">services:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> spreedbackend:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> build:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> context: .</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> dockerfile: docker/server/Dockerfile</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> platforms:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;linux/amd64&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: spreedbackend</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> depends_on:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - nats</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - janus</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - coturn</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./server.conf:/config/server.conf:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - proxy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> labels:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.docker.network=proxy&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Router for certificate acquisition (Host-only rule)</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.hpbe-cert.rule=Host(`signaling.your-domain.com`)&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.hpbe-cert.entrypoints=web,websecure&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.hpbe-cert.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.hpbe-cert.priority=1&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Router for the actual service (Host + Path rule)</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.hpbe.rule=Host(`signaling.your-domain.com`) &amp;&amp; PathPrefix(`/standalone-signaling`)&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.hpbe.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.hpbe.tls=true&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.hpbe.priority=100&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Middlewares: Set X-Forwarded-Proto and strip the path prefix</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.middlewares.hpbe-headers.headers.customRequestHeaders.X-Forwarded-Proto=https&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.middlewares.hpbe-strip.stripprefix.prefixes=/standalone-signaling&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.hpbe.middlewares=hpbe-headers@docker,hpbe-strip@docker,crowdsec-bouncer@docker&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Internal service port</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.services.hpbe.loadbalancer.server.port=8080&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> nats:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: nats:2.10</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: nats</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> command: [&quot;-c&quot;, &quot;/config/gnatsd.conf&quot;]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - type: bind</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> source: ./gnatsd.conf</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> target: /config/gnatsd.conf</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> read_only: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - proxy</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> janus:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Build Janus from source using the provided Dockerfile</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> build: docker/janus</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: janus</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> command: [&quot;janus&quot;, &quot;--full-trickle&quot;]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - proxy</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ports:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;20000-20100:20000-20100/udp&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Optional only if you enabled ice_tcp=true (see section 3.3)</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # - &quot;20000-20100:20000-20100/tcp&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./janus/janus.jcfg:/usr/local/etc/janus/janus.jcfg:ro</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> coturn:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: coturn/coturn:4.6</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: coturn</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> logging:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> driver: &quot;json-file&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> options:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> max-size: &quot;10m&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> max-file: &quot;3&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> command:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;--realm&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;signaling.your-domain.com&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;--static-auth-secret&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;PASTE-A-STRONG-RANDOM-32-CHAR-HEX-SECRET-HERE&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;--no-stdout-log&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;--log-file&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;stdout&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;--stale-nonce=600&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;--use-auth-secret&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Using shared-secret auth only; lt-cred-mech omitted to avoid mixed-auth warning</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;--fingerprint&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;--no-software-attribute&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;--no-multicast-peers&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;--min-port&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;30000&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;--max-port&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;30100&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;--cert&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;/certs/fullchain.pem&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;--pkey&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;/certs/privkey.pem&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;--tls-listening-port&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;5349&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ports:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;3478:3478/tcp&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;3478:3478/udp&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;5349:5349/tcp&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;5349:5349/udp&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;30000-30100:30000-30100/udp&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./certs:/certs:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> external: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre> <p>Note: Before launching, create <code>janus/janus.jcfg</code> as described in section 3.3 (set <code>nat_1_1_mapping</code> and the <code>min_port</code>/<code>max_port</code> media port range).</p> <p>Note: On hosts with a direct public IP, you typically do not need to set Coturn’s <code>--listening-ip</code>, <code>--relay-ip</code>, or <code>--external-ip</code>. Relying on defaults avoids common binding errors (e.g., “Cannot assign requested address”, errno=99). Only set <code>--external-ip PUBLIC_IP/PRIVATE_HOST_IP</code> (and optionally <code>--listening-ip</code>/<code>--relay-ip</code> to the private host IP) if your host is behind NAT.</p> <h3 id="3-2-signaling-server-config-server-conf">3.2. Signaling Server Config (<code>server.conf</code>)</h3> <p>This file configures the core logic of the HPBE. Create <code>server.conf</code>, paste the template below, and replace the placeholder values with your own secrets and URLs.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee server.conf</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">[http]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">listen = 0.0.0.0:8080</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">[app]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">debug = false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">[sessions]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Use &#39;openssl rand -base64 16&#39; to generate these</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">hashkey = PASTE-A-RANDOM-BASE64-KEY-HERE</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">blockkey = PASTE-A-RANDOM-BASE64-KEY-HERE</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">[backend]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">backends = backend-1 #, backend-2</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">allowall = false</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">timeout = 10</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">connectionsperhost = 8</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">[backend-1]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">url = https://cloud.your-domain.com</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Use &#39;openssl rand -hex 16&#39; to generate this</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">secret = PASTE-A-RANDOM-HEX-SECRET-HERE</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"># To add a second backend, add it to the &#39;backends&#39; list and create a new section</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># [backend-2]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># url = https://another-cloud.com</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># secret = PASTE-ANOTHER-RANDOM-HEX-SECRET-HERE</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">[nats]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">url = nats://nats:4222</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">[mcu]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">type = janus</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">url = ws://janus:8188</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">[turn]</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># Use &#39;openssl rand -base64 16&#39; to generate this</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">apikey = PASTE-A-RANDOM-BASE64-KEY-HERE</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"># This secret MUST be identical to the &#39;--static-auth-secret&#39; in docker-compose.yml</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">secret = PASTE-THE-SAME-STRONG-SECRET-AS-IN-DOCKER-COMPOSE</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">servers = turn:signaling.your-domain.com:3478?transport=udp,turn:signaling.your-domain.com:3478?transport=tcp</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ SYNCHRONIZE TURN SECRET </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The <code>secret</code> in the <code>[turn]</code> section of this file <strong>must</strong> be identical to the <code>--static-auth-secret</code> value used in the <code>coturn</code> service in your <code>docker-compose.yml</code> file.</p> </td> </tr> </table> <p>Ensure the file has the correct permissions: <code>sudo chmod 644 server.conf</code>.</p> <h3 id="3-2-1-replace-placeholders-and-generate-secrets">3.2.1 Replace placeholders and generate secrets</h3> <p>Before launching, perform these steps so your setup works on your domain and with strong secrets.</p> <ol> <li>Replace the domain placeholder</li> </ol> <p>We use <code>signaling.your-domain.com</code> as a placeholder. Replace it with your real domain in both files:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/nextcloud-hpbe</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> sed</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> &#39;s/signaling\.your-domain\.com/signaling.example.com/g&#39; docker-compose.yml server.conf</span></span></code></pre> <p>Replace <code>signaling.example.com</code> with your actual TURN/signaling domain.</p> <ol start="2"> <li>Generate the required secrets with openssl</li> </ol> <ul> <li>Sessions keys (base64) for <code>server.conf</code> <code>[sessions]</code>:</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">openssl</span><span style="color: #9ECBFF;"> rand</span><span style="color: #79B8FF;"> -base64 16</span><span style="color: #6A737D;"> # paste as sessions.hashkey</span></span> <span class="giallo-l"><span style="color: #B392F0;">openssl</span><span style="color: #9ECBFF;"> rand</span><span style="color: #79B8FF;"> -base64 16</span><span style="color: #6A737D;"> # paste as sessions.blockkey</span></span></code></pre> <ul> <li>Backend shared secret (hex) for each Nextcloud in <code>server.conf</code> <code>[backend-*]</code>:</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">openssl</span><span style="color: #9ECBFF;"> rand</span><span style="color: #79B8FF;"> -hex 16</span><span style="color: #6A737D;"> # paste as backend-1.secret (and for backend-2, backend-3, ...)</span></span></code></pre> <ul> <li>TURN API key (base64) for <code>server.conf</code> <code>[turn] apikey</code>:</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">openssl</span><span style="color: #9ECBFF;"> rand</span><span style="color: #79B8FF;"> -base64 16</span><span style="color: #6A737D;"> # paste as turn.apikey</span></span></code></pre> <ul> <li>TURN static secret (hex) used in BOTH places: <ul> <li><code>server.conf</code> <code>[turn] secret</code></li> <li>docker-compose <code>coturn</code> command <code>--static-auth-secret</code></li> </ul> </li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">openssl</span><span style="color: #9ECBFF;"> rand</span><span style="color: #79B8FF;"> -hex 16</span><span style="color: #6A737D;"> # paste into both places, values must be identical</span></span></code></pre> <ol start="3"> <li>Open firewall ports (host level)</li> </ol> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 3478/tcp</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 3478/udp</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 20000:20100/udp</span><span style="color: #6A737D;"> # Janus media range</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 30000:30100/udp</span><span style="color: #6A737D;"> # Coturn relay range</span></span> <span class="giallo-l"><span style="color: #6A737D;"># The main docker-compose includes TURNS by default:</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 5349/tcp</span><span style="color: #6A737D;"> # required for TURNS</span></span> <span class="giallo-l"><span style="color: #6A737D;"># sudo ufw allow 5349/udp # optional; some clients might use it</span></span></code></pre><h3 id="3-2-2-example-multiple-nextcloud-backends">3.2.2 Example: Multiple Nextcloud backends</h3> <p>If you operate more than one Nextcloud that should use the same signaling backend, model your <code>[backend]</code> section like this. Replace the example domains and secrets with your own.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #B392F0;">[backend]</span></span> <span class="giallo-l"><span style="color: #F97583;">backends</span><span> = backend-1, backend-2, backend-3</span></span> <span class="giallo-l"><span style="color: #F97583;">allowall</span><span> = false</span></span> <span class="giallo-l"><span style="color: #F97583;">timeout</span><span> = 10</span></span> <span class="giallo-l"><span style="color: #F97583;">connectionsperhost</span><span> = 8</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">[backend-1]</span></span> <span class="giallo-l"><span style="color: #F97583;">url</span><span> = https://cloud1.example.com</span></span> <span class="giallo-l"><span style="color: #F97583;">secret</span><span> = PASTE-A-RANDOM-HEX-SECRET-HERE</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">[backend-2]</span></span> <span class="giallo-l"><span style="color: #F97583;">url</span><span> = https://cloud2.example.com</span></span> <span class="giallo-l"><span style="color: #F97583;">secret</span><span> = PASTE-A-RANDOM-HEX-SECRET-HERE</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">[backend-3]</span></span> <span class="giallo-l"><span style="color: #F97583;">url</span><span> = https://cloud3.example.com</span></span> <span class="giallo-l"><span style="color: #F97583;">secret</span><span> = PASTE-A-RANDOM-HEX-SECRET-HERE</span></span></code></pre> <p>Note: The <code>secret</code> for each backend must match the “Shared secret” you configure in that specific Nextcloud under Admin -&gt; Talk.</p> <h4 id="3-2-3-optional-bind-the-http-listener-to-the-service-name">3.2.3 Optional: Bind the HTTP listener to the service name</h4> <p>By default this guide uses <code>listen = 0.0.0.0:8080</code> in <code>[http]</code>, which is simple and works well behind Traefik. If you prefer to bind strictly to the Docker service name, you can set:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #B392F0;">[http]</span></span> <span class="giallo-l"><span style="color: #F97583;">listen</span><span> = spreedbackend:8080</span></span></code></pre> <p>Both are valid in a single Docker network; choose the variant that fits your operational preference.</p> <h3 id="3-3-janus-nat-and-media-ports-required-for-working-audio-video">3.3. Janus NAT and Media Ports (required for working audio/video)</h3> <p>WebRTC media flows (DTLS/SRTP) are carried on a dynamic UDP port range on the Janus SFU. If these ports are not reachable from the internet, calls will not establish and you will see errors like “publisher not sending yet” or repeated “requestoffer: context deadline exceeded” in the signaling logs.</p> <p>Do the following:</p> <ol> <li>Create a minimal Janus config that sets public IP mapping and a fixed media port range</li> </ol> <p>Create <code>./janus/janus.jcfg</code> with the following content. Replace <code>PUBLIC.IP.OR.DNS</code> with your server’s public address or a DNS name that resolves to it (no CDN/Orange-Cloud in front):</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #6A737D;"># Minimal but complete Janus config for operation behind Docker</span></span> <span class="giallo-l"><span style="color: #6A737D;"># with a fixed UDP port range and correct 1:1 NAT mapping.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>general: {</span></span> <span class="giallo-l"><span style="color: #F97583;"> configs_folder</span><span> =</span><span style="color: #9ECBFF;"> &quot;/usr/local/etc/janus&quot;</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Keep logging at &quot;info&quot; (default), set &quot;debug = true&quot; if needed</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>at: {</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Important: public IP or DNS of the host that clients should see</span></span> <span class="giallo-l"><span style="color: #F97583;"> nat_1_1_mapping</span><span> =</span><span style="color: #9ECBFF;"> &quot;signaling.your-domain.com&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # SRFLX candidates (optional, but doesn&#39;t hurt)</span></span> <span class="giallo-l"><span style="color: #F97583;"> stun_server</span><span> =</span><span style="color: #9ECBFF;"> &quot;signaling.your-domain.com&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> stun_port</span><span> = 3478</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # ICE Lite is fine for SFU operation and reduces complexity</span></span> <span class="giallo-l"><span style="color: #F97583;"> ice_lite</span><span> = true</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>media: {</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Fixed, small port range: must match docker-compose (ports:)</span></span> <span class="giallo-l"><span style="color: #F97583;"> min_port</span><span> = 20000</span></span> <span class="giallo-l"><span style="color: #F97583;"> max_port</span><span> = 20100</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # Prefer UDP (TCP disabled as it&#39;s often problematic/unnecessary)</span></span> <span class="giallo-l"><span style="color: #F97583;"> ice_tcp</span><span> = false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # (Optional) Enforce RTCP-MUX – common default, can help</span></span> <span class="giallo-l"><span style="color: #F97583;"> rtcp_mux</span><span> = true</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Websockets (HPBE communicates internally via ws://janus:8188)</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Defaults are fine, no extra port publishing needed as it&#39;s in the same Docker network.</span></span> <span class="giallo-l"><span>websockets: {</span></span> <span class="giallo-l"><span style="color: #F97583;"> ws</span><span> = true</span></span> <span class="giallo-l"><span style="color: #F97583;"> ws_port</span><span> = 8188</span></span> <span class="giallo-l"><span style="color: #F97583;"> ws_interface</span><span> =</span><span style="color: #9ECBFF;"> &quot;0.0.0.0&quot;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># REST &amp; Admin disabled by default – not needed</span></span> <span class="giallo-l"><span>admin: {</span></span> <span class="giallo-l"><span style="color: #F97583;"> admin_http</span><span> = false</span></span> <span class="giallo-l"><span style="color: #F97583;"> admin_secret</span><span> =</span><span style="color: #9ECBFF;"> &quot;changeit&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ol start="2"> <li>Ensure your main docker-compose includes the Janus media ports and config mount</li> </ol> <p>In section 3.1, the <code>janus</code> service already contains the required <code>ports</code> and <code>volumes</code> lines. Verify that your configuration matches:</p> <ul> <li><code>ports: "20000-20100:20000-20100/udp"</code> (optional TCP only if <code>ice_tcp=true</code>)</li> <li><code>volumes: ./janus/janus.jcfg:/usr/local/etc/janus/janus.jcfg:ro</code></li> </ul> <ol start="3"> <li>Open the firewall for the media range (host level)</li> </ol> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 20000:20100/udp</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Adjust to the exact range you configured in janus.jcfg and docker-compose</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Only if you enabled ice_tcp=true</span></span> <span class="giallo-l"><span style="color: #6A737D;"># sudo ufw allow 20000:20100/tcp</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ CAPACITY PLANNING FOR MEDIA PORTS </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>With RTCP-MUX/BUNDLE (Janus default), each active PeerConnection typically uses about one UDP port on the server.</p> <ul> <li>Plan roughly 1 port per active participant (conservatively 2 if features like separate screen-share/recording open additional PeerConnections).</li> <li>Examples (illustrative): <ul> <li>Range 40000–40050 (51 ports) → about 25–50 concurrent PeerConnections (small groups).</li> <li>Range 40000–40199 (200 ports) → more headroom for spikes and larger meetings.</li> </ul> </li> <li>Always match your firewall (UFW) and CrowdSec rules to the same UDP range you configured in <code>janus.jcfg</code> and in the <code>janus</code> service <code>ports</code>. The above examples use 40000-based ranges; choose the range you actually configured (e.g., 20000–20100).</li> </ul> </td> </tr> </table> <ol start="4"> <li>Apply the changes</li> </ol> <ul> <li>If you have not launched the stack yet, skip this step. The changes will take effect when you start the stack in section 4.</li> <li>If Janus is already running, apply the updated config now:</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose up</span><span style="color: #79B8FF;"> -d --force-recreate</span><span style="color: #9ECBFF;"> janus</span></span></code></pre> <ol start="5"> <li>Verify during a call attempt</li> </ol> <ul> <li>In Firefox <code>about:webrtc</code> or Chrome <code>chrome://webrtc-internals</code> check that the remote ICE candidates from Janus show your public IP with ports in <code>20000–20100</code> and that the ICE state becomes <code>connected/completed</code>.</li> <li>On the server, you should see traffic on those ports while a call is setting up:</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tcpdump</span><span style="color: #79B8FF;"> -ni</span><span style="color: #9ECBFF;"> any udp port</span><span style="color: #79B8FF;"> 3478</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tcpdump</span><span style="color: #79B8FF;"> -ni</span><span style="color: #9ECBFF;"> any udp portrange 20000-20100</span></span></code></pre> <p>If you exclusively rely on shared-secret auth for TURN, you can still keep section 3.4 (TURNS) as-is; TURN helps with client NAT traversal but cannot replace opening Janus’ own media ports.</p> <h3 id="3-4-enable-turn-over-tls-5349">3.4. Enable TURN over TLS (5349)</h3> <p>Enabling <code>turns:</code> adds TLS encryption to TURN traffic on port <code>5349</code>. This often helps in restrictive networks and hides credentials from passive observers.</p> <p>Steps:</p> <ol> <li>Create the certs directory and export PEMs from Traefik’s ACME store</li> </ol> <p>Since this guide builds on the prerequisite <a href="../traefik-v3-crowdsec-tutorial/">Traefik v3 and CrowdSec tutorial</a>, your certificates are stored in Traefik’s ACME database at <code>/opt/containers/traefik-stack/traefik/certs/acme.json</code>. Export the certificate and key for your TURN domain into <code>./certs</code>.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/nextcloud-hpbe</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Domain used for TURN/TURNS (anonymized placeholder)</span></span> <span class="giallo-l"><span>TURN_DOMAIN</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;signaling.your-domain.com&quot;</span></span> <span class="giallo-l"><span>ACME</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;/opt/containers/traefik-stack/traefik/certs/acme.json&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Ensure tools are available</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt-get update</span><span> &amp;&amp;</span><span style="color: #B392F0;"> sudo</span><span style="color: #9ECBFF;"> apt-get install</span><span style="color: #79B8FF;"> -y</span><span style="color: #9ECBFF;"> jq</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Create output directory</span></span> <span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ./certs</span></span> <span class="giallo-l"><span style="color: #6A737D;"># (Directory permissions are set in step 1.1 below)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Extract certificate and key for the TURN domain from acme.json</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> jq</span><span style="color: #79B8FF;"> -r --arg</span><span style="color: #9ECBFF;"> d &quot;</span><span>$TURN_DOMAIN</span><span style="color: #9ECBFF;">&quot; &#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> .. | objects</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> | select(has(&quot;domain&quot;) and (.domain.main==$d or ((.domain.sans // []) | index($d))))</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> | .certificate</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&#39; &quot;</span><span>$ACME</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> base64</span><span style="color: #79B8FF;"> -d</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sudo</span><span style="color: #9ECBFF;"> tee ./certs/fullchain.pem</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> jq</span><span style="color: #79B8FF;"> -r --arg</span><span style="color: #9ECBFF;"> d &quot;</span><span>$TURN_DOMAIN</span><span style="color: #9ECBFF;">&quot; &#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> .. | objects</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> | select(has(&quot;domain&quot;) and (.domain.main==$d or ((.domain.sans // []) | index($d))))</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> | .key</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&#39; &quot;</span><span>$ACME</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> base64</span><span style="color: #79B8FF;"> -d</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sudo</span><span style="color: #9ECBFF;"> tee ./certs/privkey.pem</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span></span></code></pre> <p>Note: The certificate must match the TURN realm/domain you advertise (e.g., <code>signaling.your-domain.com</code>).</p> <p>1.1 Set Certificate and Directory Permissions</p> <p>Coturn does not run as root inside the container, but as the <code>nobody:nogroup</code> user. Without the correct permissions on both the directory and the files, Coturn cannot read the certificates and the <code>turns:</code> connection will fail (often shown as red in Nextcloud Talk).</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># In your project directory (e.g., /opt/containers/nextcloud-hpbe)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Detect the group ID used by Coturn inside the container (commonly 65534 for &#39;nogroup&#39;)</span></span> <span class="giallo-l"><span>GID</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose exec</span><span style="color: #79B8FF;"> -T</span><span style="color: #9ECBFF;"> coturn sh</span><span style="color: #79B8FF;"> -c</span><span style="color: #9ECBFF;"> &#39;id -g&#39;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> tr</span><span style="color: #79B8FF;"> -d</span><span style="color: #9ECBFF;"> &#39;\r&#39;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Ensure the certs directory is accessible to that group</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> chgrp &quot;</span><span>$GID</span><span style="color: #9ECBFF;">&quot; ./certs</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> chmod</span><span style="color: #79B8FF;"> 750</span><span style="color: #9ECBFF;"> ./certs</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Set group ownership and restrictive permissions on the files</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> chgrp &quot;</span><span>$GID</span><span style="color: #9ECBFF;">&quot; ./certs/privkey.pem ./certs/fullchain.pem</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> chmod</span><span style="color: #79B8FF;"> 640</span><span style="color: #9ECBFF;"> ./certs/privkey.pem</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> chmod</span><span style="color: #79B8FF;"> 644</span><span style="color: #9ECBFF;"> ./certs/fullchain.pem</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Restart Coturn to load the updated certificates</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose up</span><span style="color: #79B8FF;"> -d --force-recreate</span><span style="color: #9ECBFF;"> coturn</span></span></code></pre> <p>Note: If your image uses the default <code>nobody:nogroup</code>, you may alternatively use <code>sudo chgrp nogroup ...</code> instead of the detected GID.</p> <ol start="2"> <li>TLS is already configured in the main <code>docker-compose.yml</code> in this guide. After creating/exporting the certificates in step 1, simply recreate Coturn so it picks up the TLS files.</li> </ol> <p>Note: If you exclusively use shared-secret auth (<code>--use-auth-secret</code> with <code>--static-auth-secret</code>), you can omit <code>--lt-cred-mech</code> to avoid a warning.</p> <ol start="3"> <li>Update your <code>server.conf</code> <code>servers</code> list to include the <code>turns:</code> endpoint:</li> </ol> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #B392F0;">[turn]</span></span> <span class="giallo-l"><span style="color: #F97583;">servers</span><span> = turn:signaling.your-domain.com:3478?</span><span style="color: #F97583;">transport</span><span>=udp,turn:signaling.your-domain.com:3478?</span><span style="color: #F97583;">transport</span><span>=tcp,turns:signaling.your-domain.com:5349?</span><span style="color: #F97583;">transport</span><span>=tcp</span></span></code></pre> <ol start="4"> <li>Open the firewall for port <code>5349</code>:</li> </ol> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> ufw allow 5349/tcp</span><span style="color: #6A737D;"> # required for TURNS</span></span> <span class="giallo-l"><span style="color: #6A737D;"># sudo ufw allow 5349/udp # optional; enable only if you need UDP on 5349</span></span></code></pre><h2 id="4-launch-the-stack">4. Launch the Stack</h2> <p>With the configuration complete, you can now build and start the services.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># From within the /opt/containers/nextcloud-hpbe directory</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose up</span><span style="color: #79B8FF;"> --build -d</span></span></code></pre> <p>The <code>--build</code> flag is important because it builds the Janus and the <code>spreedbackend</code> images from their Dockerfiles. The Janus build, in particular, can take several minutes.</p> <p>You can monitor the logs to ensure everything starts correctly:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose logs</span><span style="color: #79B8FF;"> -f</span></span></code></pre><h3 id="4-1-verify-turn-turns-endpoints">4.1 Verify TURN/TURNS endpoints</h3> <p>If <code>nc</code> is not installed, install it first:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt-get update</span><span> &amp;&amp;</span><span style="color: #B392F0;"> sudo</span><span style="color: #9ECBFF;"> apt-get install</span><span style="color: #79B8FF;"> -y</span><span style="color: #9ECBFF;"> netcat-openbsd</span></span></code></pre> <p>Run these quick checks from a client or your server to verify connectivity:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># 1) Check TCP reachability (expect &quot;succeeded&quot;)</span></span> <span class="giallo-l"><span style="color: #B392F0;">nc</span><span style="color: #79B8FF;"> -vz</span><span style="color: #9ECBFF;"> signaling.your-domain.com</span><span style="color: #79B8FF;"> 3478</span></span> <span class="giallo-l"><span style="color: #B392F0;">nc</span><span style="color: #79B8FF;"> -vz</span><span style="color: #9ECBFF;"> signaling.your-domain.com</span><span style="color: #79B8FF;"> 5349</span><span style="color: #6A737D;"> # only if TURNS enabled</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 2) Verify TLS on 5349 (should show certificate details; only if TURNS is enabled)</span></span> <span class="giallo-l"><span style="color: #B392F0;">openssl</span><span style="color: #9ECBFF;"> s_client</span><span style="color: #79B8FF;"> -connect</span><span style="color: #9ECBFF;"> signaling.your-domain.com:5349</span><span style="color: #79B8FF;"> -servername</span><span style="color: #9ECBFF;"> signaling.your-domain.com</span><span style="color: #79B8FF;"> -brief</span><span style="color: #F97583;"> &lt;</span><span style="color: #9ECBFF;"> /dev/null</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 3) Check Coturn runtime logs</span></span> <span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose logs</span><span style="color: #79B8FF;"> -f</span><span style="color: #9ECBFF;"> coturn</span></span></code></pre> <p>If you have <code>turnutils_uclient</code> available (from the coturn package), you can perform an end-to-end TURN allocation test as an advanced check.</p> <h2 id="5-configure-nextcloud">5. Configure Nextcloud</h2> <p>The final step is to tell your Nextcloud instance to use the new High-Performance Backend.</p> <ol> <li>Log in to Nextcloud as an administrator.</li> <li>Navigate to <strong>Administration Settings</strong> -&gt; <strong>Talk</strong>.</li> <li>Scroll down to the “Signaling server” section.</li> <li>Check “Enable custom signaling server”.</li> <li>In the “Signaling server URL” field, enter the full path to your HPBE: <code>https://signaling.your-domain.com/standalone-signaling</code>.</li> <li>In the “Shared secret” field, paste the corresponding shared secret for this specific Nextcloud instance (e.g., the value of <code>NEXTCLOUD_1_SHARED_SECRET</code> for your first instance).</li> <li>Click “Save changes”.</li> </ol> <p>Nextcloud will verify the connection. If everything is correct, you’re all set!</p> <h3 id="clarifying-secret-mappings">Clarifying Secret Mappings</h3> <p>To ensure all components communicate securely, it’s crucial to map the secrets correctly. Here is a quick reference:</p> <table><thead><tr><th><code>server.conf</code> Section &amp; Key</th><th>Maps to…</th><th>Purpose</th></tr></thead><tbody> <tr><td><code>[backend]</code> -&gt; <code>secret</code></td><td>Nextcloud Admin -&gt; Talk -&gt; <strong>Shared secret</strong></td><td>Authenticates Nextcloud with the signaling server.</td></tr> <tr><td><code>[turn]</code> -&gt; <code>apikey</code></td><td>Used by the signaling server to generate time-limited TURN credentials for clients. Janus does not use this key in this setup.</td><td>Allows signaling server to get TURN credentials.</td></tr> <tr><td><code>[turn]</code> -&gt; <code>secret</code></td><td><code>coturn</code> service -&gt; <code>--static-auth-secret</code> command argument</td><td>Authenticates TURN users (generated by signaling).</td></tr> </tbody></table> <h2 id="6-troubleshooting-monitoring">6. Troubleshooting &amp; Monitoring</h2> <p>If you encounter issues, here are a few steps to diagnose the problem:</p> <ol> <li> <p><strong>Verify the Signaling Server is Reachable</strong></p> <p>You should get a <code>200 OK</code> response from the <code>/welcome</code> endpoint. This confirms that Traefik is routing requests correctly.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> https://signaling.your-domain.com/standalone-signaling/api/v1/welcome</span></span></code></pre></li> <li> <p><strong>Check the Container Logs</strong></p> <p>The logs are the best source for identifying errors. Pay close attention to messages about secrets, WebSocket connections, or backend timeouts.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># From within the /opt/containers/nextcloud-hpbe directory</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose logs</span><span style="color: #79B8FF;"> -f</span></span></code></pre></li> <li> <p><strong>Common Errors &amp; Fixes</strong></p> <ul> <li><strong><code>ERROR: the sessions block key must be...</code> or <code>hash key should be...</code></strong>: This error occurs when the keys in <code>server.conf</code> are missing or have the wrong format. Use <code>openssl rand -base64 16</code> to generate new keys and paste them into the <code>[sessions]</code> section.</li> <li><strong>TURN Secret Mismatch</strong>: If calls fail to connect, verify that the <code>secret</code> in the <code>[turn]</code> section of <code>server.conf</code> is <strong>exactly</strong> the same as the <code>--static-auth-secret</code> in the <code>coturn</code> command in <code>docker-compose.yml</code>.</li> <li><strong>“failed to establish signaling connection”</strong>: This is a classic error. <ul> <li>Check that the URL in Nextcloud is exactly <code>https://.../standalone-signaling</code>.</li> <li>Ensure your Traefik labels are correct (especially the <code>PathPrefix</code> and <code>stripPrefix</code> rules).</li> <li>Verify that the <code>Shared secret</code> in Nextcloud matches the one in <code>server.conf</code>.</li> <li>Media range not reachable: If ICE repeatedly fails or you see “publisher not sending yet”, ensure your chosen Janus media port range is open end-to-end (firewall/CrowdSec), and that the exact same range is configured in both <code>docker-compose.yml</code> (Janus <code>ports</code>) and <code>janus/janus.jcfg</code>.</li> </ul> </li> <li><strong>Calls work for 2 people but fail with 3+</strong>: This often points to a problem with Janus (the MCU) or Coturn (the TURN server). Check their logs specifically.</li> <li><strong>No video/audio from external networks</strong>: This is a typical TURN server issue. Ensure ports <code>3478</code> (TCP/UDP) are open on your firewall and correctly forwarded to the Coturn container.</li> <li><strong><code>turn:</code> works, but <code>turns:</code> fails (is red in Nextcloud)</strong>: This is almost always a certificate permission issue. Coturn cannot read the TLS certificate or key. Verify that Coturn can access the files with <code>docker compose exec coturn ls -l /certs</code>. If you see permission errors, re-run the permission-setting steps in section 3.4. You can also test externally with: <code>openssl s_client -connect signal.example.com:5349 -servername signal.example.com</code>.</li> </ul> </li> </ol> <h3 id="6-1-diagnose-ice-rtp-issues-quickly">6.1 Diagnose ICE/RTP issues quickly</h3> <ul> <li><strong>Check remote candidates in the browser</strong>: Use <code>about:webrtc</code> (Firefox) or <code>chrome://webrtc-internals</code> (Chrome). You should see server-reflexive (srflx) and relayed (relay) candidates, and remote candidates from Janus on the public IP in the configured media range.</li> <li><strong>Look for ICE state</strong>: <code>iceConnectionState</code> should reach <code>connected/completed</code>. If it stays in <code>checking/failed</code>, open ports or NAT/public IP mapping are missing.</li> <li><strong>Server-side packet capture</strong>: While attempting a call, run <code>sudo tcpdump -ni any udp portrange 20000-20100</code> to confirm media packets hit the host.</li> <li><strong>TURN sanity</strong>: Use the Trickle ICE demo with your TURN URIs to confirm you get <code>relay</code> candidates; verify your Coturn <code>realm</code> and static secret match the values in <code>server.conf</code> and <code>docker-compose.yml</code>.</li> </ul> <h2 id="7-maintenance-and-updates">7. Maintenance and Updates</h2> <p>Updating the High-Performance Backend involves fetching the latest version while preserving your custom configurations. The recommended method is to back up your current installation, clone the new version, and restore your configuration files. This avoids potential conflicts from a direct <code>git pull</code>.</p> <h3 id="step-1-stop-and-back-up-the-current-installation">Step 1: Stop and Back Up the Current Installation</h3> <p>First, stop the running services and create a backup of your entire <code>nextcloud-hpbe</code> directory.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Navigate to the parent directory of your HPBE installation</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Stop the services using the existing docker-compose file</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose</span><span style="color: #79B8FF;"> -f</span><span style="color: #9ECBFF;"> nextcloud-hpbe/docker-compose.yml down</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Create a backup by renaming the directory</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mv nextcloud-hpbe nextcloud-hpbe_BACKUP</span></span></code></pre><h3 id="step-2-clone-the-new-version">Step 2: Clone the New Version</h3> <p>Clone the latest version of the repository into a clean directory with the original name.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Stay in /opt/containers/</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> git clone https://github.com/strukturag/nextcloud-spreed-signaling.git nextcloud-hpbe</span></span></code></pre><h3 id="step-3-restore-your-configuration">Step 3: Restore Your Configuration</h3> <p>Copy your essential configuration files from the backup into the new directory. This ensures your secrets, domains, and other settings are preserved.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Copy your docker-compose.yml and server.conf</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> cp nextcloud-hpbe_BACKUP/docker-compose.yml nextcloud-hpbe/docker-compose.yml</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> cp nextcloud-hpbe_BACKUP/server.conf nextcloud-hpbe/server.conf</span></span></code></pre><h3 id="step-4-launch-the-updated-stack">Step 4: Launch the Updated Stack</h3> <p>Finally, navigate into the new directory and start the services. The <code>--build</code> flag will create new images if required, and <code>--remove-orphans</code> cleans up any old, unused containers.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Navigate into the new HPBE directory</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> nextcloud-hpbe</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Build and start the updated services</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> docker compose up</span><span style="color: #79B8FF;"> --build -d --remove-orphans</span></span></code></pre> <p>After a few moments, your updated High-Performance Backend will be running. You can optionally remove the backup directory (<code>sudo rm -rf /opt/containers/nextcloud-hpbe_BACKUP</code>) once you have confirmed everything is working correctly.</p> <h2 id="conclusion">Conclusion</h2> <p>Congratulations! You have successfully deployed a Nextcloud Talk High-Performance Backend. Your users will now experience more stable and performant video calls, especially in group settings. This powerful, containerized setup integrates perfectly with a modern Traefik proxy, providing a scalable and secure solution for your communication needs.</p> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;strukturag&#x2F;nextcloud-spreed-signaling" class="retro-button"> <span class="emoji">📚</span><span class="button-text">OFFICIAL HPBE REPOSITORY</span> </a> Deploying a Secure Nginx Website with Traefik and Docker Compose Wed, 17 Sep 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/nginx-webserver/ https://criticalbasics.xyz/posts/nginx-webserver/ <p>This tutorial explains how to deploy a simple and secure Nginx web server using Docker Compose. This setup is designed to run behind an existing Traefik reverse proxy, providing a robust and easily manageable solution for hosting a static website.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-09-17</td><td><strong>Initial Version:</strong> Article created to demonstrate a secure Nginx deployment behind a Traefik v3 stack.</td></tr> </tbody></table> </div> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>This guide builds directly upon a previously established secure Docker environment. Before you begin, you must have a fully functional Traefik v3 and CrowdSec stack.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ CRUCIAL PREREQUISITE </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>This tutorial is part of a series and assumes you have a fully functional Docker environment with Traefik running. You must have already completed the setup described in our previous tutorial:</p> <ul> <li><strong><a href="../traefik_v3_crowdsec_tutorial/">Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack</a></strong>: This is the foundation for our reverse proxy and security.</li> </ul> <p>If you haven’t already created the external network for Traefik, do so now:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> network create proxy</span></span></code></pre> </td> </tr> </table> <p>You will also need:</p> <ul> <li>Docker and Docker Compose installed on your server.</li> <li>A domain name pointed to your server’s IP address.</li> <li><code>sudo</code> or root access.</li> </ul> <h2 id="2-directory-structure">2. Directory Structure</h2> <p>To keep our project organized, we’ll create a dedicated directory for the Nginx service. All subsequent file paths in this guide are relative to this base directory.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Create the main directory for your Nginx site</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> /opt/containers/nginx</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/nginx</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Create subdirectories for configuration and website files</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir conf html</span></span></code></pre> <p>This structure separates your Nginx configuration from your actual website content.</p> <h2 id="3-configuration-files">3. Configuration Files</h2> <p>Next, we will create the necessary configuration files for Nginx and Docker Compose.</p> <h3 id="3-1-environment-file-env">3.1. Environment File (<code>.env</code>)</h3> <p>First, create a <code>.env</code> file to store your domain name. This makes the configuration cleaner and easier to update.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee .env</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">DOMAIN_NAME=your-domain.com</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ IMPORTANT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Replace <code>your-domain.com</code> with your actual domain name.</p> </td> </tr> </table> <h3 id="3-2-docker-compose-file">3.2. Docker Compose File</h3> <p>Now, create the <code>docker-compose.yml</code> file. It will read the <code>DOMAIN_NAME</code> variable from your <code>.env</code> file.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee docker-compose.yml</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">services:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> nginx:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image: nginx:1.27.1</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> container_name: nginx</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> restart: unless-stopped</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> volumes:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./html:/usr/share/nginx/html:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./conf/nginx.conf:/etc/nginx/nginx.conf:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - ./conf/mime.types:/etc/nginx/mime.types:ro</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> labels:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.enable=true&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # --- Routing ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.nginx.rule=Host(`${DOMAIN_NAME}`) || Host(`www.${DOMAIN_NAME}`)&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.nginx.entrypoints=websecure&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.nginx.tls=true&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.nginx.tls.certresolver=tls_resolver&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # --- Middlewares ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # 1. CORS headers for Matrix federation (defined on-the-fly)</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.middlewares.nginx-cors.headers.accessControlAllowMethods=GET,OPTIONS,PUT,POST&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.middlewares.nginx-cors.headers.accessControlAllowHeaders=*&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.middlewares.nginx-cors.headers.accessControlAllowOriginList=*&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> </span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # 2. Assignment of all middlewares</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.routers.nginx.middlewares=security-headers@file,crowdsec-bouncer@docker,nginx-cors@docker&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # --- Service Definition ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - &quot;traefik.http.services.nginx.loadbalancer.server.port=80&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> - proxy</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">networks:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> proxy:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> external: true</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre> <p><strong>Key Points from this file:</strong></p> <ul> <li><strong><code>labels</code></strong>: These are instructions for Traefik. We define routing, TLS, and a chain of middlewares.</li> <li><strong><code>middlewares</code></strong>: We apply three middlewares: <code>security-headers</code> (from a file), <code>crowdsec-bouncer</code> (from the Traefik service’s own labels), and <code>nginx-cors</code>. The <code>nginx-cors</code> middleware is defined on-the-fly here and is <strong>critical for Matrix federation</strong>, as it allows other servers to access the <code>.well-known</code> delegation files. For a standard website without Matrix integration, this middleware and its assignment can be omitted.</li> <li><strong><code>volumes</code></strong>: We mount our local <code>html</code> and <code>conf</code> directories into the container as read-only (<code>ro</code>) for better security.</li> <li><strong><code>networks</code></strong>: The service is attached to the external <code>proxy</code> network, allowing it to communicate with the Traefik container.</li> </ul> <h3 id="3-3-nginx-configuration">3.3. Nginx Configuration</h3> <p>Next, create the main Nginx configuration file at <code>/opt/containers/nginx/conf/nginx.conf</code>. This file controls the behavior of the web server and is optimized for serving a static site with Gzip compression.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee conf/nginx.conf</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">worker_processes 2;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">user www-data;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">events {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> use epoll;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> worker_connections 128;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;">http {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> include /etc/nginx/mime.types;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> default_type application/octet-stream;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # --- Basic Settings ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> sendfile on;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> tcp_nopush on;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> tcp_nodelay on;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> keepalive_timeout 65;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> types_hash_max_size 2048;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # --- Gzip Settings ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> gzip on;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> gzip_disable &quot;msie6&quot;;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> gzip_vary on;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> gzip_proxied any;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> gzip_comp_level 6;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> gzip_buffers 16 8k;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> gzip_http_version 1.1;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # --- Main Server Block ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> server {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> listen 80;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> server_name _;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> root /usr/share/nginx/html;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> index index.html;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> location / {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> try_files $uri $uri/ =404;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # --- Future-Proofing for Matrix Synapse ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> location /.well-known/matrix/server {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> return 200 &#39;{&quot;m.server&quot;: &quot;matrix.YOUR_DOMAIN_COM_PLACEHOLDER:443&quot;}&#39;;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> add_header &quot;Content-Type&quot; &quot;application/json&quot;;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> location /.well-known/matrix/client {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> return 200 &#39;{&quot;m.homeserver&quot;: {&quot;base_url&quot;: &quot;https://matrix.YOUR_DOMAIN_COM_PLACEHOLDER&quot;}, &quot;m.identity_server&quot;: {&quot;base_url&quot;: &quot;https://vector.im&quot;}}&#39;;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> add_header &quot;Content-Type&quot; &quot;application/json; charset=utf-8&quot;;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> add_header &quot;Access-Control-Allow-Origin&quot; &quot;*&quot;;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # --- Error Pages ---</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> error_page 404 /404.html;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> location = /404.html {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> internal;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> error_page 500 502 503 504 /50x.html;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> location = /50x.html {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> internal;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre> <p>Now, read the .env file and use sed to replace the placeholders:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F97583;">export</span><span> $(</span><span style="color: #B392F0;">grep</span><span style="color: #79B8FF;"> -v</span><span style="color: #9ECBFF;"> &#39;^#&#39; .env</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> xargs</span><span>)</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> sed</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> &quot;s/YOUR_DOMAIN_COM_PLACEHOLDER/${</span><span>DOMAIN_NAME</span><span style="color: #9ECBFF;">}/g&quot; conf/nginx.conf</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ PREPARING FOR MATRIX SYNAPSE </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The <code>location /.well-known/matrix</code> blocks are included as a forward-thinking measure. They are required for setting up a federated <strong><a href="../matrix_synapse_server/">Matrix Synapse server</a></strong> on your domain. By including them now, you won’t need to reconfigure this Nginx service when you decide to deploy Matrix later. These directives tell Matrix clients and other servers where to find your chat homeserver.</p> </td> </tr> </table> <h3 id="3-4-mime-types">3.4. Mime Types</h3> <p>Create a <code>mime.types</code> file at <code>/opt/containers/nginx/conf/mime.types</code>. This file ensures that Nginx sends the correct <code>Content-Type</code> header for various file formats, which is particularly important for web fonts and modern web assets.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee conf/mime.types</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">types {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> text/html html htm shtml;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> text/css css;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> text/xml xml;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image/gif gif;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image/jpeg jpeg jpg;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> application/javascript js;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> application/atom+xml atom;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> application/rss+xml rss;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Fonts</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> application/vnd.ms-fontobject eot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> font/truetype ttf;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> font/opentype otf;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> font/woff woff;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> font/woff2 woff2;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image/svg+xml svg svgz;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image/png png;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> image/x-icon ico;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">}</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><h3 id="3-5-website-content">3.5. Website Content</h3> <p>Before launching the server, place your website files into the <code>/opt/containers/nginx/html</code> directory. For a quick test, create a simple <code>index.html</code> file within it.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Create a simple index.html for testing</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee html/index.html</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;!DOCTYPE html&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;html lang=&quot;en&quot;&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;head&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &lt;meta charset=&quot;UTF-8&quot;&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &lt;title&gt;Welcome to My Nginx Site&lt;/title&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &lt;style&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> body { font-family: sans-serif; background-color: #f0f0f0; text-align: center; padding: 50px; }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> h1 { color: #333; }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &lt;/style&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;/head&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;body&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &lt;h1&gt;Success!&lt;/h1&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &lt;p&gt;Your Nginx website is running securely behind Traefik.&lt;/p&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;/body&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;/html&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Create custom error pages</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee html/404.html</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;!DOCTYPE html&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;html lang=&quot;en&quot;&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;head&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &lt;meta charset=&quot;UTF-8&quot;&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &lt;title&gt;404 Not Found&lt;/title&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;/head&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;body&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &lt;h1&gt;404 - Page Not Found&lt;/h1&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &lt;p&gt;The page you are looking for does not exist.&lt;/p&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;/body&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;/html&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> tee html/50x.html</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> /dev/null</span><span style="color: #F97583;"> &lt;&lt;</span><span style="color: #9ECBFF;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;!DOCTYPE html&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;html lang=&quot;en&quot;&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;head&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &lt;meta charset=&quot;UTF-8&quot;&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &lt;title&gt;Server Error&lt;/title&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;/head&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;body&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &lt;h1&gt;50x - Server Error&lt;/h1&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &lt;p&gt;An internal server error occurred.&lt;/p&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;/body&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">&lt;/html&gt;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">EOF</span></span></code></pre><h2 id="5-launch-and-verify">5. Launch and Verify</h2> <p>With all the files in place, you can start your Nginx container. Use <code>docker compose</code> for consistency with the main Traefik stack.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Navigate to your project directory if you aren&#39;t already there</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> /opt/containers/nginx</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Start the service in the background</span></span> <span class="giallo-l"><span style="color: #B392F0;">docker</span><span style="color: #9ECBFF;"> compose up</span><span style="color: #79B8FF;"> -d</span></span></code></pre> <p>You can check the status of your new container with <code>docker compose ps</code>. It should show a state of <code>Up</code>.</p> <p>Now, open a web browser and navigate to <code>https://your-domain.com</code>. You should see the “Success!” message from your <code>index.html</code> file, served over a secure HTTPS connection managed by Traefik.</p> <h2 id="6-conclusion">6. Conclusion</h2> <p>You have successfully deployed a secure, containerized Nginx web server behind your Traefik and CrowdSec stack. This setup not only serves your static content efficiently but also benefits from centralized TLS management, security headers, and threat protection. Furthermore, it is already prepared for future expansion, such as the addition of a <strong><a href="../matrix_synapse_server/">Matrix Synapse server</a></strong>.</p> Secure Server-to-Server File Transfers with rsync and tmux Fri, 08 Aug 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/server-file-transfer-rsync-tmux/ https://criticalbasics.xyz/posts/server-file-transfer-rsync-tmux/ <p>This guide provides a definitive, “terminal-first” approach to transferring large amounts of data directly between two remote servers. By combining the power of <code>rsync</code> for data synchronization, <code>tmux</code> for session persistence, and a securely configured SSH deploy key for authentication, you can create a “fire-and-forget” transfer process that is robust, efficient, and secure.</p> <p>This method avoids routing traffic through your local machine, saving you bandwidth and making the process immune to local network disconnects.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-08-08</td><td><strong>Initial Version:</strong> Article created.</td></tr> </tbody></table> </div> <hr /> <h2 id="1-the-goal-direct-robust-server-to-server-transfers">1. The Goal: Direct, Robust Server-to-Server Transfers</h2> <p>Before we begin, it’s essential to understand the data flow we are building.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ UNDERSTANDING THE ARCHITECTURE </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The goal is to initiate a transfer that runs entirely on <strong>Server1</strong>, pulling data from itself and pushing it directly to <strong>Server2</strong>. Your local computer is only used to set up the infrastructure and start the process; it can be disconnected immediately afterward.</p> <p><strong>Data Flow:</strong> <code>Server1 (Source) ---(Data Transfer)---&gt; Server2 (Destination)</code></p> </td> </tr> </table> <h2 id="2-prerequisites">2. Prerequisites</h2> <ul> <li>You have <strong>key-based SSH access</strong> from your <strong>local computer</strong> to two Linux servers, <code>Server1</code> and <code>Server2</code>.</li> <li>Password authentication on your servers is (correctly) disabled.</li> <li>You have <code>sudo</code> or <code>root</code> privileges on <code>Server1</code> to install software.</li> </ul> <h3 id="local-ssh-configuration-for-your-convenience">Local SSH Configuration (For Your Convenience)</h3> <p>Define aliases for your servers in your <strong>local computer’s</strong> <code>~/.ssh/config</code> file. This only makes it easier for <em>you</em> to connect; it does not affect the servers themselves.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #6A737D;"># In ~/.ssh/config on your LOCAL machine</span></span> <span class="giallo-l"><span>Host Server1</span></span> <span class="giallo-l"><span> HostName cloud.server1.xyz</span></span> <span class="giallo-l"><span> User your_user</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Host Server2</span></span> <span class="giallo-l"><span> HostName cloud.server2.xyz</span></span> <span class="giallo-l"><span> User root</span></span> <span class="giallo-l"><span> Port 2222 </span><span style="color: #6A737D;"># Use your actual port</span></span></code></pre> <hr /> <h2 id="3-the-core-method-building-the-key-infrastructure">3. The Core Method: Building the Key Infrastructure</h2> <p>This is the most critical part of the tutorial. We will:</p> <ol> <li>Create a deploy key on <code>Server1</code>.</li> <li>Configure the SSH client <strong>on <code>Server1</code></strong> so it knows how to find <code>Server2</code>.</li> <li>Use our local PC as a trusted intermediary to securely install and restrict the key on <code>Server2</code>.</li> </ol> <h3 id="3-1-on-server1-create-the-deploy-key">3.1. On Server1: Create the Deploy Key</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># On your local machine, connect to Server1</span></span> <span class="giallo-l"><span style="color: #B392F0;">ssh</span><span style="color: #9ECBFF;"> Server1</span></span></code></pre><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Now, on Server1, generate a new, passwordless SSH key pair</span></span> <span class="giallo-l"><span style="color: #6A737D;"># When prompted for a passphrase, press Enter twice to leave it empty.</span></span> <span class="giallo-l"><span style="color: #B392F0;">ssh-keygen</span><span style="color: #79B8FF;"> -t</span><span style="color: #9ECBFF;"> ed25519</span><span style="color: #79B8FF;"> -f</span><span style="color: #9ECBFF;"> ~/.ssh/id_deploy_to_server2</span><span style="color: #79B8FF;"> -C</span><span style="color: #9ECBFF;"> &quot;rsync deploy key for server2&quot;</span></span></code></pre><h3 id="3-2-on-server1-configure-its-ssh-client">3.2. On Server1: Configure its SSH Client</h3> <p>We must teach <code>Server1</code> how to connect to <code>Server2</code>. We do this by creating a <code>config</code> file in its <code>.ssh</code> directory.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># On Server1, create and open the config file</span></span> <span class="giallo-l"><span style="color: #B392F0;">nano</span><span style="color: #9ECBFF;"> ~/.ssh/config</span></span></code></pre> <p>Add the following configuration. <strong>Replace the values</strong> with the actual connection details for <code>Server2</code>.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span>Host Server2</span></span> <span class="giallo-l"><span> HostName cloud.server2.xyz</span></span> <span class="giallo-l"><span> User root</span></span> <span class="giallo-l"><span> Port 2222</span></span> <span class="giallo-l"><span> IdentityFile ~/.ssh/id_deploy_to_server2</span></span></code></pre> <ul> <li><code>IdentityFile</code>: This line is key. It tells <code>Server1</code>’s SSH client: “When connecting to the host aliased as ‘Server2’, <strong>always</strong> use this specific private key.”</li> </ul> <p>Save the file (<code>Ctrl+X</code>, then <code>Y</code>, then <code>Enter</code>) and set the correct permissions:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># On Server1</span></span> <span class="giallo-l"><span style="color: #B392F0;">chmod</span><span style="color: #79B8FF;"> 600</span><span style="color: #9ECBFF;"> ~/.ssh/config</span></span></code></pre><h3 id="3-3-on-server1-copy-the-public-key-for-transfer">3.3. On Server1: Copy the Public Key for Transfer</h3> <p>Display the public key so you can copy it to your clipboard.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># On Server1</span></span> <span class="giallo-l"><span style="color: #B392F0;">cat</span><span style="color: #9ECBFF;"> ~/.ssh/id_deploy_to_server2.pub</span></span></code></pre> <p><strong>Action:</strong> Mark and copy the entire output (the line starting <code>ssh-ed25519 AAAA...</code>). Then, log out from <code>Server1</code>.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">exit</span></span></code></pre><h3 id="3-4-from-your-local-pc-install-and-restrict-the-key-on-server2">3.4. From Your Local PC: Install and Restrict the Key on Server2</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># 1. On your local PC, append the key to Server2&#39;s authorized_keys.</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Replace &#39;PASTE_KEY_FROM_CLIPBOARD_HERE&#39; with the key you just copied.</span></span> <span class="giallo-l"><span style="color: #B392F0;">ssh</span><span style="color: #9ECBFF;"> Server2 &quot;echo &#39;PASTE_KEY_FROM_CLIPBOARD_HERE&#39; &gt;&gt; ~/.ssh/authorized_keys&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># 2. Now, SSH to Server2 to restrict the key.</span></span> <span class="giallo-l"><span style="color: #B392F0;">ssh</span><span style="color: #9ECBFF;"> Server2</span></span></code></pre><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># 3. Once on Server2, open the file for editing.</span></span> <span class="giallo-l"><span style="color: #B392F0;">nano</span><span style="color: #9ECBFF;"> ~/.ssh/authorized_keys</span></span></code></pre> <p>In the editor, find the key you just added at the bottom of the file. Navigate to the <strong>very beginning</strong> of that line and prepend the <code>command</code> restriction.</p> <p><strong>Before:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>ssh-ed25519 AAAA... rsync deploy key for server2</span></span></code></pre> <p><strong>After (replace <code>/path/to/destination/</code> with your actual path!):</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>command=&quot;rsync --server -vlogDtpre.iL --partial . /path/to/destination/&quot;,no-port-forwarding,no-x11-forwarding,no-agent-forwarding,no-pty ssh-ed25519 AAAA... rsync deploy key for server2</span></span></code></pre> <p>Save the file and exit the editor (<code>Ctrl+X</code>, then <code>Y</code>, then <code>Enter</code>).</p> <hr /> <h2 id="4-test-the-connection-and-launch-the-transfer">4. Test the Connection and Launch the Transfer</h2> <h3 id="4-1-test-the-inter-server-connection">4.1. Test the Inter-Server Connection</h3> <p>This test now verifies that the new configuration on <code>Server1</code> is working correctly.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># On your local PC</span></span> <span class="giallo-l"><span style="color: #B392F0;">ssh</span><span style="color: #9ECBFF;"> Server1</span></span></code></pre><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Now, on Server1, this command will work because of the new ~/.ssh/config</span></span> <span class="giallo-l"><span style="color: #B392F0;">ssh</span><span style="color: #9ECBFF;"> Server2</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 SUCCESS LOOKS LIKE A FAILURE! </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The terminal may appear to hang and show a message like <code>PTY allocation request failed on channel 0</code>. This is the <strong>expected and correct behavior!</strong> It proves that the server has successfully rejected your request for an interactive shell due to our security rule.</p> <p><strong>Press <code>Ctrl+C</code></strong> to return to the prompt. Your test was successful.</p> </td> </tr> </table> <h3 id="4-2-launch-the-uninterruptible-transfer">4.2. Launch the Uninterruptible Transfer</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># On Server1, install tmux if you haven&#39;t already</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt update</span><span> &amp;&amp;</span><span style="color: #B392F0;"> sudo</span><span style="color: #9ECBFF;"> apt install tmux</span></span></code></pre><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Start a new tmux session</span></span> <span class="giallo-l"><span style="color: #B392F0;">tmux</span><span style="color: #9ECBFF;"> new</span><span style="color: #79B8FF;"> -s</span><span style="color: #9ECBFF;"> syncJob</span></span></code></pre><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Inside the tmux session, execute the now-simplified rsync command.</span></span> <span class="giallo-l"><span style="color: #6A737D;"># No -e option is needed because Server1&#39;s SSH client is now configured!</span></span> <span class="giallo-l"><span style="color: #B392F0;">rsync</span><span style="color: #79B8FF;"> -avh --info=progress2 --partial \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> /path/to/source/</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> Server2:/path/to/destination/</span></span></code></pre><h3 id="4-3-detach-and-disconnect">4.3. Detach and Disconnect</h3> <p>The process is now running. Detach from the <code>tmux</code> session and log out.</p> <blockquote> <p><strong><code>Ctrl+b</code></strong>, then <strong><code>d</code></strong></p> </blockquote> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># On Server1</span></span> <span class="giallo-l"><span style="color: #79B8FF;">exit</span></span></code></pre> <hr /> <h2 id="5-managing-the-rsync-session">5. Managing the <code>rsync</code> Session</h2> <p>You can check on, re-attach, or terminate your transfer at any time.</p> <ul> <li><strong>To check the progress:</strong> <code>ssh Server1</code> and then <code>tmux attach -t syncJob</code>.</li> <li><strong>To kill the session:</strong> <code>ssh Server1</code> and then <code>tmux kill-session -t syncJob</code>.</li> </ul> <hr /> <h2 id="6-quick-troubleshooting">6. Quick Troubleshooting</h2> <div class="styled-table-container"> <table id="custom-table" > <colgroup> <col width="40%"> <col width="60%"> </colgroup> <thead><tr><th>Problem</th><th>Solution</th></tr></thead><tbody> <tr><td><strong>“Could not resolve hostname Server2”</strong></td><td>The <code>~/.ssh/config</code> file on <strong>Server1</strong> is missing, has incorrect permissions (should be 600), or the <code>Host Server2</code> entry is misspelled.</td></tr> <tr><td><strong>“Permission denied (publickey).”</strong></td><td>The <code>IdentityFile</code> path in <code>Server1</code>’s <code>~/.ssh/config</code> might be wrong. Or, the public key was not correctly added to <code>Server2</code>’s <code>authorized_keys</code>.</td></tr> <tr><td><strong><code>ssh Server2</code> test works, but <code>rsync</code> fails</strong></td><td>Check the <code>User</code> in <code>Server1</code>’s <code>~/.ssh/config</code>. Does that user have permission to write to the destination directory on <code>Server2</code>? Also, check the path in the <code>command=</code> restriction.</td></tr> <tr><td><strong>Files are copied into a nested directory</strong></td><td>You likely omitted the trailing slash (<code>/</code>) on your source path. <code>/path/to/source</code> copies the directory itself, while <code>/path/to/source/</code> copies its contents.</td></tr> </tbody> </table> </div> <hr /> <h2 id="7-conclusion">7. Conclusion</h2> <p>By following this definitive guide, you have built a powerful and professionally architected data transfer system. The key was configuring the client (<code>Server1</code>) to know how to reach the target (<code>Server2</code>), a fundamental concept for any automated inter-server task. This setup is ideal for large backups, data migrations, and any scenario where a direct, robust, server-to-server connection is required.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;www.samba.org&#x2F;ftp&#x2F;rsync&#x2F;rsync.html" class="retro-button"> <span class="emoji">📚</span><span class="button-text">RSYNC DOCUMENTATION</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;tmux&#x2F;tmux&#x2F;wiki" class="retro-button"> <span class="emoji">🛡️</span><span class="button-text">TMUX WIKI &amp; DOCS</span> </a> </p> A Smart, mimeapps.list-Aware File Opener for Neomutt Mon, 04 Aug 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/neomutt-file-opener/ https://criticalbasics.xyz/posts/neomutt-file-opener/ <p>Tired of being locked into a single default program for your email attachments in <a rel="noopener external" target="_blank" href="https://github.com/LukeSmithxyz/mutt-wizard">Neomutt</a>? This tutorial will guide you through creating an intelligent file-open-chooser that dynamically reads your system’s <code>mimeapps.list</code> configuration. With a single keypress, you can select from all associated applications to open any attachment, bringing the flexibility of a file manager like Ranger directly into your email client.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-08-04</td><td>Initial version of the tutorial published.</td></tr> </tbody></table> </div> <hr /> <h2 id="part-1">1. Prerequisites</h2> <p>Before we begin, ensure your system has the necessary software and configuration in place.</p> <h3 id="1-1-required-software">1.1. Required Software</h3> <p>This script relies on a few common command-line utilities.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Arch Linux Installation</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> neomutt rofi file</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Optional: dmenu as a fallback for rofi</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> dmenu</span></span></code></pre><h3 id="1-2-existing-configuration">1.2. Existing Configuration</h3> <p>You should already have:</p> <ul> <li>A working Neomutt setup (e.g., one configured with <a rel="noopener external" target="_blank" href="https://github.com/LukeSmithxyz/mutt-wizard"><code>mutt-wizard</code></a>).</li> <li>A populated <code>~/.config/mimeapps.list</code> file with your preferred application associations.</li> </ul> <hr /> <h2 id="part-2">2. The Core Script: <code>file-open-chooser</code></h2> <p>This script is the heart of our new functionality. It identifies an attachment’s file type, finds all associated programs from your <code>mimeapps.list</code>, and presents them in a selection menu.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ BEYOND NEOMUTT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>While we focus on Neomutt here, this script is a full-featured, system-wide file opener. It reads your mimeapps.list and works in any context where files can be piped via stdin - terminal, other mail clients, RSS readers, or custom scripts.</p> </td> </tr> </table> <h3 id="step-1-create-the-script-s-directory-and-file">Step 1: Create the Script’s Directory and File</h3> <p>To keep your scripts organized, we will create a dedicated folder and the script file within it.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Create the subdirectory for our project</span></span> <span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/Scripts/file-open-chooser</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Create the script file itself</span></span> <span class="giallo-l"><span style="color: #B392F0;">touch</span><span style="color: #9ECBFF;"> ~/Scripts/file-open-chooser/file-open-chooser.sh</span></span></code></pre> <p>Now, open the file <code>~/Scripts/file-open-chooser/file-open-chooser.sh</code> and paste the entire content below into it.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;">#!/bin/bash</span></span> <span class="giallo-l"><span style="color: #79B8FF;">set -euo</span><span style="color: #9ECBFF;"> pipefail</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Create a temporary file to hold the attachment content piped from Neomutt</span></span> <span class="giallo-l"><span>tempfile</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">mktemp</span><span>)</span></span> <span class="giallo-l"><span style="color: #B392F0;">cat</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> &quot;</span><span>$tempfile</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Determine the MIME type of the temporary file</span></span> <span class="giallo-l"><span>mimetype</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">file</span><span style="color: #79B8FF;"> --mime-type -b</span><span style="color: #9ECBFF;"> &quot;</span><span>$tempfile</span><span style="color: #9ECBFF;">&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># --- Function to extract available programs from mimeapps.list ---</span></span> <span class="giallo-l"><span style="color: #B392F0;">get_programs_for_mime</span><span>() {</span></span> <span class="giallo-l"><span style="color: #F97583;"> local</span><span> mime</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;">$1</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Read from both [Default Applications] and [Added Associations] sections</span></span> <span class="giallo-l"><span style="color: #F97583;"> for</span><span> section</span><span style="color: #F97583;"> in</span><span style="color: #9ECBFF;"> &quot;Default Applications&quot; &quot;Added Associations&quot;</span><span>;</span><span style="color: #F97583;"> do</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -q</span><span style="color: #9ECBFF;"> &quot;^\[</span><span>$section</span><span style="color: #9ECBFF;">\]&quot; ~/.config/mimeapps.list</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Use awk to find and print programs for the given MIME type</span></span> <span class="giallo-l"><span> apps</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">awk</span><span style="color: #79B8FF;"> -v</span><span style="color: #9ECBFF;"> section=&quot;</span><span>$section</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;"> -v</span><span style="color: #9ECBFF;"> mime=&quot;</span><span>$mime</span><span style="color: #9ECBFF;">&quot; &#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> /^\[.*\]/ { current_section = $0; gsub(/[\[\]]/, &quot;&quot;, current_section) }</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> current_section == section &amp;&amp; $0 ~ &quot;^&quot; mime &quot;=&quot; {</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> sub(&quot;^&quot; mime &quot;=&quot;, &quot;&quot;)</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> gsub(/;/, &quot;\n&quot;)</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> print</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> }&#39; ~/.config/mimeapps.list</span><span>)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [</span><span style="color: #F97583;"> -n</span><span style="color: #9ECBFF;"> &quot;</span><span>$apps</span><span style="color: #9ECBFF;">&quot;</span><span> ];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$apps</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;"> done</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Always include a &quot;Default&quot; option to use the system&#39;s xdg-open</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;Default&quot;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># --- Function to convert a .desktop file name to a human-readable application name ---</span></span> <span class="giallo-l"><span style="color: #B392F0;">desktop_to_name</span><span>() {</span></span> <span class="giallo-l"><span style="color: #F97583;"> local</span><span> desktop</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;">$1</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> local</span><span> desktop_file</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;&quot;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Search for the .desktop file in standard system locations</span></span> <span class="giallo-l"><span style="color: #F97583;"> for</span><span> dir</span><span style="color: #F97583;"> in</span><span style="color: #9ECBFF;"> ~/.local/share/applications /usr/share/applications /usr/local/share/applications</span><span>;</span><span style="color: #F97583;"> do</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [</span><span style="color: #F97583;"> -f</span><span style="color: #9ECBFF;"> &quot;</span><span>$dir</span><span style="color: #9ECBFF;">/</span><span>$desktop</span><span style="color: #9ECBFF;">&quot;</span><span> ];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span> desktop_file</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;</span><span>$dir</span><span style="color: #9ECBFF;">/</span><span>$desktop</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> break</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;"> done</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [</span><span style="color: #F97583;"> -n</span><span style="color: #9ECBFF;"> &quot;</span><span>$desktop_file</span><span style="color: #9ECBFF;">&quot;</span><span> ];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Extract the &#39;Name=&#39; field from the .desktop file</span></span> <span class="giallo-l"><span> name</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">grep</span><span style="color: #9ECBFF;"> &quot;^Name=&quot; &quot;</span><span>$desktop_file</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> head</span><span style="color: #79B8FF;"> -1</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> cut</span><span style="color: #79B8FF;"> -d</span><span style="color: #9ECBFF;">&#39;=&#39;</span><span style="color: #79B8FF;"> -f2-</span><span>)</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;${</span><span>name</span><span style="color: #F97583;">:-</span><span>$desktop</span><span style="color: #9ECBFF;">}&quot;</span><span style="color: #6A737D;"> # Fallback to the filename if Name is not found</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$desktop</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># --- Main Logic ---</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Collect a unique, sorted list of programs</span></span> <span class="giallo-l"><span>programs</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">get_programs_for_mime</span><span style="color: #9ECBFF;"> &quot;</span><span>$mimetype</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sort</span><span style="color: #79B8FF;"> -u</span><span>)</span></span> <span class="giallo-l"><span>display_programs</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Build the display list with readable names</span></span> <span class="giallo-l"><span style="color: #F97583;">while</span><span> IFS</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;"> read -r</span><span style="color: #9ECBFF;"> program</span><span>;</span><span style="color: #F97583;"> do</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [</span><span style="color: #9ECBFF;"> &quot;</span><span>$program</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &quot;Default&quot;</span><span> ];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span> display_programs</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;</span><span>$display_programs$program</span><span style="color: #9ECBFF;">\n&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span> readable_name</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">desktop_to_name</span><span style="color: #9ECBFF;"> &quot;</span><span>$program</span><span style="color: #9ECBFF;">&quot;</span><span>)</span></span> <span class="giallo-l"><span> display_programs</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;</span><span>$display_programs$readable_name</span><span style="color: #9ECBFF;"> (</span><span>$program</span><span style="color: #9ECBFF;">)\n&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;">done &lt;&lt;&lt;</span><span style="color: #9ECBFF;"> &quot;</span><span>$programs</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Show the selection menu using rofi, dmenu, or a terminal prompt as fallback</span></span> <span class="giallo-l"><span>choice</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;&quot;</span><span style="color: #6A737D;"> # Initialize variable</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span style="color: #79B8FF;"> command -v</span><span style="color: #9ECBFF;"> rofi</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;">/dev/null</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span> choice</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo -e</span><span style="color: #9ECBFF;"> &quot;</span><span>$display_programs</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> rofi</span><span style="color: #79B8FF;"> -dmenu -p</span><span style="color: #9ECBFF;"> &quot;Open </span><span>$mimetype</span><span style="color: #9ECBFF;"> with:&quot;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;">elif</span><span style="color: #79B8FF;"> command -v</span><span style="color: #9ECBFF;"> dmenu</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;">/dev/null</span><span>;</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span> choice</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo -e</span><span style="color: #9ECBFF;"> &quot;</span><span>$display_programs</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> dmenu</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> &quot;Open </span><span>$mimetype</span><span style="color: #9ECBFF;"> with:&quot;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;Choose program to open </span><span>$mimetype</span><span style="color: #9ECBFF;"> file:&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo -e</span><span style="color: #9ECBFF;"> &quot;</span><span>$display_programs</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> nl</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> read -p</span><span style="color: #9ECBFF;"> &quot;Enter choice number: &quot; num</span></span> <span class="giallo-l"><span> choice</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo -e</span><span style="color: #9ECBFF;"> &quot;</span><span>$display_programs</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sed</span><span style="color: #79B8FF;"> -n</span><span style="color: #9ECBFF;"> &quot;${</span><span>num</span><span style="color: #9ECBFF;">}p&quot;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Exit if the user cancelled the selection (e.g., by pressing Esc in rofi)</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [</span><span style="color: #F97583;"> -z</span><span style="color: #9ECBFF;"> &quot;</span><span>$choice</span><span style="color: #9ECBFF;">&quot;</span><span> ];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> rm</span><span style="color: #79B8FF;"> -f</span><span style="color: #9ECBFF;"> &quot;</span><span>$tempfile</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> exit 0</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Execute the chosen program</span></span> <span class="giallo-l"><span style="color: #F97583;">if</span><span> [</span><span style="color: #9ECBFF;"> &quot;</span><span>$choice</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &quot;Default&quot;</span><span> ];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> setsid</span><span style="color: #9ECBFF;"> xdg-open &quot;</span><span>$tempfile</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> 2&gt;&amp;1</span><span> &amp;</span></span> <span class="giallo-l"><span style="color: #F97583;">else</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Extract the .desktop filename from the selection (e.g., from &quot;Okular (org.kde.okular.desktop)&quot;)</span></span> <span class="giallo-l"><span> desktop_file</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;</span><span>$choice</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sed</span><span style="color: #9ECBFF;"> &#39;s/.*(\(.*\))/\1/&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [</span><span style="color: #F97583;"> -n</span><span style="color: #9ECBFF;"> &quot;</span><span>$desktop_file</span><span style="color: #9ECBFF;">&quot;</span><span> ] &amp;&amp; [</span><span style="color: #9ECBFF;"> &quot;</span><span>$desktop_file</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> !=</span><span style="color: #9ECBFF;"> &quot;</span><span>$choice</span><span style="color: #9ECBFF;">&quot;</span><span> ];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Use gtk-launch for .desktop files, as it&#39;s the proper way to launch them</span></span> <span class="giallo-l"><span style="color: #B392F0;"> setsid</span><span style="color: #9ECBFF;"> gtk-launch &quot;</span><span>$desktop_file</span><span style="color: #9ECBFF;">&quot; &quot;</span><span>$tempfile</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> 2&gt;&amp;1</span><span> &amp;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Fallback to xdg-open if something went wrong</span></span> <span class="giallo-l"><span style="color: #B392F0;"> setsid</span><span style="color: #9ECBFF;"> xdg-open &quot;</span><span>$tempfile</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #F97583;"> 2&gt;&amp;1</span><span> &amp;</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;">fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Clean up the temporary file after a delay to give the program time to open it</span></span> <span class="giallo-l"><span>(</span><span style="color: #B392F0;">sleep</span><span style="color: #79B8FF;"> 60</span><span>;</span><span style="color: #B392F0;"> rm</span><span style="color: #79B8FF;"> -f</span><span style="color: #9ECBFF;"> &quot;</span><span>$tempfile</span><span style="color: #9ECBFF;">&quot;</span><span>) &amp;</span></span></code></pre><h3 id="step-2-make-the-script-executable">Step 2: Make the Script Executable</h3> <p>Your shell needs permission to run the script file.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">chmod</span><span style="color: #9ECBFF;"> +x ~/Scripts/file-open-chooser/file-open-chooser.sh</span></span></code></pre> <hr /> <h2 id="part-3">3. Neomutt Integration</h2> <p>Now, let’s teach Neomutt our new trick. We will bind the <code>o</code> key (for “open”) in the attachment view to execute our script directly.</p> <p>Add the following line to your Neomutt configuration file (e.g., <code>~/.config/mutt/muttrc</code>):</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #6A737D;"># Add a macro to the attachment menu (key &#39;o&#39;) to pipe the</span></span> <span class="giallo-l"><span style="color: #6A737D;"># attachment to our script by calling it with its full path.</span></span> <span class="giallo-l"><span>macro attach o </span><span style="color: #9ECBFF;">&quot;&lt;pipe-entry&gt;bash $HOME/Scripts/file-open-chooser/file-open-chooser.sh&lt;enter&gt;&quot; &quot;Choose program to open attachment&quot;</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ WHY &#x27;BASH $HOME&#x2F;...&#x27;? </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>By explicitly calling <code>bash</code>, we ensure the script is executed with the Bash interpreter. Using <code>$HOME</code> instead of <code>~</code> is a good practice inside configurations, as it’s more robustly expanded in different contexts.</p> </td> </tr> </table> <hr /> <h2 id="part-4">4. Usage in Neomutt</h2> <p>Your new workflow is simple and efficient:</p> <ol> <li>Navigate to an email with an attachment.</li> <li>Press <code>v</code> to open the attachment view.</li> <li>Use the arrow keys to select the desired attachment.</li> <li>Press <code>o</code> (our new macro).</li> <li>A Rofi (or dmenu) window will appear, listing all compatible programs.</li> <li>Select a program, and the file will open.</li> </ol> <p><strong>Example Workflows:</strong></p> <ul> <li><strong>PDF Attachment</strong> → <code>o</code> → Choose between Okular, Zathura, Evince…</li> <li><strong>Image Attachment</strong> → <code>o</code> → Choose between Viewnior, GIMP, Inkscape…</li> <li><strong>Video Attachment</strong> → <code>o</code> → Choose between MPV, VLC…</li> </ul> <hr /> <h2 id="part-5">5. Customization</h2> <p>To add a new program to the list for a specific file type, simply edit your <code>~/.config/mimeapps.list</code> file. The changes are picked up by the script immediately, with no need to restart anything!</p> <p><strong>Example <code>[Added Associations]</code> section:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #B392F0;">[Added Associations]</span></span> <span class="giallo-l"><span>application/</span><span style="color: #F97583;">pdf</span><span>=org.kde.okular.desktop</span><span style="color: #6A737D;">;org.pwmt.zathura.desktop;org.gnome.Evince.desktop;</span></span> <span class="giallo-l"><span>image/</span><span style="color: #F97583;">jpeg</span><span>=viewnior.desktop</span><span style="color: #6A737D;">;gimp.desktop;</span></span></code></pre><h3 id="another-useful-keybinding">Another Useful Keybinding</h3> <p>You can still define a separate shortcut to <em>always</em> use the default system application without seeing the menu.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #6A737D;"># Add this to your muttrc. &#39;O&#39; (Shift+o) will open with the default handler.</span></span> <span class="giallo-l"><span>macro attach O </span><span style="color: #9ECBFF;">&quot;&lt;pipe-entry&gt;xdg-open&lt;enter&gt;&quot; &quot;Open with default application&quot;</span></span></code></pre> <hr /> <h2 id="part-6">6. Troubleshooting</h2> <p>If things don’t work as expected, here are some common issues and their solutions.</p> <div class="styled-table-container"> <table id="custom-table" > <colgroup> <col width="40%"> <col width="60%"> </colgroup> <thead><tr><th>Problem</th><th>Solution</th></tr></thead><tbody> <tr><td><strong>Permission denied error</strong></td><td>The script is likely not executable. Run <code>chmod +x ~/Scripts/file-open-chooser/file-open-chooser.sh</code> again to be sure.</td></tr> <tr><td><strong>File not found error</strong></td><td>Double-check the path in your Neomutt macro. Make sure it exactly matches the location of your script. Verify with <code>ls -l ~/Scripts/file-open-chooser/file-open-chooser.sh</code>.</td></tr> <tr><td><strong>Rofi/dmenu does not start</strong></td><td>Test <code>rofi</code> directly by running <code>rofi -show run</code>. If it fails, check for error messages. Ensure it’s installed. The script should fall back to a terminal prompt if <code>rofi</code> is missing.</td></tr> <tr><td><strong>Incorrect or no programs listed</strong></td><td>Test the MIME type detection with <code>file --mime-type -b /path/to/some/file.pdf</code>. Check your <code>~/.config/mimeapps.list</code> to ensure the associations for that MIME type are correct.</td></tr> </tbody> </table> </div> <hr /> <h2 id="7-conclusion">7. Conclusion</h2> <p>By implementing this file-open-chooser, you’ve significantly enhanced Neomutt’s capabilities. Your setup now:</p> <ul> <li>✅ Leverages your existing <code>mimeapps.list</code> configuration without duplication.</li> <li>✅ Works universally with any file type.</li> <li>✅ Provides flexible application choices with a single keypress.</li> <li>✅ Integrates elegantly with modern tools like Rofi.</li> <li>✅ Is robust, with fallbacks for different system configurations.</li> <li>✅ Is easy to set up with a direct, simple configuration.</li> </ul> <p>You now have the same power and flexibility to open files in your email client as you do in your file manager.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;neomutt.org&#x2F;guide&#x2F;advanced-usage#using-external-programs" class="retro-button"> <span class="emoji">📚</span><span class="button-text">NEOMUTT DOCS: EXTERNAL PROGRAMS</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;davatorium&#x2F;rofi" class="retro-button"> <span class="emoji">🚀</span><span class="button-text">ROFI ON GITHUB</span> </a> </p> Guide: NVIDIA Legacy Drivers & Multi-Monitor Setup on a ThinkPad W520 (Arch Linux) Wed, 30 Jul 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/thinkpad-w520-nvidia-multi-monitor/ https://criticalbasics.xyz/posts/thinkpad-w520-nvidia-multi-monitor/ <p>This tutorial walks you through the process of setting up a <strong>ThinkPad W520</strong> to run exclusively on its discrete NVIDIA GPU. This is essential for using external monitors connected via the docking station and achieving a stable, high-performance desktop environment on Arch Linux with the i3 window manager.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ THE GOAL </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>The primary objective is to enable the NVIDIA Quadro 1000M/2000M GPU in “Discrete Graphics” mode, install the required legacy <code>nvidia-390xx</code> driver, and configure the system for a stable multi-monitor experience without the freezes commonly caused by compositors like <code>picom</code>.</p> </td> </tr> </table> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-07-29</td><td>Initial version of the guide created.</td></tr> </tbody></table> </div> <hr /> <h2 id="1-correct-bios-configuration">1. Correct BIOS Configuration</h2> <p>First, we need to instruct the system to use only the NVIDIA GPU, bypassing the integrated Intel graphics.</p> <ol> <li>Press <strong>F1</strong> during startup to enter the BIOS setup utility.</li> <li>Navigate to the <code>Config</code> → <code>Display</code> menu.</li> <li>Set the <strong>Graphics Device</strong> option to <strong>Discrete Graphics</strong>. Do not use “Optimus” or “Integrated Graphics.”</li> <li>If the option exists, disable <code>OS Detection for Optimus</code>.</li> <li>Save your changes and exit the BIOS. The system will now reboot.</li> </ol> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 WHY DISCRETE GRAPHICS? </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>On the ThinkPad W520, the physical display outputs (DisplayPort, DVI) on the laptop and its docking station are wired directly to the NVIDIA GPU. They will not function if the system is running on integrated graphics.</p> </td> </tr> </table> <hr /> <h2 id="2-installing-the-nvidia-legacy-driver">2. Installing the NVIDIA Legacy Driver</h2> <p>The NVIDIA Quadro 1000M/2000M GPU found in the W520 belongs to the “Fermi” architecture. Mainline NVIDIA drivers no longer support it, so we must install the <code>nvidia-390xx</code> legacy driver from the Arch User Repository (AUR).</p> <h3 id="2-1-install-an-aur-helper-yay">2.1. Install an AUR Helper (yay)</h3> <p>If you don’t already have an AUR helper, <code>yay</code> is a popular choice.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S --needed</span><span style="color: #9ECBFF;"> git base-devel</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> clone https://aur.archlinux.org/yay.git</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> yay</span></span> <span class="giallo-l"><span style="color: #B392F0;">makepkg</span><span style="color: #79B8FF;"> -si</span></span></code></pre><h3 id="2-2-install-the-nvidia-390xx-driver-from-the-aur">2.2. Install the NVIDIA 390xx Driver from the AUR</h3> <p>Now, use your AUR helper to install the driver and its utilities.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">yay</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> nvidia-390xx-dkms nvidia-390xx-utils</span></span></code></pre> <ul> <li>The <code>-dkms</code> package ensures that the NVIDIA kernel module is automatically rebuilt every time your Linux kernel is updated, which prevents breakage.</li> <li>During the installation, if prompted, allow the installer to blacklist the open-source <code>nouveau</code> driver, as it conflicts with the proprietary NVIDIA driver.</li> </ul> <h3 id="2-3-ensure-kernel-headers-are-present">2.3. Ensure Kernel Headers are Present</h3> <p>DKMS requires kernel headers to build modules. Install them if they are not already on your system.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> linux-headers</span></span></code></pre> <p>After installation, you can run <code>sudo dkms autoinstall</code> to manually rebuild the module if needed.</p> <h3 id="2-4-reboot-and-verify">2.4. Reboot and Verify</h3> <p>A reboot is necessary to load the new kernel module.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> reboot</span></span></code></pre> <p>After rebooting, check if the NVIDIA GPU is active and the driver is loaded correctly by running:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">nvidia-smi</span></span></code></pre> <p>If this command displays your GPU details and driver version, the installation was successful.</p> <hr /> <h2 id="3-minimal-xorg-configuration">3. Minimal Xorg Configuration</h2> <p>To ensure the X server starts correctly, we will create a minimal configuration file.</p> <p>Create the directory if it doesn’t exist:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> /etc/X11/xorg.conf.d</span></span></code></pre> <p>Create and edit the configuration file:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> nano /etc/X11/xorg.conf.d/20-nvidia.conf</span></span></code></pre> <p>Add the following content to the file:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>Section &quot;Device&quot;</span></span> <span class="giallo-l"><span> Identifier &quot;NVIDIA Card&quot;</span></span> <span class="giallo-l"><span> Driver &quot;nvidia&quot;</span></span> <span class="giallo-l"><span> Option &quot;AllowEmptyInitialConfiguration&quot;</span></span> <span class="giallo-l"><span>EndSection</span></span></code></pre> <p>Reboot your system one more time. After this, Xorg should correctly detect all connected displays (both the internal laptop screen and any external monitors) and run them at their native resolutions.</p> <hr /> <h2 id="4-taming-the-compositor-picom">4. Taming the Compositor (picom)</h2> <p>The <code>nvidia-390xx</code> driver can have stability issues with modern compositors like <code>picom</code>, often causing applications like <code>rofi</code> or terminal emulators to freeze the entire desktop. Here are two solutions.</p> <h3 id="4-1-the-stable-solution-configure-picom">4.1. The Stable Solution: Configure picom</h3> <p>You can make <code>picom</code> more stable by changing its rendering backend.</p> <p>Open your <code>picom</code> configuration file:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">nano</span><span style="color: #9ECBFF;"> ~/.config/picom/picom.conf</span></span></code></pre> <p>Find and set the following lines:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>backend = &quot;xrender&quot;;</span></span> <span class="giallo-l"><span>vsync = false;</span></span></code></pre> <p>The <code>xrender</code> backend uses CPU-based rendering. While it may be slightly less performant than the GPU-based GLX backend, it is significantly more stable with this legacy driver.</p> <h3 id="4-2-the-rock-solid-alternative-disable-picom">4.2. The Rock-Solid Alternative: Disable picom</h3> <p>If you don’t need transparency or other compositor effects, the most stable option is to disable <code>picom</code> entirely.</p> <p>First, stop any running instance:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">killall</span><span style="color: #9ECBFF;"> picom</span></span></code></pre> <p>Then, prevent it from starting automatically by commenting out or deleting the relevant line in your i3 config (<code>~/.config/i3/config</code>):</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span># exec --no-startup-id picom</span></span></code></pre><!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 ACHIEVING TEAR-FREE VIDEO WITHOUT A COMPOSITOR </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>You can still get a tear-free experience by enabling the “Force Full Composition Pipeline” option in the NVIDIA settings.</p> <ol> <li>Run <code>nvidia-settings</code> from the terminal.</li> <li>Navigate to <em>X Server Display Configuration</em> → <em>Advanced</em>.</li> <li>Check the box for <strong>Force Full Composition Pipeline</strong>.</li> <li>Click <strong>Apply</strong>, and then save the configuration by running <code>sudo nvidia-settings --write-config</code>. This will make the setting persistent across reboots.</li> </ol> </td> </tr> </table> <hr /> <h2 id="5-multi-monitor-autostart-in-i3">5. Multi-Monitor Autostart in i3</h2> <p>To have i3 automatically arrange your monitors every time it starts, create a simple shell script.</p> <p>First, create a directory for your layout scripts:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.screenlayout</span></span></code></pre> <p>Create the script:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">nano</span><span style="color: #9ECBFF;"> ~/.screenlayout/monitors.sh</span></span></code></pre> <p>Add your <code>xrandr</code> command to the script. Use the <code>xrandr</code> command with no arguments to find the names of your connected outputs (e.g., <code>eDP-1</code>, <code>DP-1</code>, <code>DP-5</code>, etc.).</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;">#!/bin/bash</span></span> <span class="giallo-l"><span style="color: #B392F0;">xrandr</span><span style="color: #79B8FF;"> --output</span><span style="color: #9ECBFF;"> eDP-1</span><span style="color: #79B8FF;"> --primary --mode</span><span style="color: #9ECBFF;"> 1920x1080</span><span style="color: #79B8FF;"> --pos 0x0 --rotate</span><span style="color: #9ECBFF;"> normal</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> --output</span><span style="color: #9ECBFF;"> DP-1</span><span style="color: #79B8FF;"> --mode</span><span style="color: #9ECBFF;"> 1920x1080</span><span style="color: #79B8FF;"> --right-of</span><span style="color: #9ECBFF;"> eDP-1</span><span style="color: #79B8FF;"> --rotate</span><span style="color: #9ECBFF;"> normal</span></span></code></pre> <p>Make the script executable:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">chmod</span><span style="color: #9ECBFF;"> +x ~/.screenlayout/monitors.sh</span></span></code></pre> <p>Finally, add this script to your i3 config to execute it on startup:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span># In ~/.config/i3/config</span></span> <span class="giallo-l"><span>exec --no-startup-id ~/.screenlayout/monitors.sh</span></span></code></pre> <hr /> <h2 id="you-re-all-set">You’re All Set!</h2> <p>Congratulations! You should now have a fully functional and stable setup.</p> <ul> <li>Your ThinkPad W520 is running on its powerful NVIDIA GPU.</li> <li>External monitors connected via the dock are recognized and working.</li> <li>Desktop freezes caused by the compositor have been resolved.</li> <li>Your i3 session automatically configures your monitor layout on startup.</li> </ul> Efficient File Compression in Ranger File Manager Fri, 18 Jul 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/ranger-compression-workflow/ https://criticalbasics.xyz/posts/ranger-compression-workflow/ <p>Terminal file managers like ranger offer powerful ways to manage your files efficiently. This guide shows you how to enhance ranger with custom commands for compressing files into various archive formats directly from the file manager interface. This is part of a series of guides on extending ranger’s functionality.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-07-18</td><td><strong>Initial Version:</strong> Created guide for compression workflow in ranger</td></tr> </tbody></table> </div> <hr /> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>Before we begin, make sure you have the following tools installed:</p> <ul> <li><strong>ranger</strong>: The terminal file manager</li> <li><strong>atool</strong>: A script for managing file archives of various types</li> <li><strong>Archive utilities</strong>: While atool is a wrapper, you’ll need the actual compression tools installed: <ul> <li><strong>zip</strong>, <strong>unzip</strong>: For .zip archives</li> <li><strong>tar</strong>: For .tar, .tar.gz, .tar.bz2 archives</li> <li><strong>p7zip-full</strong> (Debian/Ubuntu) or <strong>p7zip</strong> (Arch/Fedora): For .7z archives</li> <li><strong>rar</strong>, <strong>unrar</strong>: For .rar archives</li> </ul> </li> </ul> <h3 id="installation-on-various-distributions">Installation on Various Distributions</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># For Debian/Ubuntu</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt update</span><span> &amp;&amp;</span><span style="color: #B392F0;"> sudo</span><span style="color: #9ECBFF;"> apt install ranger atool</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># For Arch Linux</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> ranger atool</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># For Fedora</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> dnf install ranger atool</span></span></code></pre> <p>The <code>atool</code> package provides commands like <code>apack</code> (for creating archives) and <code>aunpack</code> (for extracting archives), which we’ll use in our custom ranger commands.</p> <hr /> <h2 id="2-creating-the-custom-compress-command">2. Creating the Custom compress Command</h2> <p>The integration requires adding a custom command to ranger that will use <code>apack</code> to compress selected files into an archive.</p> <h3 id="2-1-create-or-edit-commands-py">2.1. Create or Edit commands.py</h3> <p>First, navigate to your ranger configuration directory and create or edit the <code>commands.py</code> file:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.config/ranger</span></span> <span class="giallo-l"><span style="color: #B392F0;">touch</span><span style="color: #9ECBFF;"> ~/.config/ranger/commands.py</span></span></code></pre> <p>If you don’t have a <code>commands.py</code> file yet, you can generate a template with:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">ranger</span><span style="color: #79B8FF;"> --copy-config=commands</span></span></code></pre><h3 id="2-2-add-the-compress-command">2.2. Add the compress Command</h3> <p>Open the <code>commands.py</code> file in your favorite text editor and add the following code:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span style="color: #F97583;">import</span><span> os</span></span> <span class="giallo-l"><span style="color: #F97583;">from</span><span> ranger.core.loader</span><span style="color: #F97583;"> import</span><span> CommandLoader</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">class</span><span style="color: #B392F0;"> compress</span><span>(</span><span style="color: #B392F0;">Command</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;&quot;&quot; Compress marked files to current directory &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> cwd</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> self</span><span>.fm.thisdir</span></span> <span class="giallo-l"><span> marked_files</span><span style="color: #F97583;"> =</span><span> cwd.get_selection()</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if not</span><span> marked_files:</span></span> <span class="giallo-l"><span style="color: #F97583;"> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> refresh</span><span>(_):</span></span> <span class="giallo-l"><span> cwd</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> self</span><span>.fm.get_directory(original_path)</span></span> <span class="giallo-l"><span> cwd.load_content()</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> original_path</span><span style="color: #F97583;"> =</span><span> cwd.path</span></span> <span class="giallo-l"><span> parts</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> self</span><span>.line.split()</span></span> <span class="giallo-l"><span> au_flags</span><span style="color: #F97583;"> =</span><span> parts[</span><span style="color: #79B8FF;">1</span><span>:]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> descr</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &quot;Compressing to: &quot;</span><span style="color: #F97583;"> +</span><span> os.path.basename(parts[</span><span style="color: #79B8FF;">1</span><span>])</span></span> <span class="giallo-l"><span> obj</span><span style="color: #F97583;"> =</span><span> CommandLoader(</span><span style="color: #FFAB70;">args</span><span style="color: #F97583;">=</span><span>[</span><span style="color: #9ECBFF;">&#39;apack&#39;</span><span>]</span><span style="color: #F97583;"> +</span><span> au_flags</span><span style="color: #F97583;"> +</span><span> \</span></span> <span class="giallo-l"><span> [os.path.relpath(f.path, cwd.path)</span><span style="color: #F97583;"> for</span><span> f</span><span style="color: #F97583;"> in</span><span> marked_files],</span><span style="color: #FFAB70;"> descr</span><span style="color: #F97583;">=</span><span>descr,</span><span style="color: #FFAB70;"> read</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> obj.signal_bind(</span><span style="color: #9ECBFF;">&#39;after&#39;</span><span>, refresh)</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.loader.add(obj)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> tab</span><span>(self, tabnum):</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;&quot;&quot; Complete with current folder name &quot;&quot;&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> extension</span><span style="color: #F97583;"> =</span><span> [</span><span style="color: #9ECBFF;">&#39;.zip&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.tar.gz&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.rar&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.7z&#39;</span><span>]</span></span> <span class="giallo-l"><span style="color: #F97583;"> return</span><span> [</span><span style="color: #9ECBFF;">&#39;compress &#39;</span><span style="color: #F97583;"> +</span><span> os.path.basename(</span><span style="color: #79B8FF;">self</span><span>.fm.thisdir.path)</span><span style="color: #F97583;"> +</span><span> ext</span><span style="color: #F97583;"> for</span><span> ext</span><span style="color: #F97583;"> in</span><span> extension]</span></span></code></pre> <p>This command will:</p> <ol> <li>Take the marked files in ranger</li> <li>Use <code>apack</code> to compress them into an archive</li> <li>Refresh the directory view after compression</li> <li>Provide tab completion for common archive formats</li> </ol> <hr /> <h2 id="3-adding-an-extract-command-optional">3. Adding an Extract Command (Optional)</h2> <p>For a complete compression workflow, you might also want to add an extraction command. Add this to your <code>commands.py</code> file:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span style="color: #F97583;">class</span><span style="color: #B392F0;"> extract_here</span><span>(</span><span style="color: #B392F0;">Command</span><span>):</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;&quot;&quot; Extract selected files to current directory &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> cwd</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> self</span><span>.fm.thisdir</span></span> <span class="giallo-l"><span> marked_files</span><span style="color: #F97583;"> =</span><span> cwd.get_selection()</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if not</span><span> marked_files:</span></span> <span class="giallo-l"><span style="color: #F97583;"> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> refresh</span><span>(_):</span></span> <span class="giallo-l"><span> cwd</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> self</span><span>.fm.get_directory(original_path)</span></span> <span class="giallo-l"><span> cwd.load_content()</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> original_path</span><span style="color: #F97583;"> =</span><span> cwd.path</span></span> <span class="giallo-l"><span> au_flags</span><span style="color: #F97583;"> =</span><span> [</span><span style="color: #9ECBFF;">&#39;-X&#39;</span><span>, cwd.path]</span><span style="color: #6A737D;"> # Extract to current directory</span></span> <span class="giallo-l"><span> au_flags</span><span style="color: #F97583;"> +=</span><span style="color: #79B8FF;"> self</span><span>.line.split()[</span><span style="color: #79B8FF;">1</span><span>:]</span></span> <span class="giallo-l"><span> au_flags</span><span style="color: #F97583;"> +=</span><span> [</span><span style="color: #9ECBFF;">&#39;-e&#39;</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.copy_buffer.clear()</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.cut_buffer</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> False</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #79B8FF;"> len</span><span>(marked_files)</span><span style="color: #F97583;"> ==</span><span style="color: #79B8FF;"> 1</span><span>:</span></span> <span class="giallo-l"><span> descr</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &quot;extracting: &quot;</span><span style="color: #F97583;"> +</span><span> os.path.basename(marked_files[</span><span style="color: #79B8FF;">0</span><span>].path)</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span><span>:</span></span> <span class="giallo-l"><span> descr</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &quot;extracting </span><span style="color: #79B8FF;">{}</span><span style="color: #9ECBFF;"> files&quot;</span><span>.format(</span><span style="color: #79B8FF;">len</span><span>(marked_files))</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> obj</span><span style="color: #F97583;"> =</span><span> CommandLoader(</span><span style="color: #FFAB70;">args</span><span style="color: #F97583;">=</span><span>[</span><span style="color: #9ECBFF;">&#39;aunpack&#39;</span><span>]</span><span style="color: #F97583;"> +</span><span> au_flags</span><span style="color: #F97583;"> +</span><span> \</span></span> <span class="giallo-l"><span> [f.path</span><span style="color: #F97583;"> for</span><span> f</span><span style="color: #F97583;"> in</span><span> marked_files],</span><span style="color: #FFAB70;"> descr</span><span style="color: #F97583;">=</span><span>descr,</span><span style="color: #FFAB70;"> read</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> obj.signal_bind(</span><span style="color: #9ECBFF;">&#39;after&#39;</span><span>, refresh)</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.loader.add(obj)</span></span></code></pre> <hr /> <h2 id="4-creating-keyboard-shortcuts">4. Creating Keyboard Shortcuts</h2> <p>Now that we have our custom commands, let’s create keyboard shortcuts to invoke them easily.</p> <h3 id="4-1-edit-rc-conf">4.1. Edit rc.conf</h3> <p>Open your ranger configuration file:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">vim</span><span style="color: #9ECBFF;"> ~/.config/ranger/rc.conf</span></span></code></pre> <p>If you don’t have this file yet, you can generate it with:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">ranger</span><span style="color: #79B8FF;"> --copy-config=rc</span></span></code></pre><h3 id="4-2-add-the-keyboard-mappings">4.2. Add the Keyboard Mappings</h3> <p>Add the following lines to map the commands to keyboard shortcuts:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span># Compression and extraction</span></span> <span class="giallo-l"><span>map cc console compress%space</span></span> <span class="giallo-l"><span>map cx extract_here</span></span></code></pre> <p>With these shortcuts:</p> <ul> <li><code>cc</code> will start the compress command and wait for you to specify the archive name</li> <li><code>cx</code> will extract the selected archive in the current directory</li> </ul> <div class="styled-table-container shortcut-table"> <table><thead><tr><th>Shortcut</th><th>Description</th></tr></thead><tbody> <tr><td><code>cc</code></td><td>Compress selected files into an archive</td></tr> <tr><td><code>cx</code></td><td>Extract selected archive in the current directory</td></tr> </tbody></table> </div> <hr /> <h2 id="5-advanced-configuration">5. Advanced Configuration</h2> <h3 id="5-1-customize-archive-formats">5.1. Customize Archive Formats</h3> <p>You can modify the list of supported archive extensions in the <code>tab</code> method of the <code>compress</code> command:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span style="color: #F97583;">def</span><span style="color: #B392F0;"> tab</span><span>(self, tabnum):</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;&quot;&quot; Complete with current folder name &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> extension</span><span style="color: #F97583;"> =</span><span> [</span><span style="color: #9ECBFF;">&#39;.zip&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.tar.gz&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.tar.bz2&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.tar.xz&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.rar&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.7z&#39;</span><span>]</span></span> <span class="giallo-l"><span style="color: #F97583;"> return</span><span> [</span><span style="color: #9ECBFF;">&#39;compress &#39;</span><span style="color: #F97583;"> +</span><span> os.path.basename(</span><span style="color: #79B8FF;">self</span><span>.fm.thisdir.path)</span><span style="color: #F97583;"> +</span><span> ext</span><span style="color: #F97583;"> for</span><span> ext</span><span style="color: #F97583;"> in</span><span> extension]</span></span></code></pre> <p>Add or remove archive formats based on your needs and installed utilities.</p> <h3 id="5-2-add-compression-options">5.2. Add Compression Options</h3> <p>You can enhance the <code>compress</code> command to support additional options like compression level:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span style="color: #F97583;">def</span><span style="color: #B392F0;"> tab</span><span>(self, tabnum):</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;&quot;&quot; Complete with current folder name and compression options &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> extension</span><span style="color: #F97583;"> =</span><span> [</span><span style="color: #9ECBFF;">&#39;.zip&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.tar.gz&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.rar&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.7z&#39;</span><span>]</span></span> <span class="giallo-l"><span> base_name</span><span style="color: #F97583;"> =</span><span> os.path.basename(</span><span style="color: #79B8FF;">self</span><span>.fm.thisdir.path)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Basic archive names</span></span> <span class="giallo-l"><span> options</span><span style="color: #F97583;"> =</span><span> [</span><span style="color: #9ECBFF;">&#39;compress &#39;</span><span style="color: #F97583;"> +</span><span> base_name</span><span style="color: #F97583;"> +</span><span> ext</span><span style="color: #F97583;"> for</span><span> ext</span><span style="color: #F97583;"> in</span><span> extension]</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Add options with compression levels for zip</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> tabnum</span><span style="color: #F97583;"> ==</span><span style="color: #79B8FF;"> 1</span><span>:</span></span> <span class="giallo-l"><span> options</span><span style="color: #F97583;"> +=</span><span> [</span><span style="color: #9ECBFF;">&#39;compress &#39;</span><span style="color: #F97583;"> +</span><span> base_name</span><span style="color: #F97583;"> +</span><span style="color: #9ECBFF;"> &#39;.zip -mx=9&#39;</span><span>]</span><span style="color: #6A737D;"> # Maximum compression</span></span> <span class="giallo-l"><span> options</span><span style="color: #F97583;"> +=</span><span> [</span><span style="color: #9ECBFF;">&#39;compress &#39;</span><span style="color: #F97583;"> +</span><span> base_name</span><span style="color: #F97583;"> +</span><span style="color: #9ECBFF;"> &#39;.zip -mx=1&#39;</span><span>]</span><span style="color: #6A737D;"> # Fastest compression</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #F97583;"> return</span><span> options</span></span></code></pre><h3 id="5-3-exclude-certain-files">5.3. Exclude Certain Files</h3> <p>You might want to exclude certain files from compression (like temporary files or already compressed files). You can modify the <code>execute</code> method to filter the marked files:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span>marked_files</span><span style="color: #F97583;"> =</span><span> [f</span><span style="color: #F97583;"> for</span><span> f</span><span style="color: #F97583;"> in</span><span> cwd.get_selection()</span><span style="color: #F97583;"> if not</span><span> f.path.endswith((</span><span style="color: #9ECBFF;">&#39;.zip&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.rar&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;.7z&#39;</span><span>))]</span></span></code></pre> <hr /> <h2 id="6-usage">6. Usage</h2> <p>Once everything is set up, you can use your new compression workflow:</p> <h3 id="6-1-creating-archives">6.1. Creating Archives</h3> <ol> <li>Open ranger in your terminal</li> <li>Navigate to the directory containing files you want to compress</li> <li>Select files using the <code>space</code> key (or select a single file with the cursor)</li> <li>Press <code>cc</code> to start the compress command</li> <li>Type the archive name or press <code>Tab</code> to auto-complete with suggested formats</li> <li>Press <code>Enter</code> to create the archive</li> </ol> <h3 id="6-2-extracting-archives">6.2. Extracting Archives</h3> <ol> <li>Navigate to an archive file or select it</li> <li>Press <code>cx</code> to extract its contents to the current directory</li> </ol> <hr /> <h2 id="7-practical-examples">7. Practical Examples</h2> <h3 id="7-1-backup-workflow">7.1. Backup Workflow</h3> <p>Create quick backups of important directories:</p> <ol> <li>Navigate to a project folder</li> <li>Press <code>cc</code> then <code>Tab</code> to get suggestions</li> <li>Select <code>.tar.gz</code> format for good compression</li> <li>Add a date to the filename: <code>project-backup-2025-07-18.tar.gz</code></li> </ol> <h3 id="7-2-sharing-files">7.2. Sharing Files</h3> <p>Compress files for sharing:</p> <ol> <li>Select multiple files with <code>space</code></li> <li>Press <code>cc</code> and create a <code>.zip</code> file (most compatible format)</li> <li>The archive is ready to be emailed or transferred</li> </ol> <h3 id="7-3-working-with-different-archive-types">7.3. Working with Different Archive Types</h3> <p>The workflow supports various archive formats:</p> <ul> <li><code>.zip</code> - Good compatibility across platforms</li> <li><code>.tar.gz</code> - Better compression, common on Linux</li> <li><code>.7z</code> - Best compression ratio</li> <li><code>.rar</code> - Good for split archives</li> </ul> <hr /> <h2 id="8-troubleshooting">8. Troubleshooting</h2> <h3 id="8-1-command-not-found">8.1. Command Not Found</h3> <p>If you get a “Command not found” error when trying to use the shortcut:</p> <ul> <li>Make sure you’ve saved the <code>commands.py</code> file correctly</li> <li>Restart ranger to load the new command</li> <li>Check that <code>atool</code> is installed and in your PATH</li> </ul> <h3 id="8-2-compression-fails">8.2. Compression Fails</h3> <p>If compression fails:</p> <ul> <li>Check if you have the appropriate compression tools installed</li> <li>Verify that you have write permissions in the current directory</li> <li>Make sure you have enough disk space</li> </ul> <p>Try running <code>apack</code> directly to see if it works outside of ranger:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">apack</span><span style="color: #9ECBFF;"> archive.zip file1 file2 file3</span></span></code></pre><h3 id="8-3-file-not-found-errors">8.3. File Not Found Errors</h3> <p>If you get “file not found” errors:</p> <ul> <li>Make sure you’re not trying to compress files with special characters in their names</li> <li>Check if the paths are correct</li> <li>Try using relative paths instead of absolute paths</li> </ul> <hr /> <h2 id="summary">Summary</h2> <p>With this compression workflow integration, you’ve enhanced ranger’s capabilities for working with archives:</p> <p>✅ Quick compression of files with just a few keystrokes ✅ Support for multiple archive formats ✅ Tab completion for common archive types ✅ Easy extraction of archives ✅ Seamless integration with your terminal workflow</p> <p>This setup is particularly valuable for system administrators, developers, and anyone who frequently needs to create or extract archives. It combines the file management power of ranger with the versatility of atool for handling various archive formats.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;www.nongnu.org&#x2F;atool&#x2F;" class="retro-button"> <span class="emoji">📚</span><span class="button-text">ATOOL DOCUMENTATION</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;ranger&#x2F;ranger&#x2F;wiki&#x2F;Custom-Commands" class="retro-button"> <span class="emoji">🔧</span><span class="button-text">RANGER CUSTOM COMMANDS</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;wiki.archlinux.org&#x2F;title&#x2F;Ranger#Archives" class="retro-button"> <span class="emoji">📦</span><span class="button-text">ARCH WIKI: RANGER ARCHIVES</span> </a> </p> <hr /> <h2 id="related-ranger-guides">Related Ranger Guides</h2> <p>Enhance your ranger experience with these additional tutorials:</p> <ul> <li><a href="/posts/ranger-fzf-bat-integration/">Ranger and fzf Integration</a> - Add powerful fuzzy search capabilities</li> <li><a href="/posts/ranger-exiftool-integration/">Image Metadata Viewing with exiftool</a> - View detailed metadata for images and media files</li> <li><a href="/posts/ranger-media-preview-configuration/">Advanced Media Preview Configuration</a> - Customize file previews for various formats</li> <li><a href="/posts/ranger-sxiv-integration/">Ranger and sxiv Integration</a> - Create a seamless image viewing workflow</li> </ul> Enhancing Ranger with fzf and bat: A Powerful File Search Integration Fri, 18 Jul 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/ranger-fzf-bat-integration/ https://criticalbasics.xyz/posts/ranger-fzf-bat-integration/ <p>The ranger file manager is already a powerful tool for navigating your filesystem, but with the addition of <code>fzf</code> (fuzzy finder) and <code>bat</code> (syntax highlighter), you can supercharge your file searching capabilities. This guide will show you how to integrate these tools for a seamless and visually appealing search experience.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-07-18</td><td><strong>Initial Version:</strong> Created guide for integrating fzf and bat with ranger</td></tr> </tbody></table> </div> <hr /> <h2 id="1-prerequisites">1. Prerequisites</h2> <p>Before we begin, ensure you have the following tools installed on your system:</p> <ul> <li><strong>ranger</strong>: The terminal file manager</li> <li><strong>fzf</strong>: Command-line fuzzy finder</li> <li><strong>bat</strong>: A cat clone with syntax highlighting</li> </ul> <h3 id="installation-on-various-distributions">Installation on Various Distributions</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># For Debian/Ubuntu</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt update</span><span> &amp;&amp;</span><span style="color: #B392F0;"> sudo</span><span style="color: #9ECBFF;"> apt install ranger fzf bat</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># For Arch Linux</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> ranger fzf bat</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># For Fedora</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> dnf install ranger fzf bat</span></span></code></pre> <p><strong>Note</strong>: On some distributions, <code>bat</code> might be packaged as <code>batcat</code>. You can create an alias in your shell configuration file:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F97583;">alias</span><span> bat</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;batcat&#39;</span></span></code></pre> <hr /> <h2 id="2-creating-the-custom-fzf-select-command">2. Creating the Custom fzf_select Command</h2> <p>The integration requires adding a custom command to ranger. This command will use <code>fzf</code> for searching and <code>bat</code> for file previews.</p> <h3 id="2-1-create-or-edit-commands-py">2.1. Create or Edit commands.py</h3> <p>First, navigate to your ranger configuration directory and create or edit the <code>commands.py</code> file:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.config/ranger</span></span> <span class="giallo-l"><span style="color: #B392F0;">touch</span><span style="color: #9ECBFF;"> ~/.config/ranger/commands.py</span></span></code></pre> <p>If you don’t have a <code>commands.py</code> file yet, you can generate a template with:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">ranger</span><span style="color: #79B8FF;"> --copy-config=commands</span></span></code></pre><h3 id="2-2-add-the-fzf-select-command">2.2. Add the fzf_select Command</h3> <p>Open the <code>commands.py</code> file in your favorite text editor and add the following code:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span style="color: #F97583;">from</span><span> ranger.api.commands</span><span style="color: #F97583;"> import</span><span> Command</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> os</span></span> <span class="giallo-l"><span style="color: #F97583;">import</span><span> subprocess</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">class</span><span style="color: #B392F0;"> fzf_select</span><span>(</span><span style="color: #B392F0;">Command</span><span>):</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> :fzf_select</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9ECBFF;"> Find a file or directory using fzf with preview using bat, excluding certain directories unless currently in them.</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> def</span><span style="color: #B392F0;"> execute</span><span>(self):</span></span> <span class="giallo-l"><span> exclude_dirs</span><span style="color: #F97583;"> =</span><span> [</span><span style="color: #9ECBFF;">&#39;Remote&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;USBmount&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;NFSshares&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;Games_ROMS&#39;</span><span>]</span><span style="color: #6A737D;"> # List of directories to exclude</span></span> <span class="giallo-l"><span> current_dir</span><span style="color: #F97583;"> =</span><span> os.getcwd()</span></span> <span class="giallo-l"><span> base_name</span><span style="color: #F97583;"> =</span><span> os.path.basename(current_dir)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # Check if the current directory is in the list of directories to exclude</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> base_name</span><span style="color: #F97583;"> in</span><span> exclude_dirs:</span></span> <span class="giallo-l"><span> find_command</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &quot;find . -type f -o -type d&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span><span>:</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Construct the find command with exclusion criteria</span></span> <span class="giallo-l"><span> exclude_opts</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &#39; &#39;</span><span>.join(</span><span style="color: #F97583;">f</span><span style="color: #9ECBFF;">&quot;-path &#39;./</span><span style="color: #79B8FF;">{</span><span>d</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;">&#39; -prune -o&quot;</span><span style="color: #F97583;"> for</span><span> d</span><span style="color: #F97583;"> in</span><span> exclude_dirs)</span></span> <span class="giallo-l"><span> find_command</span><span style="color: #F97583;"> = f</span><span style="color: #9ECBFF;">&quot;find . </span><span style="color: #79B8FF;">\\</span><span style="color: #9ECBFF;">( </span><span style="color: #79B8FF;">{</span><span>exclude_opts</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;"> -false </span><span style="color: #79B8FF;">\\</span><span style="color: #9ECBFF;">) -o </span><span style="color: #79B8FF;">\\</span><span style="color: #9ECBFF;">( -type f -o -type d </span><span style="color: #79B8FF;">\\</span><span style="color: #9ECBFF;">) -print&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> command</span><span style="color: #F97583;"> = f</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;">{</span><span>find_command</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;"> | fzf --preview &#39;[[ -f </span><span style="color: #79B8FF;">{{}}</span><span style="color: #9ECBFF;"> ]] &amp;&amp; bat --style=numbers --color=always </span><span style="color: #79B8FF;">{{}}</span><span style="color: #9ECBFF;"> || echo </span><span style="color: #79B8FF;">{{}}</span><span style="color: #9ECBFF;"> is a directory&#39; --preview-window=right:70%:wrap --exact&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> fzf</span><span style="color: #F97583;"> =</span><span> subprocess.Popen(command,</span><span style="color: #FFAB70;"> stdout</span><span style="color: #F97583;">=</span><span>subprocess.</span><span style="color: #79B8FF;">PIPE</span><span>,</span><span style="color: #FFAB70;"> shell</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>,</span><span style="color: #FFAB70;"> text</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;">True</span><span>,</span><span style="color: #FFAB70;"> cwd</span><span style="color: #F97583;">=</span><span>current_dir)</span></span> <span class="giallo-l"><span> selected, _</span><span style="color: #F97583;"> =</span><span> fzf.communicate()</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> fzf.returncode</span><span style="color: #F97583;"> ==</span><span style="color: #79B8FF;"> 0</span><span>:</span></span> <span class="giallo-l"><span> selected</span><span style="color: #F97583;"> =</span><span> selected.strip()</span></span> <span class="giallo-l"><span> selected_path</span><span style="color: #F97583;"> =</span><span> os.path.abspath(selected)</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> os.path.isdir(selected_path):</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Change to the directory if it&#39;s a directory</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.cd(selected_path)</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span><span>:</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Open the file if it&#39;s a file</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.select_file(selected_path)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # Explicitly refresh the ranger window</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> self</span><span>.fm.ui.redraw_window()</span></span></code></pre> <p>This command will:</p> <ol> <li>Exclude specific directories from the search (unless you’re already in one of them)</li> <li>Use <code>bat</code> for file previews and show a simple message for directories</li> <li>Execute <code>fzf</code> with the appropriate options</li> <li>Navigate to the selected file or directory</li> <li>Explicitly refresh the ranger window after selection</li> </ol> <hr /> <h2 id="3-creating-a-keyboard-shortcut">3. Creating a Keyboard Shortcut</h2> <p>Now that we have our custom command, let’s create a keyboard shortcut to invoke it easily.</p> <h3 id="3-1-edit-rc-conf">3.1. Edit rc.conf</h3> <p>Open your ranger configuration file:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">vim</span><span style="color: #9ECBFF;"> ~/.config/ranger/rc.conf</span></span></code></pre> <p>If you don’t have this file yet, you can generate it with:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">ranger</span><span style="color: #79B8FF;"> --copy-config=rc</span></span></code></pre><h3 id="3-2-add-the-keyboard-mapping">3.2. Add the Keyboard Mapping</h3> <p>Add the following line to map the <code>fzf_select</code> command to a keyboard shortcut. In this example, we’ll use <code>zi</code> (which stands for “zoom in”):</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>map zi fzf_select</span></span></code></pre> <p>This shortcut is easy to remember as <code>zi</code> stands for “zoom in” - which is exactly what this command does: it zooms into your file structure to quickly find what you’re looking for.</p> <div class="styled-table-container shortcut-table"> <table><thead><tr><th>Shortcut</th><th>Description</th></tr></thead><tbody> <tr><td><code>zi</code></td><td>Start fuzzy search with fzf and bat preview (“zoom in” to your files)</td></tr> </tbody></table> </div> <hr /> <h2 id="4-advanced-configuration">4. Advanced Configuration</h2> <h3 id="4-1-customize-directory-exclusions">4.1. Customize Directory Exclusions</h3> <p>You can modify the list of directories to exclude from the search by changing the <code>exclude_dirs</code> list in the <code>fzf_select</code> command:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span>exclude_dirs</span><span style="color: #F97583;"> =</span><span> [</span><span style="color: #9ECBFF;">&#39;Remote&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;USBmount&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;NFSshares&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;Games_ROMS&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;VirtualMachines&#39;</span><span>]</span><span style="color: #6A737D;"> # Add or remove directories as needed</span></span></code></pre><h3 id="4-2-show-hidden-files">4.2. Show Hidden Files</h3> <p>If you want to include hidden files in your search, modify the <code>find_command</code> variable:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span>find_command</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &quot;find . -type f -o -type d -name &#39;.*&#39; -o -type f -o -type d&quot;</span></span></code></pre><h3 id="4-3-customize-preview-options">4.3. Customize Preview Options</h3> <p>You can customize how <code>bat</code> displays file previews by modifying the preview part of the command:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="python"><span class="giallo-l"><span>command</span><span style="color: #F97583;"> = f</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;">{</span><span>find_command</span><span style="color: #79B8FF;">}</span><span style="color: #9ECBFF;"> | fzf --preview &#39;[[ -f </span><span style="color: #79B8FF;">{{}}</span><span style="color: #9ECBFF;"> ]] &amp;&amp; bat --style=full --color=always --line-range :150 </span><span style="color: #79B8FF;">{{}}</span><span style="color: #9ECBFF;"> || echo </span><span style="color: #79B8FF;">{{}}</span><span style="color: #9ECBFF;"> is a directory&#39; --preview-window=right:60%:wrap --exact&quot;</span></span></code></pre> <p>This example:</p> <ul> <li>Uses the “full” style for bat (includes line numbers, Git modifications, etc.)</li> <li>Shows up to 150 lines in the preview</li> <li>Sets the preview window width to 60% of the terminal</li> </ul> <hr /> <h2 id="5-usage">5. Usage</h2> <p>Once everything is set up, you can use your new fuzzy search capability:</p> <ol> <li>Open ranger in your terminal</li> <li>Press your configured shortcut (e.g., <code>zi</code>)</li> <li>Type to search for files</li> <li>Use arrow keys to navigate through results</li> <li>Press Enter to select a file or directory</li> </ol> <hr /> <h2 id="6-troubleshooting">6. Troubleshooting</h2> <h3 id="6-1-command-not-found">6.1. Command Not Found</h3> <p>If you get a “Command not found” error when trying to use the shortcut:</p> <ul> <li>Make sure you’ve saved the <code>commands.py</code> file correctly</li> <li>Restart ranger to load the new command</li> <li>Check that <code>fzf</code> and <code>bat</code> are installed and in your PATH</li> </ul> <h3 id="6-2-preview-not-working">6.2. Preview Not Working</h3> <p>If file previews aren’t displaying:</p> <ul> <li>Verify that <code>bat</code> is installed correctly</li> <li>Try using <code>batcat</code> instead of <code>bat</code> if you’re on Debian/Ubuntu</li> <li>Check if your terminal supports the preview feature</li> </ul> <hr /> <h2 id="summary">Summary</h2> <p>With this integration, you’ve significantly enhanced ranger’s search capabilities:</p> <p>✅ Lightning-fast file searching with fuzzy matching ✅ Beautiful syntax-highlighted previews ✅ Seamless navigation to selected files ✅ Customizable interface and behavior</p> <p>This setup combines the best of three powerful tools: ranger’s file management, fzf’s search capabilities, and bat’s beautiful syntax highlighting.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;ranger&#x2F;ranger&#x2F;wiki&#x2F;Custom-Commands" class="retro-button"> <span class="emoji">📚</span><span class="button-text">RANGER CUSTOM COMMANDS</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;junegunn&#x2F;fzf" class="retro-button"> <span class="emoji">🔍</span><span class="button-text">FZF DOCUMENTATION</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;sharkdp&#x2F;bat" class="retro-button"> <span class="emoji">🦇</span><span class="button-text">BAT DOCUMENTATION</span> </a> </p> Advanced Media Preview Configuration in Ranger Fri, 18 Jul 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/ranger-media-preview-configuration/ https://criticalbasics.xyz/posts/ranger-media-preview-configuration/ <p>One of ranger’s most powerful features is its ability to preview various file types directly in the terminal. This guide shows you how to customize the preview system to support a wide range of media files with optimal display settings.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-07-18</td><td><strong>Initial Version:</strong> Created guide for customizing media previews in ranger</td></tr> </tbody></table> </div> <hr /> <h2 id="1-understanding-ranger-s-preview-system">1. Understanding Ranger’s Preview System</h2> <p>Ranger uses a script called <code>scope.sh</code> to generate previews for different file types. This script determines how to handle each file based on its MIME type or extension, then calls the appropriate external tools to generate a preview.</p> <h3 id="1-1-the-preview-process">1.1. The Preview Process</h3> <p>When you select a file in ranger:</p> <ol> <li>Ranger calls the <code>scope.sh</code> script</li> <li>The script identifies the file type</li> <li>It selects an appropriate preview method</li> <li>The preview is displayed in the preview pane</li> </ol> <h3 id="1-2-default-configuration">1.2. Default Configuration</h3> <p>By default, ranger comes with a sample <code>scope.sh</code> file, but it’s not automatically installed. You need to copy it to your configuration directory and customize it for your needs.</p> <hr /> <h2 id="2-setting-up-the-preview-script">2. Setting Up the Preview Script</h2> <h3 id="2-1-copy-the-default-scope-sh">2.1. Copy the Default scope.sh</h3> <p>First, create your ranger configuration directory if it doesn’t exist:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.config/ranger</span></span></code></pre> <p>Then, copy the default <code>scope.sh</code> script:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">ranger</span><span style="color: #79B8FF;"> --copy-config=scope</span></span></code></pre> <p>This will create <code>~/.config/ranger/scope.sh</code> with the default configuration.</p> <h3 id="2-2-make-the-script-executable">2.2. Make the Script Executable</h3> <p>Ensure the script is executable:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">chmod</span><span style="color: #9ECBFF;"> +x ~/.config/ranger/scope.sh</span></span></code></pre> <hr /> <h2 id="3-installing-preview-dependencies">3. Installing Preview Dependencies</h2> <p>To get the most out of ranger’s preview capabilities, you’ll need to install various tools for different file types:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># For Debian/Ubuntu</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> apt update</span><span> &amp;&amp;</span><span style="color: #B392F0;"> sudo</span><span style="color: #9ECBFF;"> apt install highlight atool lynx mediainfo poppler-utils</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ffmpegthumbnailer imagemagick transmission-cli odt2txt</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> python3-pygments catdoc docx2txt fontforge</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># For Arch Linux</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> highlight atool lynx mediainfo poppler ffmpegthumbnailer</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> imagemagick transmission-cli python-pygments catdoc fontforge</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># For Fedora</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> dnf install highlight atool lynx mediainfo poppler-utils ffmpegthumbnailer</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> ImageMagick transmission python3-pygments catdoc fontforge</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Optional: Install xlsx2csv for spreadsheet previews</span></span> <span class="giallo-l"><span style="color: #B392F0;">pip</span><span style="color: #9ECBFF;"> install xlsx2csv</span></span></code></pre> <hr /> <h2 id="4-customizing-the-preview-script">4. Customizing the Preview Script</h2> <p>Now let’s customize the <code>scope.sh</code> script to enhance the preview capabilities. Open the file in your favorite text editor:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">vim</span><span style="color: #9ECBFF;"> ~/.config/ranger/scope.sh</span></span></code></pre><h3 id="4-1-image-preview-configuration">4.1. Image Preview Configuration</h3> <p>Find the section that handles images and customize it:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F97583;">case</span><span style="color: #9ECBFF;"> &quot;${</span><span>mimetype</span><span style="color: #9ECBFF;">}&quot;</span><span style="color: #F97583;"> in</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Image previews</span></span> <span class="giallo-l"><span style="color: #DBEDFF;"> image/</span><span style="color: #F97583;">*)</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Use preview size of 1920px for large images</span></span> <span class="giallo-l"><span style="color: #F97583;"> local</span><span> geometry</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;1920x1080&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [[</span><span style="color: #9ECBFF;"> &quot;${</span><span>mimetype</span><span style="color: #9ECBFF;">}&quot;</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &quot;image/svg+xml&quot;</span><span> ]];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> convert</span><span style="color: #79B8FF;"> --</span><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot; &quot;${</span><span>IMAGE_CACHE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 6</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #B392F0;"> exiftool</span><span style="color: #79B8FF;"> -b -PreviewImage -w</span><span style="color: #9ECBFF;"> &quot;${</span><span>IMAGE_CACHE_PATH</span><span style="color: #9ECBFF;">}&quot; &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 6</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # If exiftool failed, try standard conversion</span></span> <span class="giallo-l"><span style="color: #B392F0;"> convert</span><span style="color: #79B8FF;"> --</span><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}[0]&quot;</span><span style="color: #79B8FF;"> -resize</span><span style="color: #9ECBFF;"> &quot;${</span><span>geometry</span><span style="color: #9ECBFF;">}&quot; &quot;${</span><span>IMAGE_CACHE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 6</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span> ;;</span></span></code></pre><h3 id="4-2-video-preview-with-ffmpegthumbnailer">4.2. Video Preview with FFmpegthumbnailer</h3> <p>Enhance the video preview section:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">video/*</span><span>)</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Video preview using ffmpegthumbnailer</span></span> <span class="giallo-l"><span style="color: #B392F0;"> ffmpegthumbnailer</span><span style="color: #79B8FF;"> -i</span><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span style="color: #79B8FF;"> -o</span><span style="color: #9ECBFF;"> &quot;${</span><span>IMAGE_CACHE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span style="color: #79B8FF;"> -s 0 -q 10</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 6</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> exit 1</span></span> <span class="giallo-l"><span> ;;</span></span></code></pre><h3 id="4-3-pdf-preview-configuration">4.3. PDF Preview Configuration</h3> <p>Improve PDF preview with higher resolution:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">application/pdf</span><span>)</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Higher quality PDF preview (first page)</span></span> <span class="giallo-l"><span style="color: #B392F0;"> pdftoppm</span><span style="color: #79B8FF;"> -f 1 -l 1 -scale-to 1024 -singlefile -jpeg</span><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot; &quot;${</span><span>IMAGE_CACHE_PATH</span><span style="color: #F97583;">%</span><span style="color: #9ECBFF;">.</span><span style="color: #F97583;">*</span><span style="color: #9ECBFF;">}&quot;</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 6</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> exit 1</span></span> <span class="giallo-l"><span> ;;</span></span></code></pre><h3 id="4-4-office-documents-preview">4.4. Office Documents Preview</h3> <p>Add better support for office documents:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Office documents</span></span> <span class="giallo-l"><span style="color: #B392F0;">application/vnd.openxmlformats-officedocument.wordprocessingml.document</span><span style="color: #F97583;">|</span><span style="color: #B392F0;">application/vnd.oasis.opendocument.text</span><span>)</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Convert to plain text</span></span> <span class="giallo-l"><span style="color: #B392F0;"> docx2txt</span><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot; -</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 5</span></span> <span class="giallo-l"><span style="color: #B392F0;"> odt2txt</span><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 5</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> exit 1</span></span> <span class="giallo-l"><span> ;;</span></span> <span class="giallo-l"><span style="color: #B392F0;">application/vnd.openxmlformats-officedocument.spreadsheetml.sheet</span><span style="color: #F97583;">|</span><span style="color: #B392F0;">application/vnd.oasis.opendocument.spreadsheet</span><span>)</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Convert to CSV</span></span> <span class="giallo-l"><span style="color: #B392F0;"> xlsx2csv</span><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 5</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> exit 1</span></span> <span class="giallo-l"><span> ;;</span></span></code></pre><h3 id="4-5-archive-content-preview">4.5. Archive Content Preview</h3> <p>Enhance archive preview:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Archives</span></span> <span class="giallo-l"><span style="color: #B392F0;">application/zip</span><span style="color: #F97583;">|</span><span style="color: #B392F0;">application/x-rar</span><span style="color: #F97583;">|</span><span style="color: #B392F0;">application/x-7z-compressed</span><span style="color: #F97583;">|</span><span style="color: #B392F0;">application/x-tar</span><span style="color: #F97583;">|</span><span style="color: #B392F0;">application/x-bzip2</span><span style="color: #F97583;">|</span><span style="color: #B392F0;">application/x-gzip</span><span style="color: #F97583;">|</span><span style="color: #B392F0;">application/x-xz</span><span>)</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # List archive contents</span></span> <span class="giallo-l"><span style="color: #B392F0;"> atool</span><span style="color: #79B8FF;"> --list --</span><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 5</span></span> <span class="giallo-l"><span style="color: #B392F0;"> bsdtar</span><span style="color: #79B8FF;"> --list --file</span><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 5</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> exit 1</span></span> <span class="giallo-l"><span> ;;</span></span></code></pre><h3 id="4-6-syntax-highlighting-for-code">4.6. Syntax Highlighting for Code</h3> <p>Improve code syntax highlighting:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Syntax highlighting for code</span></span> <span class="giallo-l"><span style="color: #B392F0;">text/*</span><span>)</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Try to use pygmentize for syntax highlighting</span></span> <span class="giallo-l"><span style="color: #B392F0;"> env</span><span style="color: #9ECBFF;"> COLORTERM=8bit bat</span><span style="color: #79B8FF;"> --color=always --style=plain</span><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 5</span></span> <span class="giallo-l"><span style="color: #B392F0;"> pygmentize</span><span style="color: #79B8FF;"> -f</span><span style="color: #9ECBFF;"> terminal</span><span style="color: #79B8FF;"> -O</span><span style="color: #9ECBFF;"> style=monokai</span><span style="color: #79B8FF;"> -g</span><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 5</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Fallback to cat if pygmentize is not available</span></span> <span class="giallo-l"><span style="color: #B392F0;"> cat</span><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 5</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> exit 1</span></span> <span class="giallo-l"><span> ;;</span></span></code></pre> <hr /> <h2 id="5-advanced-customizations">5. Advanced Customizations</h2> <h3 id="5-1-custom-preview-size">5.1. Custom Preview Size</h3> <p>You can adjust the preview size by modifying your <code>rc.conf</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Add to ~/.config/ranger/rc.conf</span></span> <span class="giallo-l"><span style="color: #79B8FF;">set</span><span style="color: #9ECBFF;"> preview_images</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #79B8FF;">set</span><span style="color: #9ECBFF;"> preview_images_method kitty</span><span style="color: #6A737D;"> # or use: w3m, iterm2, terminology, urxvt, sixel</span></span> <span class="giallo-l"><span style="color: #79B8FF;">set</span><span style="color: #9ECBFF;"> preview_max_size</span><span style="color: #79B8FF;"> 10485760</span><span style="color: #6A737D;"> # Don&#39;t preview files larger than 10MB</span></span></code></pre><h3 id="5-2-font-preview">5.2. Font Preview</h3> <p>Add font preview capability:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Add to scope.sh under the case statement</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Note: This requires FontForge to be installed for the fontimage command</span></span> <span class="giallo-l"><span style="color: #B392F0;">font/*</span><span style="color: #F97583;">|</span><span style="color: #B392F0;">application/font*</span><span style="color: #F97583;">|</span><span style="color: #B392F0;">application/x-font*</span><span>)</span></span> <span class="giallo-l"><span> preview_png</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;/tmp/$(</span><span style="color: #B392F0;">basename</span><span style="color: #9ECBFF;"> &quot;${</span><span>IMAGE_CACHE_PATH</span><span style="color: #F97583;">%</span><span style="color: #9ECBFF;">.</span><span style="color: #F97583;">*</span><span style="color: #9ECBFF;">}&quot;).png&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #B392F0;"> fontimage</span><span style="color: #79B8FF;"> -o</span><span style="color: #9ECBFF;"> &quot;${</span><span>preview_png</span><span style="color: #9ECBFF;">}&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> --pixelsize</span><span style="color: #9ECBFF;"> &quot;120&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> --fontname \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> --pixelsize</span><span style="color: #9ECBFF;"> &quot;80&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> --text</span><span style="color: #9ECBFF;"> &quot; ABCDEFGHIJKLMNOPQRSTUVWXYZ &quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> --text</span><span style="color: #9ECBFF;"> &quot; abcdefghijklmnopqrstuvwxyz &quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> --text</span><span style="color: #9ECBFF;"> &quot; 0123456789.:,;(*!?&#39;) &quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> --text</span><span style="color: #9ECBFF;"> &quot; The quick brown fox jumps over the lazy dog. &quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span>;</span></span> <span class="giallo-l"><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #B392F0;"> convert</span><span style="color: #79B8FF;"> --</span><span style="color: #9ECBFF;"> &quot;${</span><span>preview_png</span><span style="color: #9ECBFF;">}&quot; &quot;${</span><span>IMAGE_CACHE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span> &amp;&amp;</span><span style="color: #B392F0;"> rm</span><span style="color: #9ECBFF;"> &quot;${</span><span>preview_png</span><span style="color: #9ECBFF;">}&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 6</span></span> <span class="giallo-l"><span style="color: #F97583;"> else</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> exit 1</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span> ;;</span></span></code></pre><h3 id="5-3-audio-file-preview">5.3. Audio File Preview</h3> <p>Add audio file metadata preview:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Add to scope.sh under the case statement</span></span> <span class="giallo-l"><span style="color: #B392F0;">audio/*</span><span>)</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Show audio metadata</span></span> <span class="giallo-l"><span style="color: #B392F0;"> mediainfo</span><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 5</span></span> <span class="giallo-l"><span style="color: #B392F0;"> exiftool</span><span style="color: #9ECBFF;"> &quot;${</span><span>FILE_PATH</span><span style="color: #9ECBFF;">}&quot;</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> exit 5</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> exit 1</span></span> <span class="giallo-l"><span> ;;</span></span></code></pre> <hr /> <h2 id="6-configuring-image-preview-methods">6. Configuring Image Preview Methods</h2> <p>Ranger supports several methods for displaying image previews in the terminal. You’ll need to configure both <code>scope.sh</code> and <code>rc.conf</code> to use them properly.</p> <h3 id="6-1-available-preview-methods">6.1. Available Preview Methods</h3> <p>Add this to your <code>rc.conf</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Choose one of these methods:</span></span> <span class="giallo-l"><span style="color: #79B8FF;">set</span><span style="color: #9ECBFF;"> preview_images</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #79B8FF;">set</span><span style="color: #9ECBFF;"> preview_images_method kitty</span><span style="color: #6A737D;"> # Options: kitty, ueberzug, w3m, iterm2, terminology, urxvt, sixel</span></span></code></pre> <p>Different methods work with different terminals:</p> <ul> <li><strong>kitty</strong>: For the kitty terminal</li> <li><strong>ueberzug</strong>: Works with most terminals (requires python-ueberzug)</li> <li><strong>w3m</strong>: Works with most terminals that support w3m</li> <li><strong>iterm2</strong>: For iTerm2 on macOS</li> <li><strong>terminology</strong>: For the Terminology terminal</li> <li><strong>urxvt</strong>: For urxvt with pixbuf support</li> <li><strong>sixel</strong>: For terminals with sixel support</li> </ul> <h3 id="6-2-installing-ueberzugpp-recommended">6.2. Installing UeberzugPP (Recommended)</h3> <p>For the best image preview experience across different terminals, install UeberzugPP. Note that the original Ueberzug project is no longer maintained, and UeberzugPP is the modern replacement with Wayland support:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># For Arch Linux (via AUR)</span></span> <span class="giallo-l"><span style="color: #B392F0;">yay</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> ueberzugpp</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># For other distributions (compile from source)</span></span> <span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> clone https://github.com/jstkdng/ueberzugpp.git</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> ueberzugpp</span></span> <span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #9ECBFF;"> build</span><span> &amp;&amp;</span><span style="color: #79B8FF;"> cd</span><span style="color: #9ECBFF;"> build</span></span> <span class="giallo-l"><span style="color: #B392F0;">cmake</span><span style="color: #79B8FF;"> -DCMAKE_BUILD_TYPE=Release</span><span style="color: #9ECBFF;"> ..</span></span> <span class="giallo-l"><span style="color: #B392F0;">make</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> make install</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Alternative: Install via pip (if available)</span></span> <span class="giallo-l"><span style="color: #B392F0;">pip</span><span style="color: #9ECBFF;"> install ueberzugpp</span></span></code></pre> <p>Then set in <code>rc.conf</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">set</span><span style="color: #9ECBFF;"> preview_images</span><span style="color: #79B8FF;"> true</span></span> <span class="giallo-l"><span style="color: #79B8FF;">set</span><span style="color: #9ECBFF;"> preview_images_method ueberzug</span></span></code></pre> <p>Note: Even though we’re using UeberzugPP, the method name in ranger’s configuration remains <code>ueberzug</code> for compatibility.</p> <hr /> <h2 id="7-testing-your-configuration">7. Testing Your Configuration</h2> <p>After making changes to <code>scope.sh</code>, restart ranger and test the preview functionality:</p> <ol> <li>Navigate to different file types</li> <li>Check if the previews are displayed correctly</li> <li>Adjust the configuration as needed</li> </ol> <h3 id="7-1-debugging-preview-issues">7.1. Debugging Preview Issues</h3> <p>If previews aren’t working as expected:</p> <ol> <li> <p>Run ranger with the <code>--debug</code> flag:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">ranger</span><span style="color: #79B8FF;"> --debug</span></span></code></pre></li> <li> <p>Check the output for errors related to the preview script</p> </li> <li> <p>Make sure all required dependencies are installed</p> </li> <li> <p>Verify that <code>scope.sh</code> is executable</p> </li> </ol> <hr /> <h2 id="8-practical-examples">8. Practical Examples</h2> <h3 id="8-1-image-gallery-browsing">8.1. Image Gallery Browsing</h3> <p>With proper image preview configuration, you can use ranger as an image browser:</p> <ol> <li>Navigate to a directory with images</li> <li>Use arrow keys to browse through images</li> <li>See high-quality previews directly in the terminal</li> </ol> <h3 id="8-2-code-review">8.2. Code Review</h3> <p>With syntax highlighting enabled:</p> <ol> <li>Navigate to source code files</li> <li>See syntax-highlighted code in the preview pane</li> <li>Quickly scan through multiple files</li> </ol> <h3 id="8-3-document-management">8.3. Document Management</h3> <p>With document preview support:</p> <ol> <li>Browse through PDF documents</li> <li>See previews of the first page</li> <li>View plain text content of office documents</li> </ol> <hr /> <h2 id="9-troubleshooting">9. Troubleshooting</h2> <h3 id="9-1-missing-dependencies">9.1. Missing Dependencies</h3> <p>If certain file types don’t preview correctly, you might be missing dependencies:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Check if a command is available</span></span> <span class="giallo-l"><span style="color: #79B8FF;">which</span><span style="color: #9ECBFF;"> ffmpegthumbnailer</span></span> <span class="giallo-l"><span style="color: #79B8FF;">which</span><span style="color: #9ECBFF;"> convert</span></span> <span class="giallo-l"><span style="color: #79B8FF;">which</span><span style="color: #9ECBFF;"> pdftoppm</span></span></code></pre> <p>Install any missing tools using your package manager.</p> <h3 id="9-2-terminal-compatibility">9.2. Terminal Compatibility</h3> <p>Not all terminals support all preview methods:</p> <ul> <li>If images don’t display, try a different <code>preview_images_method</code> in <code>rc.conf</code></li> <li>For kitty terminal, make sure you’re using the kitty method</li> <li>For other terminals, try ueberzug or w3m</li> </ul> <h3 id="9-3-large-files">9.3. Large Files</h3> <p>If ranger becomes slow when previewing large files:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Add to rc.conf</span></span> <span class="giallo-l"><span style="color: #79B8FF;">set</span><span style="color: #9ECBFF;"> preview_max_size</span><span style="color: #79B8FF;"> 5242880</span><span style="color: #6A737D;"> # Don&#39;t preview files larger than 5MB</span></span></code></pre> <hr /> <h2 id="summary">Summary</h2> <p>With these customizations to ranger’s preview system, you’ve enhanced your terminal file manager with rich media preview capabilities:</p> <p>✅ High-quality image previews ✅ Video thumbnails ✅ PDF document previews ✅ Office document text extraction ✅ Syntax highlighting for code ✅ Archive content listing ✅ Font previews</p> <p>This setup transforms ranger from a simple file manager into a powerful media browser that lets you quickly preview and navigate through various file types without leaving your terminal.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;ranger&#x2F;ranger&#x2F;wiki&#x2F;Image-Previews" class="retro-button"> <span class="emoji">🖼️</span><span class="button-text">RANGER IMAGE PREVIEWS</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;ranger&#x2F;ranger&#x2F;wiki&#x2F;Custom-Commands" class="retro-button"> <span class="emoji">🔧</span><span class="button-text">RANGER CUSTOM COMMANDS</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;seebye&#x2F;ueberzug" class="retro-button"> <span class="emoji">📚</span><span class="button-text">UEBERZUG DOCUMENTATION</span> </a> </p> The Ultimate Guide to Email Encryption with OpenPGP Tue, 15 Jul 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/e-mail-encryption-with-openpgp/ https://criticalbasics.xyz/posts/e-mail-encryption-with-openpgp/ <p>This guide provides a comprehensive, “terminal-first” approach to setting up robust end-to-end email encryption. By creating your cryptographic keys directly with GnuPG, you build a universal and secure foundation. We will then show you how to integrate this setup seamlessly with both Thunderbird, a user-friendly graphical client, and Neomutt, a powerful terminal-based client.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-07-15</td><td><strong>Major Restructure (Terminal-First):</strong> The entire guide was rewritten to prioritize key creation in the terminal (<code>gpg</code>), making it more robust, universal, and secure. This resolves platform-specific client issues.</td></tr> <tr><td>2025-07-15</td><td><strong>Initial Version:</strong> Article created.</td></tr> </tbody></table> </div> <hr /> <h2 id="1-pre-flight-check-your-system-s-foundation">1. Pre-Flight Check – Your System’s Foundation</h2> <p>Before we create any keys, we must ensure your system is correctly configured.</p> <h3 id="1-1-install-gnupg">1.1. Install GnuPG</h3> <p>This is the core encryption engine.</p> <ul> <li><strong>Debian/Ubuntu:</strong> <code>sudo apt update &amp;&amp; sudo apt install gnupg</code></li> <li><strong>Arch Linux:</strong> <code>sudo pacman -Syu gnupg</code></li> </ul> <h3 id="part-1-2">1.2. Install and Configure <code>pinentry</code></h3> <p>When a program needs your key’s passphrase, GPG uses a helper application called <code>pinentry</code> to display a secure prompt. You must choose the right one for your environment.</p> <p><strong>Step 1: Choose and Install the Right <code>pinentry</code> for Your Environment</strong></p> <ul> <li> <p><strong>For standard Desktop Environments (GNOME, KDE, XFCE, etc.):</strong> A graphical pop-up is the default. Install the appropriate package:</p> <ul> <li><strong>GNOME:</strong> <code>sudo apt install pinentry-gnome3</code></li> <li><strong>KDE Plasma:</strong> <code>sudo apt install pinentry-qt</code></li> <li><strong>Arch Linux (most desktops):</strong> <code>sudo pacman -S pinentry</code></li> </ul> </li> <li> <p><strong>For Tiling Window Managers (i3wm, sway, etc.) or Terminal-Enthusiasts (Recommended):</strong> A graphical <code>pinentry</code> can “grab” focus and freeze your desktop. The terminal-based <code>pinentry-curses</code> is a much better solution as it runs directly in your terminal, allowing you to switch windows normally.</p> <ul> <li><strong>Debian/Ubuntu:</strong> <code>sudo apt install pinentry-curses</code></li> <li><strong>Arch Linux:</strong> <code>pinentry</code> is already included in the <code>pinentry</code> package.</li> </ul> </li> </ul> <p><strong>Step 2: Tell the GPG Agent Which Program to Use</strong> We will now edit the GPG Agent configuration file.</p> <ol> <li> <p>Open the file with a terminal editor:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">nano</span><span style="color: #9ECBFF;"> ~/.gnupg/gpg-agent.conf</span></span></code></pre></li> <li> <p><strong>Inside the <code>nano</code> editor,</strong> add <strong>ONE</strong> of the following lines, depending on your choice in Step 1. Ensure the other line is deleted or commented out with a <code>#</code>.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #6A737D;"># For a terminal-based prompt (i3wm, sway - HIGHLY RECOMMENDED for this setup)</span></span> <span class="giallo-l"><span>pinentry-program /usr/bin/pinentry-curses</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># For a graphical prompt (GNOME, KDE, etc.)</span></span> <span class="giallo-l"><span style="color: #6A737D;"># pinentry-program /usr/bin/pinentry-gnome3</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span>default-cache-ttl 600</span></span> <span class="giallo-l"><span>max-cache-ttl 7200</span></span></code></pre> <p><em>Note: Verify the correct path with <code>which pinentry-gnome3</code> or <code>which pinentry-curses</code> if needed.</em></p> </li> <li> <p>Save the file and exit <code>nano</code> (<code>Ctrl+X</code>, then <code>Y</code>, then <code>Enter</code>).</p> </li> <li> <p>Reload the agent to apply the new configuration:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gpg-connect-agent</span><span style="color: #9ECBFF;"> reloadagent /bye</span></span></code></pre></li> </ol> <hr /> <h2 id="part-2">2. Creating Your Master Key in the Terminal</h2> <p>We will now create your OpenPGP key using the recommended interactive process.</p> <ol> <li> <p><strong>Start the key generation process:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gpg</span><span style="color: #79B8FF;"> --full-generate-key</span></span></code></pre></li> <li> <p><strong>Follow the prompts.</strong> The recommended choices are secure and robust:</p> <ul> <li><strong>Key Type:</strong> Select <strong><code>(1) RSA and RSA</code></strong>.</li> <li><strong>Key Size:</strong> Enter <strong><code>4096</code></strong> bits.</li> <li><strong>Expiration Date:</strong> Enter <strong><code>2y</code></strong> (for 2 years). Keys should expire. This is a critical safety net that limits potential damage if a key is ever lost. Don’t worry, you can easily extend the validity before it expires, as shown in Part 3.5.</li> <li><strong>Confirm</strong> that the expiration date is correct by typing <strong><code>y</code></strong>.</li> </ul> </li> <li> <p><strong>Provide Your User ID:</strong></p> <ul> <li><strong>Real name:</strong> Enter your full name.</li> <li><strong>Email address:</strong> Enter the email address for this key.</li> <li><strong>Comment:</strong> You can leave this blank.</li> <li><strong>Confirm</strong> your details by typing <strong><code>O</code></strong> (for Okay).</li> </ul> </li> <li> <p><strong>Set Your Passphrase:</strong> A secure prompt will now appear (thanks to <code>pinentry</code>!). This will be the master password for your new private key.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ PASSPHRASE QUALITY IS CRITICAL </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>A weak passphrase makes your encrypted data vulnerable. Consider using a method like <strong>Diceware</strong> to generate a sequence of random words. If you lose this passphrase, you lose access to all data encrypted with this key permanently.</p> </td> </tr> </table> </li> </ol> <p>Congratulations, you have successfully created a secure, command-line-native OpenPGP key!</p> <hr /> <h2 id="part-3">3. Essential Security Practices (Don’t Skip This!)</h2> <p>Immediately after creation, you must secure your new key for long-term use.</p> <h3 id="3-1-identifying-your-key-the-key-id">3.1. Identifying Your Key: The Key-ID</h3> <p>From this point forward, we will use your key’s unique <strong>Key-ID</strong> to refer to it. This avoids any confusion if you ever have multiple keys for the same email address.</p> <ol> <li><strong>Find Your Key-ID:</strong> Run the following command.<pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gpg</span><span style="color: #79B8FF;"> --list-secret-keys --keyid-format</span><span style="color: #9ECBFF;"> LONG</span></span></code></pre></li> <li><strong>Identify the ID:</strong> In the output <code>sec rsa4096/YOUR-KEY-ID ...</code>, the <code>YOUR-KEY-ID</code> is the long string of characters you will use in all subsequent commands.</li> </ol> <h3 id="3-2-backup-your-private-key">3.2. Backup Your Private Key</h3> <p>A backup is not a backup until it’s tested. Use your newly found Key-ID here.</p> <ol> <li><strong>Create the Backup:</strong><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">umask 077</span><span> &amp;&amp;</span><span style="color: #B392F0;"> gpg</span><span style="color: #79B8FF;"> --export-secret-keys --armor</span><span style="color: #9ECBFF;"> YOUR-KEY-ID</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> private-key-backup.asc</span></span></code></pre></li> <li><strong>Verify the Backup:</strong><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gpg</span><span style="color: #79B8FF;"> --dry-run --import</span><span style="color: #9ECBFF;"> private-key-backup.asc</span></span></code></pre>If this command runs without errors, your backup is valid. Now, store the <code>.asc</code> file in one or more <strong>extremely secure, offline locations</strong>.</li> </ol> <h3 id="3-3-create-a-revocation-certificate">3.3. Create a Revocation Certificate</h3> <p>This is your emergency button. Use your Key-ID to specify which key to revoke.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #79B8FF;">umask 077</span><span> &amp;&amp;</span><span style="color: #B392F0;"> gpg</span><span style="color: #79B8FF;"> --gen-revoke --armor</span><span style="color: #9ECBFF;"> YOUR-KEY-ID</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> revocation-cert.asc</span></span></code></pre> <p>Store this file as securely as your private key backup.</p> <h3 id="3-4-verify-keys-and-build-your-web-of-trust-the-core-of-pgp-s-security">3.4. Verify Keys and Build Your Web of Trust: The Core of PGP’s Security</h3> <p>This section is conceptually the most important part of the entire guide. It explains how you can be sure a public key truly belongs to the person it claims to.</p> <h4 id="what-is-the-fingerprint">What is the Fingerprint?</h4> <p>When you run the command <code>gpg --fingerprint YOUR-KEY-ID</code>, you get an output like this:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>$ gpg --fingerprint 8A738464A2144E4C</span></span> <span class="giallo-l"><span>pub rsa4096 2025-07-29 [SC] [expires: 2027-07-29]</span></span> <span class="giallo-l"><span> 4A9E 9A72 85F5 F569 C17C 299B 8A73 8464 A214 4E4C</span></span> <span class="giallo-l"><span>uid [ultimate] Delightful Dude &lt;delightfuldude@criticalbasics.xyz&gt;</span></span> <span class="giallo-l"><span>sub rsa4096 2025-07-29 [E] [expires: 2027-07-29]</span></span></code></pre> <p>The <strong>Fingerprint</strong> is the long line of 40 hexadecimal characters (often displayed in 10 blocks of 4 characters). It is like a human fingerprint: absolutely unique to this specific key. This is your key’s “ID card.”</p> <h4 id="the-verification-process-a-practical-example">The Verification Process: A Practical Example</h4> <p>Imagine you want to communicate securely with your friend, Anna.</p> <p><strong>Step 1: You acquire Anna’s public key.</strong> Anna has published her key on her website (Method 4.1) or a keyserver (Method 4.2). You import it.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Example: You import Anna&#39;s key from her website</span></span> <span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -sL</span><span style="color: #9ECBFF;"> https://anna.example.com/public.asc</span><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> gpg</span><span style="color: #79B8FF;"> --import</span></span></code></pre> <p><strong>Step 2: You check the key’s status.</strong> Now, you view the fingerprint of Anna’s key in your keyring.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gpg</span><span style="color: #79B8FF;"> --fingerprint</span><span style="color: #9ECBFF;"> anna@example.com</span></span></code></pre> <p>The output will contain a line that looks like this: <code>uid [ unknown ] Anna Miller &lt;anna@example.com&gt;</code></p> <p>The <code>[ unknown ]</code> part is critical. It means: “I have this key, but I have absolutely no idea if it really belongs to Anna or to an attacker impersonating her.”</p> <p><strong>Step 3: The actual verification (the human part).</strong> To be sure, you must compare the fingerprint with Anna over a <strong>different, trusted channel</strong>. This is the most important step to prevent man-in-the-middle attacks.</p> <ul> <li>You meet Anna in person.</li> <li>You call Anna or have a video call (with someone whose voice or face you recognize).</li> </ul> <p>During the conversation, the following happens:</p> <ul> <li><strong>You say:</strong> “Anna, I’m going to read you the fingerprint I have for your key. Does it start with 1234 ABCD…?”</li> <li><strong>Anna says:</strong> “Yes, that’s correct. And does yours start with 0FDA EF41…?”</li> <li><strong>You say:</strong> “Yes, it does.”</li> </ul> <p>Now you both have certainty that you possess each other’s authentic key.</p> <p><strong>Step 4: Sign the key (digitally record your trust).</strong> After verifying the key, you tell your GnuPG that you trust it. You do this by signing the foreign key with your own private key.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gpg</span><span style="color: #79B8FF;"> --sign-key</span><span style="color: #9ECBFF;"> anna@example.com</span></span></code></pre> <p>GPG will show you Anna’s fingerprint again and ask if you are really sure. Confirm with <code>y</code>. You will need to enter your passphrase to authorize the signature with your private key.</p> <p><strong>Step 5: Check the result.</strong> Run the fingerprint command again:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gpg</span><span style="color: #79B8FF;"> --fingerprint</span><span style="color: #9ECBFF;"> anna@example.com</span></span></code></pre> <p>The output has now changed: <code>uid [ full ] Anna Miller &lt;anna@example.com&gt;</code></p> <p>The <code>[ full ]</code> is your personal note: “I have personally verified this key. It’s authentic. I trust it completely.”</p> <p>Through this process, you build your personal <strong>“Web of Trust”</strong>. If you trust Anna’s key, and Anna in turn trusts Bob’s key, you have a reason to lend some level of trust to Bob’s key as well.</p> <h3 id="3-5-extending-your-key-s-validity-key-renewal">3.5. Extending Your Key’s Validity (Key Renewal)</h3> <p>An expiring key is a feature, not a problem. You do <strong>NOT</strong> need to start over. You can easily extend its life before it expires.</p> <ol> <li><strong>Start the Key-Editing Process:</strong><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gpg</span><span style="color: #79B8FF;"> --edit-key</span><span style="color: #9ECBFF;"> YOUR-KEY-ID</span></span></code></pre></li> <li><strong>Extend the Expiration Date:</strong> Inside the GPG prompt, type <code>expire</code>, enter a new duration (e.g., <code>2y</code>), and confirm.</li> <li><strong>Save Your Changes:</strong><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>gpg&gt; save</span></span></code></pre></li> <li><strong>Distribute Your Updated Key:</strong> You must re-publish your updated public key.<pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gpg</span><span style="color: #79B8FF;"> --keyserver</span><span style="color: #9ECBFF;"> hkps://keys.openpgp.org</span><span style="color: #79B8FF;"> --send-keys</span><span style="color: #9ECBFF;"> YOUR-KEY-ID</span></span></code></pre>Also, send a newly signed email with your updated public key attached to your most important contacts.</li> </ol> <hr /> <h2 id="part-4">4. Making Your Key Discoverable (Optional)</h2> <p>A public key that only exists on your computer is like a phone number you never give out. For others to send you encrypted mail easily, you should distribute your public key.</p> <h3 id="4-1-method-1-the-gold-standard-your-personal-website">4.1. Method 1: The Gold Standard - Your Personal Website</h3> <p>This is the most secure and authoritative method. You establish a “source of truth” that you control, avoiding issues with public servers.</p> <ol> <li><strong>Export your public key:</strong><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gpg</span><span style="color: #79B8FF;"> --export --armor</span><span style="color: #9ECBFF;"> YOUR-KEY-ID</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;"> public.asc</span></span></code></pre></li> <li><strong>Upload the <code>public.asc</code> file to your website,</strong> for example, to <code>https://your-website.com/public.asc</code>.</li> </ol> <h3 id="4-2-method-2-the-convenient-way-public-keyservers">4.2. Method 2: The Convenient Way - Public Keyservers</h3> <p>This method is more convenient but involves a trade-off with privacy.</p> <ul> <li><strong>Security Risk: NO.</strong> You only upload your <strong>public</strong> key.</li> <li><strong>Privacy Risk: YES.</strong> This publicly associates your email with PGP usage.</li> </ul> <p><strong>The Solution: Use a Modern, Privacy-Respecting Keyserver.</strong> This is why we exclusively recommend <code>keys.openpgp.org</code>. It requires your consent via email verification to publish your key.</p> <ol> <li><strong>Send Your Key to the Server:</strong><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gpg</span><span style="color: #79B8FF;"> --keyserver</span><span style="color: #9ECBFF;"> hkps://keys.openpgp.org</span><span style="color: #79B8FF;"> --send-keys</span><span style="color: #9ECBFF;"> YOUR-KEY-ID</span></span></code></pre></li> <li><strong>Check Your Email:</strong> The keyserver will send you a verification email. You <strong>must click the link</strong> to finalize the publication.</li> </ol> <hr /> <h2 id="5-going-public-your-contact-page-and-email-signature">5. Going Public: Your Contact Page and Email Signature</h2> <p>Now that you have ways to distribute your key, you need to tell people about them.</p> <h3 id="5-1-on-your-website-s-contact-page">5.1. On Your Website’s Contact Page</h3> <p>Add a section like this to your contact page. It provides clear instructions for everyone.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="html"><span class="giallo-l"><span>&lt;</span><span style="color: #85E89D;">h3</span><span>&gt;Digital Contact &amp; Verification&lt;/</span><span style="color: #85E89D;">h3</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;</span><span style="color: #85E89D;">p</span><span>&gt;&lt;</span><span style="color: #85E89D;">strong</span><span>&gt;E-Mail:&lt;/</span><span style="color: #85E89D;">strong</span><span>&gt; your.name@example.com&lt;/</span><span style="color: #85E89D;">p</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;</span><span style="color: #85E89D;">p</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">strong</span><span>&gt;OpenPGP Key:&lt;/</span><span style="color: #85E89D;">strong</span><span>&gt; For encrypted communication, you can get my public key here:</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">ul</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">li</span><span>&gt;&lt;</span><span style="color: #85E89D;">a</span><span style="color: #B392F0;"> href</span><span>=</span><span style="color: #9ECBFF;">&quot;/public.asc&quot;</span><span style="color: #B392F0;"> download</span><span>&gt;Download Public Key&lt;/</span><span style="color: #85E89D;">a</span><span>&gt;&lt;/</span><span style="color: #85E89D;">li</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">li</span><span>&gt;&lt;</span><span style="color: #85E89D;">strong</span><span>&gt;Or import via command line:&lt;/</span><span style="color: #85E89D;">strong</span><span>&gt;&lt;</span><span style="color: #85E89D;">br</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">code</span><span>&gt;curl -sL https://your-website.com/public.asc | gpg --import&lt;/</span><span style="color: #85E89D;">code</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span style="color: #85E89D;">li</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span style="color: #85E89D;">ul</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">strong</span><span>&gt;Fingerprint for Verification:&lt;/</span><span style="color: #85E89D;">strong</span><span>&gt;&lt;</span><span style="color: #85E89D;">br</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">code</span><span>&gt;YOUR FINGERPRINT IN 4-DIGIT BLOCKS&lt;/</span><span style="color: #85E89D;">code</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;/</span><span style="color: #85E89D;">p</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;</span><span style="color: #85E89D;">p</span><span>&gt;&lt;</span><span style="color: #85E89D;">em</span><span>&gt;Policy: All legitimate emails from me will be digitally signed with this key.&lt;/</span><span style="color: #85E89D;">em</span><span>&gt;&lt;/</span><span style="color: #85E89D;">p</span><span>&gt;</span></span></code></pre><h3 id="5-2-in-your-email-signature">5.2. In Your Email Signature</h3> <p>A compact, professional signature in every email reinforces trust and makes verification easy.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>-- </span></span> <span class="giallo-l"><span>Your Name</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Website &amp; PGP Key: https://your-website.com/contact</span></span> <span class="giallo-l"><span>GPG Fingerprint: YOUR FINGERPRINT IN 4-DIGIT BLOCKS</span></span></code></pre> <p>This signature doesn’t overload the email but provides everything a recipient needs to verify your identity and find your key.</p> <hr /> <h2 id="part-6">6. Integration with Thunderbird</h2> <p>Once your key is created via the terminal, you need to tell Thunderbird to use it for your email account.</p> <ol> <li>In Thunderbird, open the <strong>Account Settings</strong> (via the “Hamburger” menu or <code>Tools</code> -&gt; <code>Account Settings</code>).</li> <li>In the left-hand sidebar, select the email account you want to secure (e.g., <code>delightfuldude@criticalbasics.xyz</code>).</li> <li>Click on the <strong>End-To-End Encryption</strong> sub-menu for that account.</li> </ol> <p>Now, you have two possible scenarios:</p> <h4 id="scenario-a-thunderbird-automatically-finds-your-key">Scenario A: Thunderbird Automatically Finds Your Key</h4> <p>If you’re lucky, Thunderbird has already detected the key you created in the terminal. You will see it listed and can select it directly from the dropdown menu to associate it with your account. If so, you’re done!</p> <h4 id="scenario-b-the-key-is-not-listed-manual-import">Scenario B: The Key is Not Listed (Manual Import)</h4> <p>More often, Thunderbird doesn’t immediately find externally created keys. If your key is not in the list, you must import it manually.</p> <ol> <li>In the same settings window, click the <strong>OpenPGP Key Manager…</strong> button.</li> <li>A new “OpenPGP Key Manager” window will open. In its menu, go to <strong>File</strong> -&gt; <strong>Import Secret Key(s) From File…</strong>.</li> <li>A file dialog will open. Navigate to and select the <code>private.asc</code> file you exported in <a href="https://criticalbasics.xyz/posts/e-mail-encryption-with-openpgp/#part-4"><strong>Part 4</strong></a>.</li> <li>You will be prompted for the passphrase you created for your key. Enter it to complete the import.</li> <li>After a successful import, your new key will appear in the Key Manager list. You can now close this window.</li> <li>Back in the <strong>Account Settings</strong>, your newly imported key should now be available in the dropdown menu. Select it to finalize the setup.</li> </ol> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ FURTHER HELP </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>For more detailed questions or troubleshooting, Mozilla provides an extensive FAQ page that is highly recommended:</p> <ul> <li><strong><a rel="noopener external" target="_blank" href="https://support.mozilla.org/en-US/kb/openpgp-thunderbird-howto-and-faq">Official Thunderbird Help: OpenPGP HOWTO and FAQ</a></strong></li> </ul> </td> </tr> </table> <hr /> <h2 id="7-integration-with-neomutt">7. Integration with Neomutt</h2> <h3 id="7-1-neomutt-configuration">7.1. Neomutt Configuration</h3> <p>Add these settings to <code>~/.config/neomutt/muttrc</code>, using your unique Key-ID.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #6A737D;"># --- GPG/PGP Settings for Neomutt ---</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_verify_sig</span><span> = yes</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_good_sign</span><span> =</span><span style="color: #9ECBFF;"> &quot;✅ Good OpenPGP signature from&quot;</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_autosign</span><span> = yes</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_replyencrypt</span><span> = yes</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_replysign</span><span> = yes</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Für neuere Neomutt-Versionen:</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_replysign_encrypted</span><span> = yes</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Für ältere Neomutt-Versionen (falls obige Option einen Fehler verursacht):</span></span> <span class="giallo-l"><span style="color: #6A737D;"># set crypt_replysign = yes</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Use the Key-ID followed by an exclamation mark!</span></span> <span class="giallo-l"><span style="color: #6A737D;"># This tells GPG to use *exactly* this key.</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_sign_as</span><span> =</span><span style="color: #9ECBFF;"> &quot;YOUR-KEY-ID!&quot;</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_timeout</span><span> = 300</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_show_unusable</span><span> = no</span></span></code></pre> <hr /> <h2 id="8-advanced-topic-handling-multiple-accounts">8. Advanced Topic: Handling Multiple Accounts</h2> <p>For maximum security, use <strong>separate OpenPGP keys for each email account</strong>. This provides strong separation between your digital identities. This section covers the setup for Thunderbird and two common approaches for Neomutt.</p> <p><strong>Create Keys:</strong> For each identity (e.g., private, work), <strong>repeat the process in <a href="https://criticalbasics.xyz/posts/e-mail-encryption-with-openpgp/#part-2">Part 2</a></strong> to generate a new, dedicated key. Make sure to use the correct name and email address for each.</p> <h3 id="8-1-thunderbird-integration">8.1. Thunderbird Integration</h3> <p>For each account you have set up in Thunderbird, follow <a href="https://criticalbasics.xyz/posts/e-mail-encryption-with-openpgp/#part-6"><strong>Part 6</strong></a> to assign the correct existing key to the corresponding email address. Thunderbird handles the mapping automatically.</p> <h3 id="8-2-neomutt-integration-two-approaches">8.2. Neomutt Integration: Two Approaches</h3> <p>For Neomutt, you can either switch accounts automatically based on the folder you are in, or manually via keyboard shortcuts.</p> <h4 id="method-a-automatic-switching-with-folder-hooks">Method A: Automatic Switching with Folder-Hooks</h4> <p>This method uses <code>folder-hook</code> to automatically load the correct account configuration (including the PGP key) when you enter a specific mailbox.</p> <p><strong>Step 1: Create the Directory Structure</strong> First, organize your account configurations in a dedicated directory.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.config/neomutt/accounts</span></span></code></pre> <p><strong>Step 2: Configure the Main <code>muttrc</code> for Hooks</strong> Your main <code>~/.config/neomutt/muttrc</code> will now act as a loader. Add the PGP defaults (if not already present) and the hooks.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #6A737D;"># --- PGP Defaults (add to your main muttrc) ---</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_timeout</span><span> = 300</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_verify_sig</span><span> = yes</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_good_sign</span><span> =</span><span style="color: #9ECBFF;"> &quot;✅ Good OpenPGP signature from&quot;</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_show_unusable</span><span> = no</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Für neuere Neomutt-Versionen:</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_replysign_encrypted</span><span> = yes</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Für ältere Neomutt-Versionen (falls obige Option einen Fehler verursacht):</span></span> <span class="giallo-l"><span style="color: #6A737D;"># set crypt_replysign = yes</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># --- Account Hooks ---</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Load a specific config file when you enter a folder.</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Replace the imap paths with your actual server paths.</span></span> <span class="giallo-l"><span>folder-hook </span><span style="color: #9ECBFF;">&#39;imaps://private@mail.com/&#39; &#39;source ~/.config/neomutt/accounts/private.muttrc&#39;</span></span> <span class="giallo-l"><span>folder-hook </span><span style="color: #9ECBFF;">&#39;imaps://work@company.com/&#39; &#39;source ~/.config/neomutt/accounts/work.muttrc&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Load a default account when Neomutt starts</span></span> <span class="giallo-l"><span>source ~/.config/neomutt/accounts/private.muttrc</span></span></code></pre> <p><strong>Step 3: Create Per-Account Configuration Files</strong> Create a separate file for each account inside <code>~/.config/neomutt/accounts/</code>. This is where you set the PGP key for each identity.</p> <p><strong>Example: <code>~/.config/neomutt/accounts/private.muttrc</code></strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #6A737D;"># --- Account: Private ---</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">from</span><span> =</span><span style="color: #9ECBFF;"> &quot;private@mail.com&quot;</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">realname</span><span> =</span><span style="color: #9ECBFF;"> &quot;Your Name (Private)&quot;</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_sign_as</span><span> =</span><span style="color: #9ECBFF;"> &quot;YOUR-PRIVATE-KEY-ID!&quot;</span><span style="color: #6A737D;"> # Get ID from Part 3</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_autosign</span><span> = yes</span></span> <span class="giallo-l"><span style="color: #6A737D;"># ... your private imap_user, imap_pass, smtp_url, etc. go here</span></span></code></pre><h4 id="method-b-manual-switching-for-mutt-wizard-users">Method B: Manual Switching (for <code>mutt-wizard</code> users)</h4> <p>Many users rely on the popular <a rel="noopener external" target="_blank" href="https://github.com/LukeSmithxyz/mutt-wizard"><code>mutt-wizard</code></a> script, which favors manual account switching via macros. If your <code>muttrc</code> contains lines like <code>macro index,pager i1 'source ...'</code>, this method is for you.</p> <p><strong>Step 1: Locate Your Account Files</strong> <code>mutt-wizard</code> creates a separate configuration file for each of your accounts, typically located in <code>~/.config/mutt/accounts/</code>.</p> <p><strong>Step 2: Add <code>pgp_sign_as</code> to Each Account File</strong> For each account, edit its corresponding file and add the <code>pgp_sign_as</code> line to tell Neomutt which PGP key to use.</p> <ol> <li> <p>Get the <strong>Key-ID</strong> for the key you want to use with this account (as described in <a href="https://criticalbasics.xyz/posts/e-mail-encryption-with-openpgp/#part-3">Part 3</a>).</p> </li> <li> <p>Open the account’s configuration file (e.g., <code>~/.config/mutt/accounts/delightfuldude@criticalbasics.xyz.muttrc</code>).</p> </li> <li> <p>Add the following line, replacing <code>YOUR-KEY-ID!</code> with the actual ID:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #6A737D;"># Inside e.g., ~/.config/mutt/accounts/delightfuldude@criticalbasics.xyz.muttrc</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># ... existing settings like &#39;set from&#39;, &#39;set realname&#39;, etc.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Add this line to set the default PGP signing key for this account</span></span> <span class="giallo-l"><span>set </span><span style="color: #F97583;">pgp_sign_as</span><span> = YOUR-CRITICALBASICS-KEY-ID!</span></span></code></pre></li> </ol> <p><strong>Result:</strong> Now, when you use your keyboard macros (e.g., <code>i1</code>, <code>i2</code>) to switch accounts, Neomutt will load the correct email settings and automatically select the right PGP key for signing. Your existing workflow remains unchanged but is now PGP-aware.</p> <h2 id="9-transferring-your-configuration-between-computers">9. Transferring Your Configuration Between Computers</h2> <p>One of the most common questions is: “How can I use my OpenPGP setup on multiple computers without repeating this entire tutorial?” The good news is that you can transfer your configuration between computers quite easily.</p> <h3 id="9-1-what-files-to-transfer">9.1. What Files to Transfer</h3> <p>The most important directory is <code>~/.gnupg/</code>, which contains:</p> <ul> <li>Your private and public keys</li> <li>GPG Agent configuration</li> <li>Trust database (Web of Trust)</li> </ul> <p>Additionally, depending on your email client:</p> <ul> <li><strong>Thunderbird</strong>: Thunderbird accesses the GnuPG keyring directly, so transferring the <code>.gnupg</code> directory is sufficient.</li> <li><strong>Neomutt</strong>: You’ll also need to copy your configuration files: <ul> <li><code>~/.config/neomutt/muttrc</code></li> <li><code>~/.config/neomutt/accounts/</code> (if you have multiple accounts)</li> </ul> </li> </ul> <h3 id="9-2-transfer-process">9.2. Transfer Process</h3> <ol> <li> <p><strong>Secure Transfer</strong>: Use a secure channel for transferring these files (encrypted USB drive, encrypted file transfer).</p> </li> <li> <p><strong>Copy the Directory</strong>: Copy the entire <code>.gnupg</code> directory to the same location on the target computer.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># On the source computer, create a secure backup</span></span> <span class="giallo-l"><span style="color: #B392F0;">tar</span><span style="color: #79B8FF;"> -czf</span><span style="color: #9ECBFF;"> gnupg-backup.tar.gz</span><span style="color: #79B8FF;"> -C</span><span style="color: #9ECBFF;"> ~ .gnupg</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Transfer securely to the target computer and extract</span></span> <span class="giallo-l"><span style="color: #6A737D;"># On the target computer:</span></span> <span class="giallo-l"><span style="color: #B392F0;">tar</span><span style="color: #79B8FF;"> -xzf</span><span style="color: #9ECBFF;"> gnupg-backup.tar.gz</span><span style="color: #79B8FF;"> -C</span><span style="color: #9ECBFF;"> ~</span></span></code></pre></li> <li> <p><strong>Fix Permissions</strong>: After transferring, ensure proper permissions:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">chmod</span><span style="color: #79B8FF;"> 700</span><span style="color: #9ECBFF;"> ~/.gnupg</span></span> <span class="giallo-l"><span style="color: #B392F0;">chmod</span><span style="color: #79B8FF;"> 600</span><span style="color: #9ECBFF;"> ~/.gnupg/</span><span style="color: #79B8FF;">*</span></span></code></pre></li> <li> <p><strong>Adjust Pinentry Configuration</strong>: If the target system has a different desktop environment, you may need to modify the <code>pinentry-program</code> path in <code>~/.gnupg/gpg-agent.conf</code>.</p> </li> <li> <p><strong>Reload GPG Agent</strong>: After transferring, reload the GPG agent:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gpg-connect-agent</span><span style="color: #9ECBFF;"> reloadagent /bye</span></span></code></pre></li> <li> <p><strong>Verify the Setup</strong>: Test that your keys are available:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">gpg</span><span style="color: #79B8FF;"> --list-secret-keys</span></span></code></pre></li> </ol> <p>By following these steps, you can efficiently use your OpenPGP setup across multiple computers without repeating the entire configuration process.</p> <h2 id="10-quick-troubleshooting">10. Quick Troubleshooting</h2> <div class="styled-table-container"> <table id="custom-table" > <colgroup> <col width="40%"> <col width="60%"> </colgroup> <thead><tr><th>Problem</th><th>Solution</th></tr></thead><tbody> <tr><td><strong>“gpg: signing failed: Ambiguous specification”</strong></td><td>You have multiple keys for one email. Use the unique <strong>Key-ID</strong> instead of the email address in your configuration (e.g., <code>pgp_sign_as</code> in Neomutt).</td></tr> <tr><td><strong>No password prompt appears</strong></td><td>Your <code>pinentry</code> program is missing or misconfigured. Go back to <a href="#part-1-2"><strong>Part 1.2</strong></a> and ensure it is installed and configured correctly.</td></tr> <tr><td><strong>GPG Agent Issues</strong> (Passphrase not requested)</td><td>The GPG agent might have a stale cache. Force a reload with: <code>gpg-connect-agent reloadagent /bye</code></td></tr> <tr><td><strong>“Key not found” error</strong></td><td>You don’t have the recipient’s public key. Ask them for it or search a keyserver.</td></tr> <tr><td><strong>“gpg: signing failed: No secret key”</strong></td><td>Your key might be expired, or GPG cannot find the correct secret key. Check <code>gpg --list-secret-keys</code> to ensure it’s present and valid.</td></tr> <tr><td><strong>Message shows “untrusted signature”</strong></td><td>You have the sender’s public key, but you haven’t marked it as trusted. Verify the fingerprint and then sign it.</td></tr> </tbody> </table> </div> <hr /> <h2 id="11-conclusion">11. Conclusion</h2> <p>By starting with a solid foundation—creating your keys directly in the terminal—you have built a robust and universal encryption setup. This method not only avoids platform-specific pitfalls but also equips you with a deeper understanding of how PGP works. By performing essential maintenance like backups, establishing a clear public identity, and renewing your keys, you ensure your digital identity remains secure and trustworthy for the long term.</p> <p><!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;www.openpgp.org&#x2F;docs&#x2F;" class="retro-button"> <span class="emoji">📚</span><span class="button-text">OPENPGP DOCUMENTATION</span> </a> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;gnupg.org&#x2F;documentation&#x2F;index.html" class="retro-button"> <span class="emoji">🛡️</span><span class="button-text">GNUPG DOCUMENTATION</span> </a> </p> Tutorial: Integrating ranger and sxiv with Advanced Features Sun, 06 Jul 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/ranger-sxiv-integration/ https://criticalbasics.xyz/posts/ranger-sxiv-integration/ <p>This tutorial combines all the necessary steps to seamlessly integrate <strong>sxiv</strong> and <strong>ranger</strong>, including:</p> <ul> <li>Launching a gallery view from ranger</li> <li>Configuring keybindings in ranger</li> <li>Creating an interactive “Open with…” menu in sxiv</li> <li>Opening ranger from within sxiv</li> <li>Navigating and using shortcuts in sxiv</li> <li>Increasing thumbnail sizes by recompiling sxiv</li> </ul> <h2 id="prerequisites">Prerequisites</h2> <ul> <li><strong>Arch Linux</strong> (or a similar distro; this guide refers to <code>pacman</code> and the AUR)</li> <li><code>sxiv</code> and <code>ranger</code> installed</li> <li>A terminal emulator (e.g., <code>xterm</code>, <code>urxvt</code>, <code>alacritty</code>, <code>kitty</code>)</li> <li>Standard command-line tools (<code>file</code>, <code>grep</code>, <code>sed</code>, etc.)</li> <li><code>gtk-launch</code> (usually available via <code>xdg-utils</code> or a similar package)</li> </ul> <hr /> <h2 id="1-set-up-the-ranger-keybinding-launch-gallery">1. Set Up the ranger Keybinding (Launch Gallery)</h2> <ol> <li> <p>Open your ranger configuration file: <code>~/.config/ranger/rc.conf</code>.</p> </li> <li> <p>Add a line to open sxiv in <strong>thumbnail mode</strong> recursively using a key combination. For example, <code>gG</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span># Open sxiv in thumbnail mode (-t) recursively (-r) in the current directory (%d)</span></span> <span class="giallo-l"><span>map gG shell sxiv -tr %d &amp;</span></span></code></pre> <ul> <li><code>-t</code> enables <strong>thumbnail mode</strong>.</li> <li><code>-r</code> searches subdirectories recursively.</li> <li>The trailing <code>&amp;</code> ensures that ranger <strong>does not</strong> wait for sxiv to close.</li> </ul> </li> <li> <p>Save the file and reload the configuration in ranger with:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">:reload_config</span></span></code></pre> <p>or simply restart ranger.</p> </li> </ol> <hr /> <h2 id="2-navigating-in-sxiv">2. Navigating in sxiv</h2> <ul> <li> <p><strong>Open Gallery View:</strong> Use <code>sxiv -tr /path/to/your/folder</code> to start directly in thumbnail mode.</p> </li> <li> <p><strong>Open a Single Image:</strong> Highlight an image in the gallery and press <code>Enter</code>.</p> </li> <li> <p><strong>Switch Between Images (Single-Image Mode):</strong></p> <ul> <li><code>n</code> or <code>Space</code>: Next image</li> <li><code>p</code> or <code>Backspace</code>: Previous image</li> <li><code>]</code>: 10 images forward</li> <li><code>[</code>: 10 images backward</li> <li><code>g</code>: First image, <code>G</code>: Last image</li> <li>Right mouse click: Next image, Left mouse click: Previous image</li> </ul> </li> <li> <p><strong>Zoom in the Gallery:</strong></p> <ul> <li><code>+</code>: Zoom in</li> <li><code>-</code>: Zoom out</li> </ul> <blockquote> <p>To increase the maximum zoom level, you need to recompile sxiv (see Section 4).</p> </blockquote> </li> </ul> <hr /> <h2 id="3-interactive-open-with-and-ranger-integration-in-sxiv">3. Interactive “Open with…” and Ranger Integration in sxiv</h2> <p>We will create a <strong>key-handler script</strong> that allows the following:</p> <ul> <li><strong><code>Ctrl-x r</code></strong>: Opens ranger in a new terminal, selecting the current file.</li> <li><strong><code>Ctrl-x o</code></strong> (or any other key): Displays an interactive menu of all suitable applications and opens the image with the selected one.</li> </ul> <h3 id="3-1-create-the-script">3.1. Create the Script</h3> <ol> <li> <p>Create the directory:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/.config/sxiv/exec</span></span></code></pre></li> <li> <p>Create the file <code>~/.config/sxiv/exec/key-handler</code> and paste the following content <strong>in its entirety</strong>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;">#!/usr/bin/env sh</span></span> <span class="giallo-l"><span style="color: #6A737D;">#</span></span> <span class="giallo-l"><span style="color: #6A737D;"># ~/.config/sxiv/exec/key-handler</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Interactive script for sxiv:</span></span> <span class="giallo-l"><span style="color: #6A737D;"># - Ctrl-x r → opens ranger in a new terminal with the current file selected</span></span> <span class="giallo-l"><span style="color: #6A737D;"># - Ctrl-x o (and others) → opens an &quot;Open with…&quot; menu to choose an application</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Robust handling of spaces, logging, and i3-compatible terminals</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Logfile for debugging and tracking</span></span> <span class="giallo-l"><span>LOG</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">/tmp/sxiv-open.log</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;=== key-handler started $(</span><span style="color: #B392F0;">date</span><span style="color: #9ECBFF;">) ===&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Terminal emulator used to open the selection menu</span></span> <span class="giallo-l"><span style="color: #6A737D;"># Possible options: xterm, urxvt, alacritty, kitty …</span></span> <span class="giallo-l"><span>TERMWIN</span><span style="color: #F97583;">=</span><span>${TERMWIN</span><span style="color: #F97583;">:-</span><span>urxvt}</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;TERMWIN set to: </span><span>$TERMWIN</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># $1 contains the key pressed after Ctrl-x</span></span> <span class="giallo-l"><span>cmd</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;">$1</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;Command argument: </span><span>$cmd</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Remove the prefix argument; all image paths follow via stdin</span></span> <span class="giallo-l"><span style="color: #79B8FF;">shift</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Process each file individually (handles paths with spaces)</span></span> <span class="giallo-l"><span style="color: #F97583;">while</span><span> IFS</span><span style="color: #F97583;">=</span><span style="color: #79B8FF;"> read -r</span><span style="color: #9ECBFF;"> img</span><span>;</span><span style="color: #F97583;"> do</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;Processing file: &#39;</span><span>$img</span><span style="color: #9ECBFF;">&#39;&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # === Ranger Integration (Ctrl-x r) ===</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [</span><span style="color: #9ECBFF;"> &quot;</span><span>$cmd</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &quot;r&quot;</span><span> ];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot;Ranger Integration: Opening ranger in terminal for &#39;</span><span>$img</span><span style="color: #9ECBFF;">&#39;&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # Ranger needs a terminal, so launch it via a terminal emulator</span></span> <span class="giallo-l"><span style="color: #B392F0;"> &quot;</span><span>$TERMWIN</span><span style="color: #B392F0;">&quot;</span><span style="color: #79B8FF;"> -e</span><span style="color: #9ECBFF;"> ranger</span><span style="color: #79B8FF;"> --selectfile=</span><span style="color: #9ECBFF;">&quot;</span><span>$img</span><span style="color: #9ECBFF;">&quot;</span><span> &amp;</span></span> <span class="giallo-l"><span style="color: #F97583;"> continue</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # === Default Open-with… Menu (Ctrl-x o or other keys) ===</span></span> <span class="giallo-l"><span style="color: #6A737D;"> # 1) Determine the MIME type of the file</span></span> <span class="giallo-l"><span> mime</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">file</span><span style="color: #79B8FF;"> --mime-type -b</span><span style="color: #9ECBFF;"> &quot;</span><span>$img</span><span style="color: #9ECBFF;">&quot;</span><span>)</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot; MIME-Type: </span><span>$mime</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # 2) Find matching .desktop files for this MIME type</span></span> <span class="giallo-l"><span style="color: #B392F0;"> mapfile</span><span style="color: #79B8FF;"> -t</span><span style="color: #9ECBFF;"> apps</span><span style="color: #F97583;"> &lt;</span><span style="color: #9ECBFF;"> &lt;(</span></span> <span class="giallo-l"><span style="color: #B392F0;"> grep</span><span style="color: #79B8FF;"> -Rl</span><span style="color: #9ECBFF;"> &quot;MimeType=.*</span><span>$mime</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> /usr/share/applications ~/.local/share/applications</span><span style="color: #F97583;"> 2&gt;</span><span style="color: #9ECBFF;">/dev/null</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> xargs</span><span style="color: #79B8FF;"> -r -n1</span><span style="color: #9ECBFF;"> basename</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sort</span><span style="color: #79B8FF;"> -u</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> )</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [ ${</span><span style="color: #F97583;">#</span><span>apps[</span><span style="color: #F97583;">@</span><span>]}</span><span style="color: #F97583;"> -eq</span><span style="color: #79B8FF;"> 0</span><span> ];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot; No matching applications found for MIME &#39;</span><span>$mime</span><span style="color: #9ECBFF;">&#39;&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> continue</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot; Found applications: ${</span><span>apps</span><span style="color: #9ECBFF;">[</span><span style="color: #F97583;">*</span><span style="color: #9ECBFF;">]}&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # 3) Create temporary files for the list and the choice</span></span> <span class="giallo-l"><span> list_file</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">mktemp</span><span>)</span></span> <span class="giallo-l"><span> tmp_choice</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">mktemp</span><span>)</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> printf</span><span style="color: #9ECBFF;"> &quot;%s\n&quot; &quot;${</span><span>apps</span><span style="color: #9ECBFF;">[</span><span style="color: #F97583;">@</span><span style="color: #9ECBFF;">]}&quot;</span><span style="color: #F97583;"> &gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$list_file</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot; List file: </span><span>$list_file</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot; Choice file: </span><span>$tmp_choice</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # 4) Open the terminal selection menu</span></span> <span class="giallo-l"><span style="color: #B392F0;"> &quot;</span><span>$TERMWIN</span><span style="color: #B392F0;">&quot;</span><span style="color: #79B8FF;"> -e</span><span style="color: #9ECBFF;"> bash</span><span style="color: #79B8FF;"> -lc</span><span style="color: #9ECBFF;"> &#39;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> PS3=&quot;Open with: &quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Read all entries into an array</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> IFS=$&#39;</span><span style="color: #79B8FF;">\&#39;</span><span style="color: #9ECBFF;">&#39;\n&#39;</span><span style="color: #79B8FF;">\&#39;</span><span style="color: #9ECBFF;">&#39; read -rd &quot;&quot; -r -a options &lt; &quot;&#39;&quot;</span><span>$list_file</span><span style="color: #9ECBFF;">&quot;&#39;&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> select opt in &quot;${options[@]}&quot;; do</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> # Write the choice to the temp file</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> echo &quot;$opt&quot; &gt; &quot;&#39;&quot;</span><span>$tmp_choice</span><span style="color: #9ECBFF;">&quot;&#39;&quot;</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> break</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> done</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> &#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # 5) Read the choice and clean up</span></span> <span class="giallo-l"><span> choice</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #F97583;">&lt;</span><span style="color: #9ECBFF;">&quot;</span><span>$tmp_choice</span><span style="color: #9ECBFF;">&quot;</span><span>)</span></span> <span class="giallo-l"><span style="color: #B392F0;"> rm</span><span style="color: #79B8FF;"> -f</span><span style="color: #9ECBFF;"> &quot;</span><span>$list_file</span><span style="color: #9ECBFF;">&quot; &quot;</span><span>$tmp_choice</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot; Selected: </span><span>$choice</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span> [</span><span style="color: #F97583;"> -n</span><span style="color: #9ECBFF;"> &quot;</span><span>$choice</span><span style="color: #9ECBFF;">&quot;</span><span> ]</span><span style="color: #F97583;"> || continue</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # 6) Find the full .desktop file path</span></span> <span class="giallo-l"><span> desktop</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> for</span><span> d</span><span style="color: #F97583;"> in</span><span style="color: #9ECBFF;"> /usr/share/applications ~/.local/share/applications</span><span>;</span><span style="color: #F97583;"> do</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span> [</span><span style="color: #F97583;"> -f</span><span style="color: #9ECBFF;"> &quot;</span><span>$d</span><span style="color: #9ECBFF;">/</span><span>$choice</span><span style="color: #9ECBFF;">&quot;</span><span> ];</span><span style="color: #F97583;"> then</span></span> <span class="giallo-l"><span> desktop</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&quot;</span><span>$d</span><span style="color: #9ECBFF;">/</span><span>$choice</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;"> break</span></span> <span class="giallo-l"><span style="color: #F97583;"> fi</span></span> <span class="giallo-l"><span style="color: #F97583;"> done</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot; Desktop entry: </span><span>$desktop</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # 7) Read the Exec line and remove placeholders</span></span> <span class="giallo-l"><span> exec_cmd</span><span style="color: #F97583;">=</span><span>$(</span><span style="color: #B392F0;">grep</span><span style="color: #79B8FF;"> -m1</span><span style="color: #9ECBFF;"> &#39;^Exec=&#39; &quot;</span><span>$desktop</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #79B8FF;"> \</span></span> <span class="giallo-l"><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> cut</span><span style="color: #79B8FF;"> -d= -f2- \</span></span> <span class="giallo-l"><span style="color: #F97583;"> |</span><span style="color: #B392F0;"> sed</span><span style="color: #79B8FF;"> -E</span><span style="color: #9ECBFF;"> &#39;s/ %[fFuUdDnNickvm]//g&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot; Exec command: </span><span>$exec_cmd</span><span style="color: #9ECBFF;">&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"> # 8) Execute the program with the image path</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> eval</span><span style="color: #9ECBFF;"> &quot;</span><span>$exec_cmd</span><span style="color: #79B8FF;"> \&quot;</span><span>$img</span><span style="color: #79B8FF;">\&quot;</span><span style="color: #9ECBFF;">&quot;</span><span> &amp;</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> echo</span><span style="color: #9ECBFF;"> &quot; Application started for &#39;</span><span>$img</span><span style="color: #9ECBFF;">&#39;&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span> <span class="giallo-l"><span style="color: #F97583;">done</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># End of log</span></span> <span class="giallo-l"><span style="color: #79B8FF;">echo</span><span style="color: #9ECBFF;"> &quot;=== key-handler finished ===&quot;</span><span style="color: #F97583;"> &gt;&gt;</span><span style="color: #9ECBFF;">&quot;</span><span>$LOG</span><span style="color: #9ECBFF;">&quot;</span></span></code></pre></li> <li> <p><strong>Make the script executable</strong>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">chmod</span><span style="color: #9ECBFF;"> +x ~/.config/sxiv/exec/key-handler</span></span></code></pre></li> <li> <p><strong><code>TERMWIN</code> variable (optional)</strong>: If you want to use a terminal other than <code>urxvt</code>, like <code>alacritty</code>, add this to your <code>~/.bashrc</code> / <code>~/.profile</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F97583;">export</span><span> TERMWIN</span><span style="color: #F97583;">=</span><span>alacritty</span></span></code></pre></li> </ol> <hr /> <h2 id="4-thumbnail-sizes-optional-recompiling-sxiv">4. Thumbnail Sizes (Optional: Recompiling sxiv)</h2> <p>By default, the available thumbnail sizes in sxiv are limited to <code>{ 32, 64, 96, 128, 160 }</code> px. If 160px is too small, you can increase them as follows:</p> <ol> <li> <p><strong>Get the sources from the AUR</strong> (example using <code>sxiv-git</code>):</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">git</span><span style="color: #9ECBFF;"> clone https://aur.archlinux.org/sxiv-git.git</span></span> <span class="giallo-l"><span style="color: #79B8FF;">cd</span><span style="color: #9ECBFF;"> sxiv-git</span></span></code></pre></li> <li> <p><strong>Generate <code>config.h</code></strong>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">make</span><span style="color: #9ECBFF;"> config.h</span></span></code></pre></li> <li> <p><strong>Adjust Thumbnail Sizes</strong>: Open the <code>config.h</code> file and find the <code>_THUMBS_CONFIG</code> section. Change the block to something like this:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="c"><span class="giallo-l"><span style="color: #F97583;">#ifdef</span><span style="color: #B392F0;"> _THUMBS_CONFIG</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;">/* thumbnail sizes in pixels (width == height): */</span></span> <span class="giallo-l"><span style="color: #F97583;">static const int</span><span> thumb_sizes</span><span style="color: #F97583;">[] =</span><span> {</span><span style="color: #79B8FF;"> 32</span><span>,</span><span style="color: #79B8FF;"> 64</span><span>,</span><span style="color: #79B8FF;"> 96</span><span>,</span><span style="color: #79B8FF;"> 128</span><span>,</span><span style="color: #79B8FF;"> 160</span><span>,</span><span style="color: #79B8FF;"> 256</span><span>,</span><span style="color: #79B8FF;"> 320</span><span>,</span><span style="color: #79B8FF;"> 400</span><span> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;">/* default thumbnail size on startup (index in thumb_sizes[]): */</span></span> <span class="giallo-l"><span style="color: #F97583;">static const int</span><span> THUMB_SIZE </span><span style="color: #F97583;">=</span><span style="color: #79B8FF;"> 5</span><span>;</span><span style="color: #6A737D;"> // starts at 256 px</span></span> <span class="giallo-l"><span style="color: #F97583;">#endif</span></span></code></pre></li> <li> <p><strong>Compile and install</strong>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">make</span></span> <span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> make install</span></span></code></pre></li> <li> <p><strong>Use the New Thumbnail Sizes</strong>: In sxiv, sizes up to <strong>400px</strong> are now available. Use <code>+</code> to increase and <code>-</code> to decrease the size.</p> </li> </ol> <hr /> <h2 id="5-summary-of-keybindings">5. Summary of Keybindings</h2> <h3 id="5-1-ranger-shortcuts">5.1 Ranger Shortcuts</h3> <div class="styled-table-container shortcut-table"> <table><thead><tr><th>Action</th><th>Command</th></tr></thead><tbody> <tr><td>Start sxiv gallery in current directory</td><td><code>gG</code></td></tr> </tbody></table> </div> <h3 id="5-2-sxiv-gallery-mode-shortcuts">5.2 sxiv Gallery Mode Shortcuts</h3> <div class="styled-table-container shortcut-table"> <table><thead><tr><th>Action</th><th>Command</th></tr></thead><tbody> <tr><td>Open single-image view</td><td><code>Enter</code></td></tr> <tr><td>Mark an image (for multi-selection)</td><td><code>m</code></td></tr> <tr><td>Zoom in</td><td><code>+</code></td></tr> <tr><td>Zoom out</td><td><code>-</code></td></tr> <tr><td>“Open with…” menu (interactive)</td><td><code>Ctrl-x o</code></td></tr> <tr><td>Open ranger in a new terminal with file selected</td><td><code>Ctrl-x r</code></td></tr> </tbody></table> </div> <h3 id="5-3-sxiv-single-image-mode-shortcuts">5.3 sxiv Single-Image Mode Shortcuts</h3> <div class="styled-table-container shortcut-table"> <table><thead><tr><th>Action</th><th>Command</th></tr></thead><tbody> <tr><td>Next image</td><td><code>n</code> or <code>Space</code></td></tr> <tr><td>Previous image</td><td><code>p</code> or <code>Backspace</code></td></tr> <tr><td>10 images forward</td><td><code>]</code></td></tr> <tr><td>10 images backward</td><td><code>[</code></td></tr> <tr><td>First image</td><td><code>g</code></td></tr> <tr><td>Last image</td><td><code>G</code></td></tr> <tr><td>Play/stop GIF animation</td><td><code>Ctrl-Space</code></td></tr> </tbody></table> </div> <hr /> <h2 id="6-debugging-logs">6. Debugging &amp; Logs</h2> <p>All actions from the <code>key-handler</code> script are logged to <code>/tmp/sxiv-open.log</code>. There you can see:</p> <ul> <li>The key that was used (<code>ctrl-x r</code> or <code>ctrl-x o</code>).</li> <li>The detected <strong>MIME type</strong>.</li> <li>The found <code>.desktop</code> entries.</li> <li>The chosen application and the executed command.</li> <li>The ranger call.</li> </ul> <p>Example:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>=== key-handler started Mon Apr 28 18:01:20 CEST 2025 ===</span></span> <span class="giallo-l"><span>TERMWIN set to: xterm</span></span> <span class="giallo-l"><span>Command argument: o</span></span> <span class="giallo-l"><span>Processing file: &#39;/home/.../Example.png&#39;</span></span> <span class="giallo-l"><span> MIME-Type: image/png</span></span> <span class="giallo-l"><span>Found applications: gimp.desktop firefox.desktop ...</span></span> <span class="giallo-l"><span>List file: /tmp/tmp.XXXXXX</span></span> <span class="giallo-l"><span>Choice file: /tmp/tmp.YYYYYY</span></span> <span class="giallo-l"><span>Selected: gimp.desktop</span></span> <span class="giallo-l"><span>Desktop entry: /usr/share/applications/gimp.desktop</span></span> <span class="giallo-l"><span>Exec command: gimp-3.0</span></span> <span class="giallo-l"><span>Application started for &#39;/home/.../Example.png&#39;</span></span> <span class="giallo-l"><span>=== key-handler finished ===</span></span></code></pre> <p>If something goes wrong, you can check the log:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">less</span><span style="color: #9ECBFF;"> /tmp/sxiv-open.log</span></span></code></pre> Vim Tip: How to Insert the Current Time with a Shortcut Thu, 03 Jul 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/vim-time-insert/ https://criticalbasics.xyz/posts/vim-time-insert/ <p>When keeping a journal, logging meetings, or documenting events, an accurate timestamp is invaluable. However, manually typing the time is cumbersome and interrupts your writing flow.</p> <p>In this short guide, you’ll learn how to use a single, clever line in your <code>.vimrc</code> to create a shortcut that lets you insert the current time instantly and effortlessly at any position.</p> <hr /> <h2 id="the-solution-a-shortcut-for-insert-mode">The Solution: A Shortcut for Insert Mode</h2> <p>This method is ideal when you’re in the middle of writing and want to insert a timestamp directly into the text, for example:</p> <p><code>14:32 – Call from the project manager</code></p> <p>To do this, simply add the following line to your <code>~/.vimrc</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span style="color: #6A737D;">&quot; Insert the current time (HH:MM) in insert mode with &lt;leader&gt;t</span></span> <span class="giallo-l"><span style="color: #F97583;">inoremap</span><span> &lt;</span><span style="color: #79B8FF;">leader</span><span>&gt;t &lt;</span><span style="color: #79B8FF;">C-R</span><span>&gt;</span><span style="color: #F97583;">=</span><span style="color: #B392F0;">strftime</span><span>(</span><span style="color: #9ECBFF;">&#39;%H:%M&#39;</span><span>)&lt;</span><span style="color: #79B8FF;">CR</span><span>&gt;</span></span></code></pre><h3 id="how-it-works">How It Works</h3> <p>This single line is a perfect example of Vim’s power:</p> <ul> <li><strong><code>inoremap &lt;leader&gt;t</code></strong>: Defines a key mapping (by default <code>\t</code>) exclusively for <strong>insert mode</strong>.</li> <li><strong><code>&lt;C-R&gt;=</code></strong>: This is the magic part. In insert mode, <code>Ctrl-R</code> normally inserts the content of a register. When you add an equals sign (<code>=</code>), Vim opens a mini-command line and evaluates the following expression.</li> <li><strong><code>strftime('%H:%M')</code></strong>: This is a built-in Vim function that returns the current time, formatted. <code>%H</code> stands for the hour (24h) and <code>%M</code> for the minute.</li> <li><strong><code>&lt;CR&gt;</code></strong>: Confirms the function, inserts its result (the time) at the cursor’s position, and seamlessly returns you to insert mode.</li> </ul> <p><strong>How to use it:</strong> The next time you’re typing in a note, just press <code>\</code> followed by <code>t</code>, and the current timestamp will appear instantly in the text.</p> <hr /> <h2 id="customize-it-to-your-needs">Customize It to Your Needs</h2> <p>The best part of this method is its flexibility. You can customize the timestamp format however you like by changing the string inside the <code>strftime()</code> function.</p> <p>Here are a few popular alternatives for your <code>.vimrc</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span style="color: #6A737D;">&quot; -- EXAMPLE 1: Time with seconds --</span></span> <span class="giallo-l"><span style="color: #F97583;">inoremap</span><span> &lt;</span><span style="color: #79B8FF;">leader</span><span>&gt;</span><span style="color: #79B8FF;">ts</span><span> &lt;</span><span style="color: #79B8FF;">C-R</span><span>&gt;</span><span style="color: #F97583;">=</span><span style="color: #B392F0;">strftime</span><span>(</span><span style="color: #9ECBFF;">&#39;%H:%M:%S&#39;</span><span>)&lt;</span><span style="color: #79B8FF;">CR</span><span>&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; -- EXAMPLE 2: Full date and time (ISO standard) --</span></span> <span class="giallo-l"><span style="color: #F97583;">inoremap</span><span> &lt;</span><span style="color: #79B8FF;">leader</span><span>&gt;dt &lt;</span><span style="color: #79B8FF;">C-R</span><span>&gt;</span><span style="color: #F97583;">=</span><span style="color: #B392F0;">strftime</span><span>(</span><span style="color: #9ECBFF;">&#39;%Y-%m-%d %H:%M&#39;</span><span>)&lt;</span><span style="color: #79B8FF;">CR</span><span>&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; -- EXAMPLE 3: US Date Format --</span></span> <span class="giallo-l"><span style="color: #F97583;">inoremap</span><span> &lt;</span><span style="color: #79B8FF;">leader</span><span>&gt;us &lt;</span><span style="color: #79B8FF;">C-R</span><span>&gt;</span><span style="color: #F97583;">=</span><span style="color: #B392F0;">strftime</span><span>(</span><span style="color: #9ECBFF;">&#39;%m/%d/%Y %I:%M %p&#39;</span><span>)&lt;</span><span style="color: #79B8FF;">CR</span><span>&gt;</span></span></code></pre> <hr /> <h2 id="bonus-inserting-a-timestamp-in-normal-mode">Bonus: Inserting a Timestamp in Normal Mode</h2> <p>Sometimes you might want to insert a timestamp on its own new line. For that, a normal mode shortcut is better suited.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span style="color: #6A737D;">&quot; Insert the current time on a new line below the current one</span></span> <span class="giallo-l"><span style="color: #F97583;">nnoremap</span><span> &lt;</span><span style="color: #79B8FF;">leader</span><span>&gt;T :put </span><span style="color: #F97583;">=</span><span style="color: #B392F0;">strftime</span><span>(</span><span style="color: #9ECBFF;">&#39;%H:%M&#39;</span><span>)&lt;</span><span style="color: #79B8FF;">CR</span><span>&gt;</span></span></code></pre> <p>With this mapping, you can press <code>\T</code> in normal mode, and the time will be placed cleanly on the next line.</p> <hr /> <h2 id="summary">Summary</h2> <p>With this simple trick, you’ve further optimized your workflow:</p> <p>✅ You can insert timestamps instantly with a keystroke, without interrupting your flow. ✅ The format is fully customizable to your needs. ✅ The solution is lean, fast, and uses built-in Vim features without any extra plugins.</p> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;vimhelp.org&#x2F;eval.txt.html#strftime()" class="retro-button"> <span class="emoji">📂</span><span class="button-text">EXPLORE ALL STRFTIME() OPTIONS</span> </a> <hr /> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ WHAT&#x27;S NEXT? </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Now that you’ve mastered timestamps, discover how to perfect links, navigation, and task management in our <a href="/posts/vimwiki-workflow-mastered">Vimwiki Workflow Guide</a>.</p> </td> </tr> </table> A Guide to Zathura: The Minimalist PDF Viewer Thu, 03 Jul 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/zathura-pdf-viewer/ https://criticalbasics.xyz/posts/zathura-pdf-viewer/ <p>This tutorial will guide you through installing, configuring, and using <strong>Zathura</strong> with the <strong>MuPDF backend</strong> on Arch Linux, specifically tailored for an <strong>i3wm</strong> environment. It covers installation, configuration, printing, and a comprehensive overview of the most important shortcuts.</p> <hr /> <h2 id="1-introduction">1. Introduction</h2> <p><strong>Zathura</strong> is a lightweight yet powerful PDF viewer that features a minimalist user interface, making it an excellent fit for lightweight window managers like <strong>i3wm</strong>. By using plugin backends like <strong>MuPDF</strong> or <strong>Poppler</strong>, you can maintain a minimal setup without sacrificing essential features such as search, bookmarks, or printing.</p> <p>Advantages of Zathura:</p> <ul> <li><strong>Very few dependencies</strong> (only Girara/GTK, and a backend like MuPDF or Poppler)</li> <li><strong>Keyboard-centric control</strong> (ideal for i3wm)</li> <li><strong>Extensible via plugins</strong> (e.g., for Synctex or annotations)</li> <li><strong>Highly configurable</strong> through a simple text file</li> </ul> <hr /> <h2 id="2-installation">2. Installation</h2> <ol> <li> <p><strong>Install Zathura &amp; the MuPDF Backend</strong> Open a terminal and execute the following command:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> zathura zathura-pdf-mupdf</span></span></code></pre></li> <li> <p><strong>Launch Zathura</strong> After installation, you can open a PDF file like this:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">zathura</span><span style="color: #9ECBFF;"> document.pdf</span></span></code></pre></li> </ol> <hr /> <h2 id="3-setting-zathura-as-the-default-pdf-viewer">3. Setting Zathura as the Default PDF Viewer</h2> <p>If you were previously using a different viewer like <strong>Evince</strong> (e.g., in <code>mimeapps.list</code>), your configuration might look like this:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span>application/</span><span style="color: #F97583;">pdf</span><span>=org.gnome.Evince.desktop</span></span></code></pre> <p>To make Zathura the new default for PDF files, you need to add or edit the following line in your <code>~/.config/mimeapps.list</code> (or <code>~/.local/share/applications/mimeapps.list</code>):</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="ini"><span class="giallo-l"><span style="color: #B392F0;">[Default Applications]</span></span> <span class="giallo-l"><span>application/</span><span style="color: #F97583;">pdf</span><span>=org.pwmt.zathura.desktop</span></span></code></pre> <p>This sets Zathura as the default application for the <code>application/pdf</code> MIME type.</p> <hr /> <h2 id="4-configuring-zathura">4. Configuring Zathura</h2> <p>Zathura reads its configuration from <code>~/.config/zathura/zathurarc</code>. Here is an example of a minimal configuration:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span># ~/.config/zathura/zathurarc</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># 1. Set the default backend to MuPDF</span></span> <span class="giallo-l"><span>set pdf-mupdf true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># 2. Adjust page to fit width on open</span></span> <span class="giallo-l"><span>set adjust-open &quot;fit-width&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># 3. Set default zoom level (100%)</span></span> <span class="giallo-l"><span>set zoom 1.0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># 4. Remap keys (optional)</span></span> <span class="giallo-l"><span>map &lt;C-f&gt; search-forward</span></span> <span class="giallo-l"><span>map &lt;C-b&gt; search-backward</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># 5. Set bookmark file path</span></span> <span class="giallo-l"><span>set bookmark-path &quot;~/.config/zathura/bookmarks&quot;</span></span></code></pre><h3 id="explanation-of-key-options">Explanation of Key Options</h3> <ul> <li><code>set pdf-mupdf true</code>: Specifies that Zathura should use the MuPDF backend instead of Poppler.</li> <li><code>set adjust-open "fit-width"</code>: Automatically fits the page to the window’s width when opening a document.</li> <li><code>set zoom 1.0</code>: Sets the default zoom level to 100%.</li> <li><code>map &lt;C-f&gt; search-forward</code>: Remaps <code>Ctrl+f</code> for searching forward.</li> <li><code>map &lt;C-b&gt; search-backward</code>: Remaps <code>Ctrl+b</code> for searching backward.</li> <li><code>set bookmark-path "..."</code>: Defines the directory where bookmark files are stored.</li> </ul> <hr /> <h2 id="5-printing-functionality">5. Printing Functionality</h2> <p>Zathura supports printing directly via GTK. To print a PDF:</p> <ol> <li>Open the PDF in Zathura:<pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">zathura</span><span style="color: #9ECBFF;"> document.pdf</span></span></code></pre></li> <li>In the viewer, simply press <code>P</code> or enter the command:<pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>:print</span></span></code></pre></li> <li>The standard <strong>GTK print dialog</strong> will open, allowing you to select a printer, page range, scaling, and other options.</li> </ol> <p>Internally, GTK generates a temporary PDF (using Cairo) and sends it to <strong>CUPS</strong>, so no additional plugins are usually necessary.</p> <blockquote> <p><strong>Tip:</strong> If you prefer to print directly from the shell, you can always use:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">lp</span><span style="color: #9ECBFF;"> document.pdf</span></span></code></pre> <p>This works independently of your chosen PDF viewer.</p> </blockquote> <hr /> <h2 id="6-overview-of-essential-keyboard-shortcuts">6. Overview of Essential Keyboard Shortcuts</h2> <p>Zathura is heavily designed for keyboard control. Below are the most useful shortcuts organized by category.</p> <h3 id="6-1-navigation">6.1 Navigation</h3> <div class="styled-table-container shortcut-table"> <table><thead><tr><th>Action</th><th>Command</th></tr></thead><tbody> <tr><td>Next Page</td><td><code>j</code> or <code>↓</code></td></tr> <tr><td>Previous Page</td><td><code>k</code> or <code>↑</code></td></tr> <tr><td>First Page</td><td><code>gg</code></td></tr> <tr><td>Last Page</td><td><code>G</code></td></tr> <tr><td>Go to Specific Page</td><td><code>:page &lt;number&gt;</code> (e.g., <code>:page 10</code>)</td></tr> </tbody></table> </div> <h3 id="6-2-zoom-view">6.2 Zoom &amp; View</h3> <div class="styled-table-container shortcut-table"> <table><thead><tr><th>Action</th><th>Command</th></tr></thead><tbody> <tr><td>Zoom In</td><td><code>zi</code> or <code>+</code></td></tr> <tr><td>Zoom Out</td><td><code>zo</code> or <code>-</code></td></tr> <tr><td>Original Size</td><td><code>zr</code></td></tr> <tr><td>Fit to Width</td><td><code>zb</code></td></tr> <tr><td>Fit to Height</td><td><code>zh</code></td></tr> <tr><td>Toggle Fullscreen</td><td><code>f</code></td></tr> </tbody></table> </div> <h3 id="6-3-search-bookmarks">6.3 Search &amp; Bookmarks</h3> <div class="styled-table-container shortcut-table"> <table><thead><tr><th>Action</th><th>Command</th></tr></thead><tbody> <tr><td>Search Forward</td><td><code>/</code> followed by search term</td></tr> <tr><td>Search Backward</td><td><code>?</code> followed by search term</td></tr> <tr><td>Next Search Result</td><td><code>n</code></td></tr> <tr><td>Previous Search Result</td><td><code>N</code></td></tr> <tr><td>Add Bookmark</td><td><code>m</code> (then choose a letter)</td></tr> <tr><td>Open Bookmark List</td><td><code>:bookmarks</code></td></tr> <tr><td>Jump to Bookmark</td><td><code>`</code> followed by the letter</td></tr> </tbody></table> </div> <h3 id="6-4-document-operations">6.4 Document Operations</h3> <div class="styled-table-container shortcut-table"> <table><thead><tr><th>Action</th><th>Command</th></tr></thead><tbody> <tr><td>Print</td><td><code>P</code> or <code>:print</code></td></tr> <tr><td>Reload Document</td><td><code>R</code></td></tr> <tr><td>Open Console (Command line in viewer)</td><td><code>:</code></td></tr> </tbody></table> </div> <h3 id="6-5-general-commands">6.5 General Commands</h3> <div class="styled-table-container shortcut-table"> <table><thead><tr><th>Action</th><th>Command</th></tr></thead><tbody> <tr><td>Show Help</td><td><code>H</code></td></tr> <tr><td>Reload Configuration</td><td><code>:config-reload</code></td></tr> <tr><td>Quit</td><td><code>q</code></td></tr> </tbody></table> </div> <blockquote> <p><strong>Note:</strong> Many of these commands can be remapped in <code>~/.config/zathura/zathurarc</code>. See Section 4 for examples.</p> </blockquote> <hr /> <h2 id="7-summary">7. Summary</h2> <ul> <li><strong>Installation:</strong><pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">sudo</span><span style="color: #9ECBFF;"> pacman</span><span style="color: #79B8FF;"> -S</span><span style="color: #9ECBFF;"> zathura zathura-pdf-mupdf</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">```</span><span style="color: #B392F0;">-</span><span style="color: #79B8FF;"> **</span><span style="color: #9ECBFF;">Set as Default PDF Viewer:</span><span style="color: #79B8FF;">**</span></span> <span class="giallo-l"><span style="color: #B392F0;">In</span><span style="color: #9ECBFF;"> `</span><span style="color: #B392F0;">~/.config/mimeapps.list</span><span style="color: #9ECBFF;">`</span><span style="color: #79B8FF;">:</span></span> <span class="giallo-l"><span style="color: #9ECBFF;">```</span><span style="color: #B392F0;">ini</span></span> <span class="giallo-l"><span>[Default Applications]</span></span> <span class="giallo-l"><span style="color: #B392F0;">application/pdf</span><span style="color: #9ECBFF;">=org.pwmt.zathura.desktop</span></span></code></pre></li> <li><strong>Configuration:</strong> Via <code>~/.config/zathura/zathurarc</code> (see example file).</li> <li><strong>Usage:</strong> Keyboard-centric, with quick access to search, zoom, bookmarks, and printing (<code>P</code> / <code>:print</code>).</li> <li><strong>Printing:</strong> Opens the GTK print dialog, using CUPS via Cairo.</li> </ul> <p>Zathura is ideal for users who want a lean, fast-starting PDF viewer with essential features, without the heavy dependencies of large desktop environments like GNOME or KDE.</p> <p>Enjoy reading with Zathura on i3wm</p> Dual Journaling with Vimwiki: How to Separate Personal and Business Notes Wed, 02 Jul 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/vimwiki-dual-journaling/ https://criticalbasics.xyz/posts/vimwiki-dual-journaling/ <p>In the <a href="https://criticalbasics.xyz/posts/vimwiki-journaling-tutorial/">previous post</a>, we built a powerful journaling system using Vimwiki. It’s a fantastic setup, but as you use it more, a common problem emerges: professional meeting notes mix with personal reflections, and work to-dos get tangled with weekend plans.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-07-02</td><td><strong>Created a direct workflow for general notes:</strong> Added a new custom function (<code>CreateGeneralNote</code>) and corresponding shortcuts (<code>\nb</code>, <code>\np</code>) to directly create topic-based notes with a filename prompt, addressing a major workflow flaw.</td></tr> <tr><td>2025-06-20</td><td>Major Revision: Clarified Wiki vs. Journal distinction, improved naming consistency for directories, and created more intuitive shortcuts.</td></tr> <tr><td>2025-06-19</td><td>Initial version of the article.</td></tr> </tbody></table> </div> <p>This guide will show you how to build a <strong>dual-wiki system</strong> to cleanly separate your personal and business notes. We will cover how to create both daily <strong>Journal Entries</strong> and topic-based <strong>General Notes</strong> in their correct contexts.</p> <h2 id="step-1-understanding-the-structure">Step 1: Understanding the Structure</h2> <p>Before we configure anything, let’s understand the hierarchy we are building. A <strong>Wiki</strong> is the main container for a context (e.g., “Business”). Within that wiki, there are two types of notes:</p> <ul> <li><strong>General Notes:</strong> Topic-based pages like “Project Alpha Ideas” or “Meeting Checklists”. They live in the root of the wiki.</li> <li><strong>Journal Entries:</strong> Date-based, daily logs. They live in the <code>diary/</code> subdirectory.</li> </ul> <p>This is the structure we will create:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>~/Nextcloud/Notes/</span></span> <span class="giallo-l"><span>├── wiki-business/</span></span> <span class="giallo-l"><span>│ ├── diary/</span></span> <span class="giallo-l"><span>│ │ └── 2025-07-04.md</span></span> <span class="giallo-l"><span>│ ├── Project Alpha.md</span></span> <span class="giallo-l"><span>│ └── index.md</span></span> <span class="giallo-l"><span>│ └── template-business-journal.md</span></span> <span class="giallo-l"><span>│</span></span> <span class="giallo-l"><span>└── wiki-personal/</span></span> <span class="giallo-l"><span> ├── diary/</span></span> <span class="giallo-l"><span> │ └── 2025-07-04.md</span></span> <span class="giallo-l"><span> ├── Holiday Plans.md</span></span> <span class="giallo-l"><span> └── index.md</span></span> <span class="giallo-l"><span> └── template-personal-journal.md</span></span></code></pre> <p>This clean separation is the key to an organized system.</p> <h2 id="step-2-update-your-vimwiki-configuration">Step 2: Update Your Vimwiki Configuration</h2> <p>First, configure your <code>~/.vimrc</code> to define the two wikis. Using <code>expand('~')</code> makes the configuration robust.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span style="color: #6A737D;">&quot; Vimwiki Configuration for multiple wikis</span></span> <span class="giallo-l"><span style="color: #F97583;">let</span><span> g:vimwiki_list</span><span style="color: #F97583;"> =</span><span> [</span></span> <span class="giallo-l"><span style="color: #F97583;"> \</span><span> {</span></span> <span class="giallo-l"><span style="color: #F97583;"> \</span><span style="color: #9ECBFF;"> &#39;path&#39;</span><span>: </span><span style="color: #B392F0;">expand</span><span>(</span><span style="color: #9ECBFF;">&#39;~&#39;</span><span>)</span><span style="color: #F97583;"> . </span><span style="color: #9ECBFF;">&#39;/Nextcloud/Notes/wiki-business/&#39;</span><span>,</span></span> <span class="giallo-l"><span style="color: #F97583;"> \</span><span style="color: #9ECBFF;"> &#39;diary_template&#39;</span><span>: </span><span style="color: #9ECBFF;">&#39;template-business-journal.md&#39;</span><span>,</span></span> <span class="giallo-l"><span style="color: #F97583;"> \</span><span style="color: #9ECBFF;"> &#39;syntax&#39;</span><span>: </span><span style="color: #9ECBFF;">&#39;markdown&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;ext&#39;</span><span>: </span><span style="color: #9ECBFF;">&#39;.md&#39;</span></span> <span class="giallo-l"><span style="color: #F97583;"> \</span><span> },</span></span> <span class="giallo-l"><span style="color: #F97583;"> \</span><span> {</span></span> <span class="giallo-l"><span style="color: #F97583;"> \</span><span style="color: #9ECBFF;"> &#39;path&#39;</span><span>: </span><span style="color: #B392F0;">expand</span><span>(</span><span style="color: #9ECBFF;">&#39;~&#39;</span><span>)</span><span style="color: #F97583;"> . </span><span style="color: #9ECBFF;">&#39;/Nextcloud/Notes/wiki-personal/&#39;</span><span>,</span></span> <span class="giallo-l"><span style="color: #F97583;"> \</span><span style="color: #9ECBFF;"> &#39;diary_template&#39;</span><span>: </span><span style="color: #9ECBFF;">&#39;template-personal-journal.md&#39;</span><span>,</span></span> <span class="giallo-l"><span style="color: #F97583;"> \</span><span style="color: #9ECBFF;"> &#39;syntax&#39;</span><span>: </span><span style="color: #9ECBFF;">&#39;markdown&#39;</span><span>,</span><span style="color: #9ECBFF;"> &#39;ext&#39;</span><span>: </span><span style="color: #9ECBFF;">&#39;.md&#39;</span></span> <span class="giallo-l"><span style="color: #F97583;"> \</span><span> }</span></span> <span class="giallo-l"><span style="color: #F97583;">\</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; Optional: Set a default wiki (1=first, 2=second).</span></span> <span class="giallo-l"><span style="color: #F97583;">let</span><span> g:vimwiki_start_wiki</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> 2</span><span style="color: #6A737D;"> &quot; Make the personal wiki the default</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; These settings apply to all wikis in the list</span></span> <span class="giallo-l"><span style="color: #F97583;">let</span><span> g:vimwiki_markdown_link_ext</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> 1</span></span> <span class="giallo-l"><span style="color: #F97583;">let</span><span> g:vimwiki_auto_diary_index</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> 1</span></span></code></pre> <p>Next, create the necessary directories in your terminal:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/Nextcloud/Notes/wiki-business/diary</span></span> <span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/Nextcloud/Notes/wiki-personal/diary</span></span></code></pre><h2 id="step-3-create-context-specific-journal-templates">Step 3: Create Context-Specific Journal Templates</h2> <p>Create a unique template for each journal. Each template file must be placed in the <strong>root directory of its corresponding wiki</strong>.</p> <h4 id="business-journal-template">Business Journal Template</h4> <p>Create the file <code>~/Nextcloud/Notes/wiki-business/template-business-journal.md</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;"># %Y-%m-%d — Business Journal</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## 🎯 Today&#39;s Top 3 Priorities</span></span> <span class="giallo-l"><span style="color: #FFAB70;">-</span><span> [ ] </span></span> <span class="giallo-l"><span style="color: #FFAB70;">-</span><span> [ ] </span></span> <span class="giallo-l"><span style="color: #FFAB70;">-</span><span> [ ] </span></span></code></pre><h4 id="personal-journal-template">Personal Journal Template</h4> <p>Create the file <code>~/Nextcloud/Notes/wiki-personal/template-personal-journal.md</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;"># %Y-%m-%d — Personal Journal</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## 🙏 Gratitude</span></span> <span class="giallo-l"><span style="color: #FFAB70;">-</span><span> </span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## 💡 Ideas &amp; Thoughts</span></span> <span class="giallo-l"><span style="color: #FFAB70;">-</span><span> </span></span></code></pre><h2 id="step-4-the-core-solution-custom-vim-functions">Step 4: The Core Solution: Custom Vim Functions</h2> <p>A standard Vimwiki installation has two limitations for our workflow:</p> <ol> <li><code>:VimwikiMakeDiaryNote</code> does not automatically apply templates.</li> <li>There is no direct command to create a new, named topic note.</li> </ol> <p>We will solve both issues with two dedicated functions in our <code>~/.vimrc</code>.</p> <h4 id="in-your-vimrc">In Your <code>.vimrc</code></h4> <p>Add these two functions and their corresponding shortcuts to your Vim configuration.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span style="color: #6A737D;">&quot; ----- FUNCTION 1: FOR DAILY JOURNAL ENTRIES -----</span></span> <span class="giallo-l"><span style="color: #F97583;">function!</span><span style="color: #B392F0;"> OpenJournalWithTemplate</span><span>(wiki_index)</span></span> <span class="giallo-l"><span style="color: #6A737D;"> &quot; Switch to the correct wiki context</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> execute</span><span style="color: #9ECBFF;"> &#39;VimwikiTabIndex &#39;</span><span style="color: #F97583;"> . </span><span>a:wiki_index</span></span> <span class="giallo-l"><span style="color: #6A737D;"> &quot; Create or open today&#39;s diary note</span></span> <span class="giallo-l"><span> VimwikiMakeDiaryNote</span></span> <span class="giallo-l"><span style="color: #6A737D;"> &quot; CRITICAL: Force Vim to update its state before we check the file</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> redraw</span></span> <span class="giallo-l"><span style="color: #6A737D;"> &quot; Check if the file is new and empty</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #B392F0;"> line</span><span>(</span><span style="color: #9ECBFF;">&#39;$&#39;</span><span>)</span><span style="color: #F97583;"> ==</span><span style="color: #79B8FF;"> 1</span><span style="color: #F97583;"> &amp;&amp; </span><span style="color: #B392F0;">getline</span><span>(</span><span style="color: #79B8FF;">1</span><span>)</span><span style="color: #F97583;"> ==</span><span style="color: #9ECBFF;"> &#39;&#39;</span></span> <span class="giallo-l"><span style="color: #F97583;"> let</span><span> l:wiki_config</span><span style="color: #F97583;"> =</span><span> g:vimwiki_list[a:wiki_index</span><span style="color: #F97583;"> - </span><span style="color: #79B8FF;">1</span><span>]</span></span> <span class="giallo-l"><span style="color: #F97583;"> let</span><span> l:template_path</span><span style="color: #F97583;"> =</span><span> l:wiki_config.path</span><span style="color: #F97583;"> . </span><span>l:wiki_config.diary_template</span></span> <span class="giallo-l"><span style="color: #6A737D;"> &quot; If the template file exists, read its content into our new file</span></span> <span class="giallo-l"><span style="color: #F97583;"> if</span><span style="color: #B392F0;"> filereadable</span><span>(l:template_path)</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> execute</span><span style="color: #9ECBFF;"> &#39;0read &#39;</span><span style="color: #F97583;"> . </span><span>l:template_path</span></span> <span class="giallo-l"><span> 1delete</span><span style="color: #6A737D;"> &quot; Delete the initial empty line</span></span> <span class="giallo-l"><span style="color: #F97583;"> normal!</span><span> gg</span><span style="color: #6A737D;"> &quot; Go to the top</span></span> <span class="giallo-l"><span style="color: #F97583;"> endif</span></span> <span class="giallo-l"><span style="color: #F97583;"> endif</span></span> <span class="giallo-l"><span style="color: #F97583;">endfunction</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; ----- FUNCTION 2: FOR GENERAL TOPIC NOTES -----</span></span> <span class="giallo-l"><span style="color: #F97583;">function!</span><span style="color: #B392F0;"> CreateGeneralNote</span><span>(wiki_index)</span></span> <span class="giallo-l"><span style="color: #6A737D;"> &quot; Switch to the correct wiki context</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> execute</span><span style="color: #9ECBFF;"> &#39;VimwikiTabIndex &#39;</span><span style="color: #F97583;"> . </span><span>a:wiki_index</span></span> <span class="giallo-l"><span style="color: #6A737D;"> &quot; Open the index page of that wiki</span></span> <span class="giallo-l"><span> VimwikiIndex</span></span> <span class="giallo-l"><span style="color: #6A737D;"> &quot; Prompt the user for the name of the new note</span></span> <span class="giallo-l"><span style="color: #F97583;"> let</span><span> l:note_name</span><span style="color: #F97583;"> =</span><span style="color: #B392F0;"> input</span><span>(</span><span style="color: #9ECBFF;">&#39;Enter name for new note: &#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #6A737D;"> &quot; Proceed only if a name was entered</span></span> <span class="giallo-l"><span style="color: #F97583;"> if !</span><span style="color: #B392F0;">empty</span><span>(l:note_name)</span></span> <span class="giallo-l"><span style="color: #6A737D;"> &quot; Go to the end of the index file and add a new link</span></span> <span class="giallo-l"><span style="color: #F97583;"> call</span><span style="color: #B392F0;"> append</span><span>(</span><span style="color: #B392F0;">line</span><span>(</span><span style="color: #9ECBFF;">&#39;$&#39;</span><span>),</span><span style="color: #9ECBFF;"> &#39;* [[&#39;</span><span style="color: #F97583;"> . </span><span>l:note_name</span><span style="color: #F97583;"> . </span><span style="color: #9ECBFF;">&#39;]]&#39;</span><span>)</span></span> <span class="giallo-l"><span style="color: #6A737D;"> &quot; Move the cursor to the newly created line</span></span> <span class="giallo-l"><span style="color: #F97583;"> call</span><span style="color: #B392F0;"> cursor</span><span>(</span><span style="color: #B392F0;">line</span><span>(</span><span style="color: #9ECBFF;">&#39;$&#39;</span><span>),</span><span style="color: #79B8FF;"> 1</span><span>)</span></span> <span class="giallo-l"><span style="color: #6A737D;"> &quot; &#39;Press Enter&#39; on the link to create and open the new file</span></span> <span class="giallo-l"><span> VimwikiFollowLink</span></span> <span class="giallo-l"><span style="color: #F97583;"> endif</span></span> <span class="giallo-l"><span style="color: #F97583;">endfunction</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; ----- KEYBOARD SHORTCUTS -----</span></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; For Journals (e.g., \jb for Journal-Business)</span></span> <span class="giallo-l"><span style="color: #F97583;">nnoremap</span><span> &lt;</span><span style="color: #79B8FF;">leader</span><span>&gt;jb :</span><span style="color: #F97583;">call</span><span style="color: #B392F0;"> OpenJournalWithTemplate</span><span>(</span><span style="color: #79B8FF;">1</span><span>)&lt;</span><span style="color: #79B8FF;">CR</span><span>&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;">nnoremap</span><span> &lt;</span><span style="color: #79B8FF;">leader</span><span>&gt;jp :</span><span style="color: #F97583;">call</span><span style="color: #B392F0;"> OpenJournalWithTemplate</span><span>(</span><span style="color: #79B8FF;">2</span><span>)&lt;</span><span style="color: #79B8FF;">CR</span><span>&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; For General Notes (e.g., \nb for Note-Business)</span></span> <span class="giallo-l"><span style="color: #F97583;">nnoremap</span><span> &lt;</span><span style="color: #79B8FF;">leader</span><span>&gt;nb :</span><span style="color: #F97583;">call</span><span style="color: #B392F0;"> CreateGeneralNote</span><span>(</span><span style="color: #79B8FF;">1</span><span>)&lt;</span><span style="color: #79B8FF;">CR</span><span>&gt;</span></span> <span class="giallo-l"><span style="color: #F97583;">nnoremap</span><span> &lt;</span><span style="color: #79B8FF;">leader</span><span>&gt;np :</span><span style="color: #F97583;">call</span><span style="color: #B392F0;"> CreateGeneralNote</span><span>(</span><span style="color: #79B8FF;">2</span><span>)&lt;</span><span style="color: #79B8FF;">CR</span><span>&gt;</span></span></code></pre><h4 id="in-your-shell-bashrc-or-zshrc">In Your Shell (<code>.bashrc</code> or <code>.zshrc</code>)</h4> <p>Create a full set of aliases in your shell configuration to call these functions directly.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6A737D;"># Aliases for Journal Entries</span></span> <span class="giallo-l"><span style="color: #F97583;">alias</span><span> journalb</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;vim -c &quot;call OpenJournalWithTemplate(1)&quot;&#39;</span></span> <span class="giallo-l"><span style="color: #F97583;">alias</span><span> journalp</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;vim -c &quot;call OpenJournalWithTemplate(2)&quot;&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Aliases for General Topic Notes</span></span> <span class="giallo-l"><span style="color: #F97583;">alias</span><span> noteb</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;vim -c &quot;call CreateGeneralNote(1)&quot;&#39;</span></span> <span class="giallo-l"><span style="color: #F97583;">alias</span><span> notep</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;vim -c &quot;call CreateGeneralNote(2)&quot;&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;"># Optional: Shorter aliases</span></span> <span class="giallo-l"><span style="color: #F97583;">alias</span><span> jb</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;journalb&#39;</span></span> <span class="giallo-l"><span style="color: #F97583;">alias</span><span> jp</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;journalp&#39;</span></span> <span class="giallo-l"><span style="color: #F97583;">alias</span><span> nb</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;noteb&#39;</span></span> <span class="giallo-l"><span style="color: #F97583;">alias</span><span> np</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;notep&#39;</span></span></code></pre> <p>Reload your shell (<code>source ~/.bashrc</code> or <code>source ~/.zshrc</code>) to activate them.</p> <hr /> <h2 id="step-5-how-to-use-your-dual-system">Step 5: How to Use Your Dual System</h2> <p>Your workflow is now clean, logical, and direct for both use cases.</p> <h3 id="workflow-1-create-a-daily-journal-entry">Workflow 1: Create a Daily Journal Entry</h3> <p>Use this for date-based, chronological logs.</p> <ul> <li><strong>From inside Vim:</strong> Press <code>\jb</code> (Business) or <code>\jp</code> (Personal).</li> <li><strong>From your terminal:</strong> Run <code>journalb</code> or <code>jb</code> (Business) / <code>journalp</code> or <code>jp</code> (Personal).</li> </ul> <p><strong>Result:</strong> Today’s journal file is created in the <code>diary/</code> folder, and the correct template is applied.</p> <h3 id="workflow-2-create-a-general-topic-note">Workflow 2: Create a General Topic Note</h3> <p>Use this for any non-daily, topic-based note like a project plan, a checklist, or meeting notes.</p> <ul> <li><strong>From inside Vim:</strong> Press <code>\nb</code> (Business) or <code>\np</code> (Personal).</li> <li><strong>From your terminal:</strong> Run <code>noteb</code> or <code>nb</code> (Business) / <code>notep</code> or <code>np</code> (Personal).</li> </ul> <p><strong>Result:</strong> You will be prompted in Vim to <strong>enter a name for the new note</strong>. After you type a name and press Enter, the new file is created in the root of the correct wiki, and a link to it is automatically added to your <code>index.md</code>.</p> <hr /> <h2 id="step-6-linking-between-wikis">Step 6: Linking Between Wikis</h2> <p>The concept of linking between wikis is now much clearer. Imagine you’re in your <strong>personal journal</strong> and have an idea for a business project.</p> <p>In your personal journal file, you can write:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## 💡 Ideas &amp; Thoughts</span></span> <span class="giallo-l"><span style="color: #FFAB70;">-</span><span> I just had an idea for work, I&#39;ll start a new note for it in my business wiki.</span></span> <span class="giallo-l"><span style="color: #FFAB70;">-</span><span> To create it, I can just write the link here and press Enter: [[wiki1:My New Business Idea]]</span></span></code></pre> <ul> <li><code>wiki1:</code> tells Vimwiki to use the first wiki in your list (your business-wiki).</li> </ul> <p>When you press <code>Enter</code>, Vimwiki creates the file <code>My New Business Idea.md</code> in the root of your <code>wiki-business/</code> and opens it.</p> <hr /> <h2 id="summary">Summary</h2> <p>By creating two dedicated functions, you have built a powerful, intuitive, and robust system:</p> <p>✅ A clean separation between your <strong>wiki-business</strong> and <strong>wiki-personal</strong>. ✅ A clear, direct workflow for creating both daily <strong>Journals</strong> and topic-based <strong>General Notes</strong>. ✅ Custom <strong>journal templates</strong> that are correctly and automatically applied. ✅ Lightning-fast, unambiguous shortcuts (<code>jb</code>, <code>jp</code>, <code>nb</code>, <code>np</code>) for both Vim and your shell. ✅ The power to intelligently link between worlds when needed.</p> <p>This setup transforms a simple note-taking tool into a comprehensive life management system.</p> <p><a rel="noopener external" target="_blank" href="https://github.com/vimwiki/vimwiki">Explore Vimwiki Further</a> 📂</p> <hr /> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ WHAT&#x27;S NEXT? </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Now that your wikis are separated and working reliably, we can explore advanced task management. In a future post, we’ll look at how to aggregate tasks from both journals into a single, unified dashboard.</p> </td> </tr> </table> Mastering the Vimwiki Workflow: A Guide to Links, Navigation, and Tasks Wed, 02 Jul 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/vimwiki-workflow/ https://criticalbasics.xyz/posts/vimwiki-workflow/ <p>In previous guides, we built a robust foundation for our note-taking and journaling system with Vimwiki. But the best configuration is useless without a fluid, daily workflow. So, how exactly do you work with it now?</p> <p>This guide is your daily companion. You will learn the core concepts of Vimwiki that will elevate your productivity to a new level—from the magic of linking and lightning-fast navigation to integrated task management.</p> <hr /> <h2 id="the-heart-of-your-wiki-the-index-md">The Heart of Your Wiki: The <code>index.md</code></h2> <p>Each of your Vim wikis has a central homepage: the <code>index.md</code> file located in the root directory. Think of it as your personal dashboard or table of contents for that wiki.</p> <p>From here, you should link to all of your important, topic-based notes.</p> <ul> <li><strong>How to open the index page:</strong> From anywhere in Vim, press <code>&lt;leader&gt;ww</code> (usually <code>\ww</code>) to instantly jump to the index page of the current wiki.</li> </ul> <p>A well-maintained index might look like this:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;"># Business Wiki Index</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## Projects</span></span> <span class="giallo-l"><span style="color: #FFAB70;">*</span><span> [[Project Alpha]]</span></span> <span class="giallo-l"><span style="color: #FFAB70;">*</span><span> [[Q4 Strategy Planning]]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## Processes &amp; Checklists</span></span> <span class="giallo-l"><span style="color: #FFAB70;">*</span><span> [[Meeting Checklist]]</span></span> <span class="giallo-l"><span style="color: #FFAB70;">*</span><span> [[New Employee Onboarding]]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## References</span></span> <span class="giallo-l"><span style="color: #FFAB70;">*</span><span> [[Important Contacts]]</span></span></code></pre> <hr /> <h2 id="the-magic-of-linking">The Magic of Linking</h2> <p>Creating notes and linking ideas is the core of Vimwiki. The process is brilliantly simple.</p> <ol> <li> <p><strong>Write a Link:</strong> Anywhere in a wiki file, write the name of a new or existing note in double square brackets.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span>I had an idea for [[Project Alpha]].</span></span></code></pre></li> <li> <p><strong>Follow the Link:</strong> Move your cursor over the link and press <code>Enter</code>.</p> </li> </ol> <p><strong>What happens?</strong></p> <ul> <li>If the file <code>Project Alpha.md</code> already exists, Vimwiki opens it.</li> <li>If the file <strong>does not</strong> exist, Vimwiki automatically creates it for you and opens the new, empty file.</li> </ul> <p>This means you never have to worry about manually creating files. You simply write down your thoughts, link concepts, and let Vimwiki build the structure in the background.</p> <p><strong>Pro-Tip:</strong> You can also create subdirectories by using a forward slash: <code>[[projects/New Project]]</code> will create the file <code>New Project.md</code> inside the <code>projects/</code> folder.</p> <hr /> <h2 id="effortless-navigation-how-to-jump-back-and-forth">Effortless Navigation: How to Jump Back and Forth</h2> <p>Switching between notes quickly is crucial. Vimwiki primarily uses Vim’s brilliant, built-in commands for this.</p> <ul> <li><strong>Jump back to the previous note:</strong> Press <code>Ctrl-O</code>. This is the most important navigation command. It takes you right back to where you came from after following a link.</li> <li><strong>Jump forward again:</strong> Press <code>Ctrl-I</code> to reverse the jump.</li> <li><strong>Go back to the index page:</strong> <code>&lt;leader&gt;ww</code> is your “home button,” always taking you back to the main index of the current wiki.</li> <li><strong>Go back to today’s journal:</strong> <code>&lt;leader&gt;w&lt;leader&gt;w</code> (or your custom mappings like <code>\jb</code>/<code>\jp</code>) will instantly take you to your daily journal entry.</li> </ul> <hr /> <h2 id="more-than-just-notes-practical-task-management">More Than Just Notes: Practical Task Management</h2> <p>Vimwiki has fantastic built-in support for to-do lists. Anytime you create a checklist in Markdown format, you can change its status directly in Vim.</p> <p>Write a list like this:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span style="color: #FFAB70;">-</span><span> [ ] Open task</span></span> <span class="giallo-l"><span style="color: #FFAB70;">-</span><span> [ ] Another task that needs to be done</span></span></code></pre> <p>Now, move your cursor onto one of these lines and press <strong><code>g&lt;Space&gt;</code></strong> (that’s <code>g</code> followed by the spacebar).</p> <p>Vimwiki will cycle through the task’s status:</p> <ul> <li><code>[ ]</code> → Open</li> <li><code>[.]</code> → Started / In Progress (optional)</li> <li><code>[X]</code> → Completed</li> <li><code>[-]</code> → Canceled / Irrelevant</li> </ul> <p>This is an incredibly fast and satisfying way to manage tasks without ever leaving Vim.</p> <hr /> <h2 id="important-tips-and-tricks-for-daily-use">Important Tips and Tricks for Daily Use</h2> <ul> <li><strong>Rename Files (and update all links!):</strong> Move your cursor onto a link to a file and run <code>:VimwikiRenameLink</code>. Enter the new name, and Vimwiki will not only rename the file but also <strong>automatically update all other files</strong> that link to that note.</li> <li><strong>Format Tables:</strong> Create a simple table using pipes (<code>|</code>):<pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span>| Column 1 | Column 2 |</span></span> <span class="giallo-l"><span>|---|---|</span></span> <span class="giallo-l"><span>| a | b |</span></span> <span class="giallo-l"><span>| longer text | c |</span></span></code></pre>Then, with your cursor inside the table, run the command <code>:VimwikiTable</code>. Vimwiki will format it perfectly for you.</li> <li><strong>Find Anything:</strong> Use <code>:VimwikiSearch [keyword]</code> to search your entire current wiki. The results are displayed in a handy quickfix list that you can navigate through quickly.</li> </ul> <hr /> <h2 id="summary">Summary</h2> <p>You now have the tools to not just own Vimwiki, but to truly master it:</p> <p>✅ You use the <strong><code>index.md</code></strong> as your central dashboard. ✅ You seamlessly create and connect notes with the <strong><code>[[Link]]</code></strong> syntax. ✅ You navigate at lightning speed with <strong><code>Ctrl-O</code></strong> and <strong><code>&lt;leader&gt;ww</code></strong>. ✅ You manage tasks directly in your notes with <strong><code>g&lt;Space&gt;</code></strong>.</p> <p>This fluid workflow transforms Vimwiki from a simple note-taking tool into a powerful “second brain.”</p> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;vimwiki&#x2F;vimwiki" class="retro-button"> <span class="emoji">📂</span><span class="button-text">EXPLORE VIMWIKI ON GITHUB</span> </a> <hr /> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ WHAT&#x27;S NEXT? </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Now that you’ve mastered the basic workflow, you’re ready for the ultimate organizational boost. In the next article, you’ll learn how to cleanly separate private and business notes with our <a href="/posts/vimwiki-dual-journaling">dual-journaling system</a>.</p> </td> </tr> </table> Getting Started with Vim Plugins: A Beginner's Guide to vim-plug Thu, 26 Jun 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/vim-setup-vim-plug/ https://criticalbasics.xyz/posts/vim-setup-vim-plug/ <p>So you’ve found an exciting Vim plugin—perhaps for journaling with <a href="https://criticalbasics.xyz/posts/vimwiki-journaling-tutorial/">Vimwiki</a>—and you’re ready to supercharge your editor. This guide will walk you through setting up <strong><code>vim-plug</code></strong>, a fast, minimalist, and incredibly popular plugin manager. Once you’ve completed these steps, you’ll have a solid foundation to install any plugin you want, unlocking the true power of Vim.</p> <h2 id="what-is-a-plugin-manager-and-why-vim-plug">What is a Plugin Manager and Why <code>vim-plug</code>?</h2> <p>A plugin manager automates the tedious process of:</p> <ul> <li>Downloading plugin files from sources like GitHub.</li> <li>Placing them in the correct directories.</li> <li>Loading them when Vim starts.</li> <li>Updating and removing them easily.</li> </ul> <p>I recommend <strong><code>vim-plug</code></strong> because it is:</p> <ul> <li><strong>Minimalist:</strong> It’s just a single file, making installation trivial.</li> <li><strong>Fast:</strong> It can install and update plugins in parallel.</li> <li><strong>Easy to Use:</strong> The commands are simple and memorable.</li> </ul> <hr /> <h2 id="step-1-install-vim-plug">Step 1: Install <code>vim-plug</code></h2> <p><code>vim-plug</code> itself needs to be downloaded first. The official and easiest way is to run a single command in your terminal. This command downloads the <code>plug.vim</code> file and places it in Vim’s <code>autoload</code> directory, which ensures it’s loaded automatically when Vim starts.</p> <p>Open your terminal and execute:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">curl</span><span style="color: #79B8FF;"> -fLo</span><span style="color: #9ECBFF;"> ~/.vim/autoload/plug.vim</span><span style="color: #79B8FF;"> --create-dirs \</span></span> <span class="giallo-l"><span style="color: #9ECBFF;"> https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim</span></span></code></pre> <p>That’s it. The plugin manager is now “installed.”</p> <hr /> <h2 id="step-2-structure-your-vimrc-for-plugins">Step 2: Structure Your <code>.vimrc</code> for Plugins</h2> <p>Next, you need to tell Vim which plugins you want to use. This is done in your <code>~/.vimrc</code> file inside a special block.</p> <ol> <li>Open your <code>~/.vimrc</code>.</li> <li>Add the following structure. All your plugin declarations must go <strong>between</strong> the <code>call plug#begin()</code> and <code>call plug#end()</code> lines.</li> </ol> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span style="color: #6A737D;">&quot; 1. VIM-PLUG SECTION</span></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; This block must be at the top of your .vimrc</span></span> <span class="giallo-l"><span style="color: #F97583;">call</span><span style="color: #B392F0;"> plug#begin</span><span>(</span><span style="color: #9ECBFF;">&#39;~/.vim/plugged&#39;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; List your plugins here</span></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; Example:</span></span> <span class="giallo-l"><span style="color: #F97583;">Plug</span><span style="color: #9ECBFF;"> &#39;vimwiki/vimwiki&#39;</span></span> <span class="giallo-l"><span style="color: #F97583;">Plug</span><span style="color: #9ECBFF;"> &#39;dracula/vim&#39;</span><span>, { </span><span style="color: #9ECBFF;">&#39;as&#39;</span><span>: </span><span style="color: #9ECBFF;">&#39;dracula&#39;</span><span> }</span><span style="color: #6A737D;"> &quot; A popular theme</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">call</span><span style="color: #B392F0;"> plug#end</span><span>()</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; 2. YOUR CONFIGURATIONS</span></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; All other settings go AFTER the vim-plug block</span></span> <span class="giallo-l"><span style="color: #F97583;">syntax enable</span></span> <span class="giallo-l"><span style="color: #F97583;">colorscheme</span><span> dracula</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">let</span><span> g:vimwiki_list</span><span style="color: #F97583;"> =</span><span> [{ </span><span style="color: #9ECBFF;">&#39;path&#39;</span><span>: </span><span style="color: #9ECBFF;">&#39;~/vimwiki/&#39;</span><span> }]</span></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; ... and so on</span></span></code></pre> <ul> <li><code>plug#begin()</code>: Initializes the plugin manager. The argument (<code>'~/.vim/plugged'</code>) is the directory where <code>vim-plug</code> will download and store all your plugins.</li> <li><code>Plug 'author/repository'</code>: This is the command to declare a plugin.</li> <li><code>plug#end()</code>: Finalizes the list and loads the plugins.</li> </ul> <hr /> <h2 id="step-3-install-the-plugins-with-pluginstall">Step 3: Install the Plugins with <code>:PlugInstall</code></h2> <p>Now that your <code>.vimrc</code> is configured, you can tell <code>vim-plug</code> to fetch and install the plugins you’ve listed.</p> <ol> <li>Save your <code>~/.vimrc</code> file and <strong>restart Vim</strong>, or source the file with <code>:so ~/.vimrc</code>.</li> <li>Run the <code>vim-plug</code> installation command inside Vim:<pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span>:PlugInstall</span></span></code></pre></li> <li>A new window will open, showing the installation progress for each plugin. Once you see “Finished!”, you can close the status window (<code>:q</code>) and start using your new plugins.</li> </ol> <hr /> <h2 id="your-plugin-management-cheat-sheet">Your Plugin Management Cheat Sheet</h2> <p>Managing plugins is now simple. Here are the essential commands you’ll use:</p> <ul> <li><code>:PlugInstall</code>: Install any new plugins you’ve added to your <code>.vimrc</code>.</li> <li><code>:PlugUpdate</code>: Update all installed plugins to their latest versions.</li> <li><code>:PlugClean</code>: Remove any plugins that are in your <code>plugged</code> directory but no longer listed in your <code>.vimrc</code>.</li> <li><code>:PlugStatus</code>: Show the status of all your plugins.</li> </ul> <hr /> <h2 id="summary-your-foundation-is-ready">Summary: Your Foundation is Ready</h2> <p>Congratulations! You have successfully set up a robust system for managing Vim plugins. You now understand:</p> <ul> <li>How to install <code>vim-plug</code>.</li> <li>How to structure your <code>.vimrc</code> to declare plugins.</li> <li>How to install, update, and manage them with simple commands.</li> </ul> <p>You are now fully equipped to customize Vim to your heart’s content and can confidently follow tutorials like our guides to <a href="https://criticalbasics.xyz/posts/vimwiki-journaling-tutorial/">setting up a Vimwiki journal</a> or creating a <a href="https://criticalbasics.xyz/posts/vimwiki-dual-journaling/">dual-journaling system</a>.</p> <hr /> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ A NOTE ON THE &lt;LEADER&gt; KEY </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Many Vim tutorials (including ours) use shortcuts like <code>&lt;leader&gt;wp</code>. The <code>&lt;leader&gt;</code> key is a placeholder that you can map to any key you want, preventing conflicts with Vim’s built-in commands. By default, it’s the backslash (<code>\</code>).</p> <p>You can set it to a more convenient key, like the comma, by adding this to your <code>.vimrc</code>: <code>let mapleader = ","</code> Now, <code>&lt;leader&gt;wp</code> would be typed as <code>,wp</code>.</p> </td> </tr> </table> Spell Checking in Vim: A Comprehensive Guide Wed, 25 Jun 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/vim-spell-check/ https://criticalbasics.xyz/posts/vim-spell-check/ <p>Spell checking is an essential feature for any editor, and Vim comes with a powerful built-in solution. This guide will walk you through everything you need—from basic activation to advanced customization and keyboard-layout considerations.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-06-25</td><td>Added QWERTZ key mappings and <code>.sug</code> file clarification.</td></tr> <tr><td>2025-06-25</td><td>Initial version of the guide.</td></tr> </tbody></table> </div> <hr /> <h2 id="enabling-spell-checking">Enabling Spell Checking</h2> <p>To enable Vim’s spell checker, use the <code>:set spell</code> command. You can type this directly into Vim for the current session, or add it to your <code>~/.vimrc</code> file for permanent activation.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span>:</span><span style="color: #F97583;">set</span><span style="color: #79B8FF;"> spell</span><span style="color: #6A737D;"> &quot; Turn on spell checking</span></span> <span class="giallo-l"><span>:</span><span style="color: #F97583;">set</span><span style="color: #79B8FF;"> spelllang</span><span style="color: #F97583;">=</span><span>en_us</span><span style="color: #6A737D;"> &quot; Set the default language (e.g., US English)</span></span></code></pre> <p>The first time you set a language, Vim may offer to download the dictionary file for you. This is a one-time setup for each language.</p> <p>For German, switch to:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span>:</span><span style="color: #F97583;">set</span><span style="color: #79B8FF;"> spelllang</span><span style="color: #F97583;">=</span><span>de_de</span><span style="color: #6A737D;"> &quot; Set German dictionary</span></span></code></pre> <p>You can list multiple languages, and Vim will check against all of them:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span>:</span><span style="color: #F97583;">set</span><span style="color: #79B8FF;"> spelllang</span><span style="color: #F97583;">=</span><span>de_de,en_us</span></span></code></pre> <p>Pro-tip: Vim supports regional variants like <code>en_gb</code> (British), <code>en_ca</code> (Canadian), and <code>en_au</code> (Australian).</p> <hr /> <h2 id="managing-spell-files">Managing Spell Files</h2> <p>Vim uses two main types of files for spell checking:</p> <ul> <li>The main dictionary (<code>.spl</code> file), a compressed word list used for all checks.</li> <li>A supplementary suggestions file (<code>.sug</code> file), which pre-computes lists of similar words to provide fast suggestions.</li> </ul> <h3 id="benefits-and-trade-offs-of-the-sug-file">Benefits and Trade-offs of the <code>.sug</code> file</h3> <ul> <li><strong>With</strong> <code>.sug</code> <strong>downloaded</strong>: <code>z=</code> suggestion requests are fast and comprehensive, as Vim doesn’t need to calculate similarities on the fly.</li> <li><strong>Without</strong> <code>.sug</code>: Vim computes suggestions at runtime, saving disk space and RAM until a suggestion is needed.</li> </ul> <h4 id="on-demand-loading">On-Demand Loading</h4> <p>Vim <strong>only loads</strong> the <code>.sug</code> file into memory when you invoke suggestions (e.g., by pressing <code>z=</code>). Simply enabling spell check and navigating errors with <code>]s</code>/<code>[s</code> won’t load the larger <code>.sug</code> file, keeping your memory footprint minimal until you request corrections.</p> <h2 id="quick-navigation-and-corrections">Quick Navigation and Corrections</h2> <ul> <li><code>]s</code> : Jump to the next misspelled word</li> <li><code>[s</code> : Jump to the previous misspelled word</li> <li><code>z=</code> : On a highlighted word, opens the suggestion list</li> <li><code>zg</code> : Add word to <strong>g</strong>ood list (your personal dictionary)</li> <li><code>zw</code> : Mark word as <strong>w</strong>rong</li> </ul> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span style="color: #6A737D;">&quot; Example vimrc settings:</span></span> <span class="giallo-l"><span style="color: #F97583;">set</span><span style="color: #79B8FF;"> spell</span></span> <span class="giallo-l"><span style="color: #F97583;">set</span><span style="color: #79B8FF;"> spelllang</span><span style="color: #F97583;">=</span><span>de_de,en_us</span></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; Optional: Define a custom file for your personal dictionary</span></span> <span class="giallo-l"><span style="color: #F97583;">set</span><span style="color: #79B8FF;"> spellfile</span><span style="color: #F97583;">=~</span><span style="color: #DBEDFF;">/.vim/</span><span style="color: #79B8FF;">spell</span><span>/en.utf-</span><span style="color: #79B8FF;">8</span><span>.add</span></span></code></pre> <hr /> <h2 id="keyboard-layouts-and-key-mappings">Keyboard Layouts and Key Mappings</h2> <p>Vim’s navigation commands rely on specific characters (<code>]</code>, <code>[</code>, <code>s</code>), not on physical keys. Below we cover the standard QWERTY layout and the German QWERTZ variant.</p> <h3 id="international-qwerty-default-mapping">International QWERTY (Default Mapping)</h3> <ul> <li>Press <code>]</code> then <code>s</code> to go to the next misspelling.</li> <li>Press <code>[</code> then <code>s</code> to go to the previous misspelling.</li> </ul> <p>No special configuration is needed on US/UK keyboards, where <code>[</code> and <code>]</code> are directly accessible.</p> <h3 id="german-qwertz-layout">German QWERTZ Layout</h3> <p>On German keyboards, the square brackets require <code>AltGr</code>:</p> <ul> <li><code>[</code>: <code>AltGr + 8</code></li> <li><code>]</code>: <code>AltGr + 9</code></li> </ul> <p>Thus, to navigate spelling corrections:</p> <ul> <li><code>AltGr + 9</code>, then <code>s</code> → <code>]s</code> (next error)</li> <li><code>AltGr + 8</code>, then <code>s</code> → <code>[s</code> (previous error)</li> </ul> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 QUICK KEY MAPPINGS ON QWERTZ </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>To simplify this, add these mappings to your <code>~/.vimrc</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span style="color: #6A737D;">&quot; F7: Next misspelling</span></span> <span class="giallo-l"><span style="color: #F97583;">nnoremap</span><span> &lt;</span><span style="color: #79B8FF;">F7</span><span>&gt; ]s</span></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; F6: Previous misspelling</span></span> <span class="giallo-l"><span style="color: #F97583;">nnoremap</span><span> &lt;</span><span style="color: #79B8FF;">F6</span><span>&gt; [s</span></span></code></pre> <p>We use <code>nnoremap</code> to create a non-recursive mapping in Normal mode, which is the safest way to define custom shortcuts. Now a single press of <code>F7</code> or <code>F6</code> navigates errors without needing <code>AltGr</code>.</p> </td> </tr> </table> <hr /> <h2 id="conclusion">Conclusion</h2> <p>Vim’s spell checker is both versatile and efficient. By understanding its core commands and how to adapt them to your keyboard layout, you can keep your writing error-free across multiple languages. Incorporate these settings into your Vim configuration for a seamless workflow.</p> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ KEY COMMANDS AT A GLANCE </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Quick reference: Navigate Errors with <code>]s</code> (next) and <code>[s</code> (previous); get suggestions with <code>z=</code>; add to dictionary with <code>zg</code>; mark as wrong with <code>zw</code>.</p> </td> </tr> </table> <p>For a deeper dive into all available options, the official documentation is an excellent resource.</p> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;vimhelp.org&#x2F;spell.txt.html" class="retro-button"> <span class="emoji">📖</span><span class="button-text">READ THE OFFICIAL DOCS</span> </a> How to Keep a Structured Markdown Journal Using Vimwiki Thu, 19 Jun 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/vimwiki-journaling-tutorial/ https://criticalbasics.xyz/posts/vimwiki-journaling-tutorial/ <p>Journaling has long been an effective way to reflect, track tasks, and document ideas or conversations. But if you’re a terminal-based user who enjoys the minimalism of Vim, Markdown, and data ownership — you’re in luck. In this post, you’ll learn how to set up a <strong>lightweight, private, and highly productive journaling system</strong> using <a rel="noopener external" target="_blank" href="https://github.com/vimwiki/vimwiki"><code>vimwiki</code></a>, all in plain text files synced via Nextcloud.</p> <p>Whether you’re logging calls, capturing thoughts, or tracking your daily wins, this setup will help you keep everything organized — without giving up control to a third-party app.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-06-19</td><td>Restructured article to move quick access methods into Step 3 for better visibility.</td></tr> <tr><td>2025-06-18</td><td>Major revision: Added to-do lists, improved configuration, and corrected template/alias usage.</td></tr> <tr><td>2025-06-17</td><td>Initial version of this article.</td></tr> </tbody></table> </div> <h2 id="why-use-vimwiki-for-journaling">Why Use Vimwiki for Journaling?</h2> <p><code>vimwiki</code> is a Vim plugin that transforms your editor into a personal wiki. It’s lightweight, fast, and supports:</p> <ul> <li>Daily journal entries (diary mode)</li> <li>Linked notes for projects or topics</li> <li>To-do lists and simple task tracking</li> <li>Markdown syntax for compatibility</li> <li>Full offline access — works with Nextcloud or any sync service</li> </ul> <p>If you’re already storing notes in Markdown, this is a perfect upgrade.</p> <h2 id="step-1-install-vimwiki">Step 1: Install <code>vimwiki</code></h2> <p>Using <a rel="noopener external" target="_blank" href="https://github.com/junegunn/vim-plug"><code>vim-plug</code></a> (or your plugin manager of choice), add this to your <code>.vimrc</code>:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span style="color: #F97583;">Plug</span><span style="color: #9ECBFF;"> &#39;vimwiki/vimwiki&#39;</span></span></code></pre> <p>Then launch Vim and run:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span>:PlugInstall</span></span></code></pre> <p>If you’re not using <code>vim-plug</code>, check the <a rel="noopener external" target="_blank" href="https://github.com/vimwiki/vimwiki">installation instructions here</a>.</p> <hr /> <h2 id="step-2-configure-vimwiki-to-use-markdown">Step 2: Configure Vimwiki to Use Markdown</h2> <p>In your <code>~/.vimrc</code>, configure <code>vimwiki</code> to store files in a Markdown format inside your Nextcloud folder. This configuration is cleaner and easier to maintain.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span style="color: #6A737D;">&quot; Vimwiki Configuration</span></span> <span class="giallo-l"><span style="color: #F97583;">let</span><span> g:vimwiki_list</span><span style="color: #F97583;"> =</span><span> [{</span></span> <span class="giallo-l"><span style="color: #F97583;"> \</span><span style="color: #9ECBFF;"> &#39;path&#39;</span><span>: </span><span style="color: #9ECBFF;">&#39;~/Nextcloud/Notes/wiki/&#39;</span><span>,</span><span style="color: #6A737D;"> &quot; Path to your wiki&#39;s root folder</span></span> <span class="giallo-l"><span style="color: #F97583;"> \</span><span style="color: #9ECBFF;"> &#39;syntax&#39;</span><span>: </span><span style="color: #9ECBFF;">&#39;markdown&#39;</span><span>,</span><span style="color: #6A737D;"> &quot; Use Markdown syntax</span></span> <span class="giallo-l"><span style="color: #F97583;"> \</span><span style="color: #9ECBFF;"> &#39;ext&#39;</span><span>: </span><span style="color: #9ECBFF;">&#39;.md&#39;</span><span style="color: #6A737D;"> &quot; Use .md as the file extension</span></span> <span class="giallo-l"><span style="color: #F97583;">\</span><span>}]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; Ensures that created links include the .md extension for better compatibility</span></span> <span class="giallo-l"><span style="color: #F97583;">let</span><span> g:vimwiki_markdown_link_ext</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> 1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6A737D;">&quot; Automatically creates an index of all diary entries</span></span> <span class="giallo-l"><span style="color: #F97583;">let</span><span> g:vimwiki_auto_diary_index</span><span style="color: #F97583;"> =</span><span style="color: #79B8FF;"> 1</span></span></code></pre> <p>Create the necessary folders manually if they don’t exist:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #B392F0;">mkdir</span><span style="color: #79B8FF;"> -p</span><span style="color: #9ECBFF;"> ~/Nextcloud/Notes/wiki/diary</span></span></code></pre> <hr /> <h2 id="step-3-creating-and-accessing-your-daily-journal">Step 3: Creating and Accessing Your Daily Journal</h2> <p>The core of your journaling workflow is creating or opening the note for the current day. Here are the best ways to do it.</p> <h3 id="the-basic-command">The Basic Command</h3> <p>The fundamental command to create or open today’s journal entry is:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span>:VimwikiMakeDiaryNote</span></span></code></pre> <p>This command will create a file like <code>~/Nextcloud/Notes/wiki/diary/2025-06-21.md</code> if it doesn’t exist, and open it otherwise.</p> <h3 id="recommended-methods-for-quick-access">Recommended Methods for Quick Access</h3> <p>While the basic command works, typing it every time is impractical. For a fast and efficient workflow, use these shortcuts instead.</p> <h4 id="method-1-from-inside-vim-the-fastest-way">Method 1: From Inside Vim (The Fastest Way)</h4> <p><code>vimwiki</code> comes with a built-in keyboard shortcut that is perfect for daily use. While in Vim’s normal mode, simply press:</p> <p><strong><code>&lt;leader&gt;w&lt;leader&gt;w</code></strong></p> <p>This is the most efficient way to open your journal when you are already working in Vim. The <code>&lt;leader&gt;</code> key is typically the backslash (<code>\</code>) by default.</p> <h4 id="method-2-from-your-terminal">Method 2: From Your Terminal</h4> <p>For moments when you want to jump directly into your journal from the command line, a shell alias is the perfect tool. Add this line to your <code>.bashrc</code> or <code>.zshrc</code> file:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F97583;">alias</span><span> journal</span><span style="color: #F97583;">=</span><span style="color: #9ECBFF;">&#39;vim -c &quot;VimwikiMakeDiaryNote&quot;&#39;</span></span></code></pre> <p>After reloading your shell, you can now simply type <code>journal</code> in your terminal. This will launch Vim and immediately open today’s diary entry, applying your template if it’s a new day.</p> <h3 id="example-entry">Example Entry</h3> <p>Regardless of which method you use to open it, your daily note will look something like this:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;"># 2025-06-21</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## 09:02 – Call with Sarah</span></span> <span class="giallo-l"><span>Discussed the project milestones. Need to follow up next Tuesday.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## 13:45 – Idea</span></span> <span class="giallo-l"><span>Use </span><span style="color: #79B8FF;">`jrnl`</span><span> CLI for quick journal entries via terminal.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## 20:15 – Reflection</span></span> <span class="giallo-l"><span>Today was productive. Really enjoying the new Vim-based workflow.</span></span></code></pre> <hr /> <h2 id="step-4-create-and-follow-internal-links">Step 4: Create and Follow Internal Links</h2> <p>Link to another page in your wiki using <code>vimwiki</code>’s native syntax:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span>[[Project Alpha]]</span></span></code></pre> <p>Pressing <code>Enter</code> on this link will create and navigate to <code>Project Alpha.md</code>.</p> <p>For universal compatibility with other Markdown editors (like Obsidian or QOwnNotes), you can use a standard Markdown link. <code>vimwiki</code> will still follow it if you press <code>Enter</code>.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span>[</span><span style="color: #DBEDFF;text-decoration: underline;">Project Alpha</span><span>](</span><span style="text-decoration: underline;">Project%20Alpha.md</span><span>)</span></span></code></pre> <p>The key difference is that <code>[[Project Alpha]]</code> is deeply integrated into <code>vimwiki</code>’s features (like backlinking), while the standard link is more portable across different applications.</p> <hr /> <h2 id="step-5-create-a-diary-template-optional">Step 5: Create a Diary Template (Optional)</h2> <p>Add a default template for your daily entries. It’s best practice to store the template in your wiki’s root directory.</p> <ol> <li> <p>Create the template file: <code>~/Nextcloud/Notes/wiki/template.md</code></p> <p><strong>Important:</strong> <code>vimwiki</code> uses <code>strftime</code> format codes, not <code>{{placeholders}}</code>.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;"># %Y-%m-%d</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## ☎️ Calls</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## 💡 Ideas</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## ✅ Tasks</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## 📌 Notes</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #79B8FF;font-weight: bold;">## 🔁 Reflection</span></span></code></pre></li> <li> <p>Add this line to your <code>.vimrc</code>. Using a relative path makes your config more robust.</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="viml"><span class="giallo-l"><span style="color: #F97583;">let</span><span> g:vimwiki_diary_template</span><span style="color: #F97583;"> =</span><span style="color: #9ECBFF;"> &#39;template.md&#39;</span></span></code></pre></li> </ol> <p>Every new diary file created with <code>:VimwikiMakeDiaryNote</code> (or the shortcuts) will now use this layout.</p> <hr /> <h2 id="bonus-tips">Bonus Tips</h2> <ul> <li><strong>Manage To-Do Lists:</strong> <code>vimwiki</code> has excellent support for task lists. Use <code>g&lt;Space&gt;</code> on a list item in Vim to cycle through states.<pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span style="color: #FFAB70;">-</span><span> [ ] An open task</span></span> <span class="giallo-l"><span style="color: #FFAB70;">-</span><span> [</span><span style="color: #DBEDFF;text-decoration: underline;">.</span><span>] A task in progress</span></span> <span class="giallo-l"><span style="color: #FFAB70;">-</span><span> [</span><span style="color: #DBEDFF;text-decoration: underline;">X</span><span>] A completed task</span></span></code></pre></li> <li><strong>Quick Navigation:</strong> After following a link, press <code>Ctrl-O</code> to go back to the previous location and <code>Ctrl-I</code> to go forward.</li> <li><strong>Diary Index:</strong> Use <code>:VimwikiDiaryIndex</code> to open the <code>diary/index.md</code> — a central view of all your entries.</li> <li><strong>Search:</strong> Use <code>:VimwikiSearch KEYWORD</code> to find entries across your entire wiki.</li> <li><strong>Syncing:</strong> Sync your <code>wiki/</code> folder with <strong>Nextcloud</strong>, and view or edit it from mobile apps like <strong>Markor (Android)</strong> or <strong>1Writer (iOS)</strong>.</li> </ul> <hr /> <h2 id="summary">Summary</h2> <p>With <code>vimwiki</code>, you can build a minimal yet powerful journaling system:</p> <p>✅ Fully Markdown-compatible ✅ Terminal- and Vim-native ✅ Works offline and syncs via Nextcloud ✅ Extendable with links, to-do lists, templates, and more</p> <p>No bloated app, no subscription, no cloud lock-in.</p> <!-- Retro-Button Shortcode using the same styles as tag buttons --> <!-- Usage: retro_button(url="#", text="Click me", icon="🔗") --> <a href="https:&#x2F;&#x2F;github.com&#x2F;vimwiki&#x2F;vimwiki" class="retro-button"> <span class="emoji">📂</span><span class="button-text">TRY VIMWIKI NOW</span> </a> <hr /> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ LOOKING FOR MORE VIM TIPS? </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>In a future post, we’ll explore how to integrate <code>jrnl</code> CLI with <code>vimwiki</code>, add backlinks support, and create a task dashboard — all using plain Markdown.</p> </td> </tr> </table> Retro-Compatible Zola Theme Showcase Mon, 16 Jun 2025 00:00:00 +0000 Unknown https://criticalbasics.xyz/posts/theme-showcase/ https://criticalbasics.xyz/posts/theme-showcase/ <p>Welcome to this comprehensive showcase of the Retro-Compatible Zola Theme! This article demonstrates all the features, elements, shortcodes, and styling options available in this unique theme designed for maximum backward compatibility with browsers dating back to the 90s.</p> <h2 id="changelog">Changelog</h2> <div class="styled-table-container changelog-table"> <table><thead><tr><th>Date</th><th>Change</th></tr></thead><tbody> <tr><td>2025-07-11</td><td>Improved accessibility with skip links, focus indicators, and screenreader support</td></tr> <tr><td>2025-06-16</td><td>Initial version of the theme showcase</td></tr> <tr><td>2025-06-16</td><td>Added code block styling with retro terminal look</td></tr> <tr><td>2025-06-16</td><td>Integration of additional fonts (Visitor, PixelOperator, Petiote, Virtual DJ, 5x5, Ambitsek, AddStandardBitmap)</td></tr> <tr><td>2025-06-16</td><td>Headings highlighted with color (Purple)</td></tr> <tr><td>2025-06-16</td><td>Added changelog table</td></tr> </tbody></table> </div> <hr /> <h1 id="what-is-zola">What is Zola?</h1> <p><a rel="noopener external" target="_blank" href="https://www.getzola.org/">Zola</a> is a blazing-fast static site generator (SSG) written in Rust. It takes your content written in Markdown, applies templates, and generates a complete HTML website that can be served by any web server. Some key features of Zola include:</p> <ul> <li><strong>Speed</strong>: Built with Rust for exceptional performance</li> <li><strong>Simplicity</strong>: Easy to use with a single binary</li> <li><strong>Flexibility</strong>: Powerful templating with Tera</li> <li><strong>Built-in Features</strong>: Syntax highlighting, search, and more</li> <li><strong>Live Reload</strong>: Instant preview of changes during development</li> </ul> <hr /> <h1 id="about-this-theme">About This Theme</h1> <p>The Retro-Compatible Zola Theme combines nostalgic aesthetics with modern functionality, offering:</p> <ul> <li><strong>Maximum Backward Compatibility</strong>: Support for browsers dating back to the 90s</li> <li><strong>Responsive Design</strong>: Optimized for desktop, tablet, and mobile devices</li> <li><strong>Retro Shortcodes</strong>: Special retro-style formatting elements</li> <li><strong>Pixel Fonts</strong>: VT323 and Perfect DOS VGA 437 for the authentic look</li> <li><strong>Three-Column Layout</strong>: Classic web design with modern responsiveness</li> </ul> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ THEME PURPOSE </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>This theme was specifically designed to provide a nostalgic web experience while maintaining compatibility with both vintage and modern browsers. It’s perfect for retro computing enthusiasts, digital preservation projects, or anyone who appreciates the aesthetic of early web design.</p> </td> </tr> </table> <hr /> <h1 id="compatibility-features">Compatibility Features</h1> <h2 id="browser-compatibility">Browser Compatibility</h2> <p>This theme is designed to work with browsers dating back to the 90s, including:</p> <ul> <li>Netscape Navigator 3.0 and earlier</li> <li>Internet Explorer 3.0 and earlier</li> <li>Opera 3.0 and earlier</li> <li>Early WebTV browsers</li> <li>Text-based browsers like Lynx</li> </ul> <h2 id="technical-compatibility-features">Technical Compatibility Features</h2> <ul> <li><strong>HTML 4.01 Strict Doctype</strong>: For maximum compatibility</li> <li><strong>Table-based layouts</strong>: Instead of Flexbox or Grid</li> <li><strong>Simple color definitions</strong>: Using hexadecimal color codes</li> <li><strong>No JavaScript dependencies</strong>: All features work without JavaScript</li> <li><strong>Email-based forms</strong>: For guestbook and contact functionality</li> </ul> <hr /> <h1 id="font-showcase">Font Showcase</h1> <p>This theme uses special pixel fonts to create an authentic retro look. Here’s a showcase of the main fonts used:</p> <h2 id="main-fonts">Main Fonts</h2> <div style="margin: 30px 0; padding: 20px; background-color: #1e1e1e; border: 1px solid #333;"> <p style="font-family: 'VT323', monospace; font-size: 24px; margin-bottom: 10px;"> <strong>VT323</strong>: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*() </p> <p style="font-family: 'Perfect DOS VGA 437', monospace; font-size: 24px; margin-bottom: 10px;"> <strong>Perfect DOS VGA 437</strong>: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*() </p> <p style="font-family: 'Commodore 64', monospace; font-size: 24px; margin-bottom: 10px;"> <strong>Commodore 64</strong>: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*() </p> <p style="font-family: 'Consolas', monospace; font-size: 24px; margin-bottom: 10px;"> <strong>Consolas</strong>: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*() </p> <p style="font-family: 'Courier New', monospace; font-size: 24px; margin-bottom: 10px;"> <strong>Courier New</strong>: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*() </p> <p style="font-family: 'Visitor', monospace; font-size: 24px; margin-bottom: 10px;"> <strong>Visitor</strong>: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*() </p> <p style="font-family: 'PixelOperator', monospace; font-size: 24px; margin-bottom: 10px;"> <strong>PixelOperator</strong>: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*() </p> <p style="font-family: 'Petiote', monospace; font-size: 24px; margin-bottom: 10px;"> <strong>Petiote</strong>: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*() </p> <p style="font-family: 'Virtual DJ', monospace; font-size: 24px; margin-bottom: 10px;"> <strong>Virtual DJ</strong>: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*() </p> <p style="font-family: '5x5', monospace; font-size: 24px; margin-bottom: 10px;"> <strong>5x5</strong>: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*() </p> <p style="font-family: 'Ambitsek', monospace; font-size: 24px; margin-bottom: 10px;"> <strong>Ambitsek</strong>: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*() </p> <p style="font-family: 'AddStandardBitmap', monospace; font-size: 24px; margin-bottom: 10px;"> <strong>AddStandardBitmap</strong>: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*() </p> </div> <hr /> <h2 id="special-font-serenityos-emoji">Special Font: SerenityOS-Emoji</h2> <div style="margin: 30px 0; padding: 20px; background-color: #1e1e1e; border: 1px solid #333;"> <p style="font-family: 'SerenityOS-Emoji'; font-size: 32px; line-height: 1.5; letter-spacing: 5px;"> 😀 😃 😄 😁 😆 😅 😂 🤣 🥲 ☺️ 😊 😇 🙂 🙃 😉 😌 😍 🥰 😘 😗 😙 😚 😋 😛 😝 😜 </p> </div> <h2 id="font-combinations">Font Combinations</h2> <div style="margin: 30px 0; padding: 20px; background-color: #1e1e1e; border: 1px solid #333;"> <h3 style="font-family: 'VT323', 'Perfect DOS VGA 437', monospace; margin-bottom: 15px;"> Header Style (VT323, Perfect DOS VGA 437) </h3> <p style="font-family: 'VT323', monospace; margin-bottom: 15px;"> This is a paragraph in VT323 font. It's designed to look like old terminal text but with better readability for longer content blocks. </p> <p style="font-family: 'Perfect DOS VGA 437', monospace; margin-bottom: 15px; font-size: 16px;"> <code>This is code text in Perfect DOS VGA 437 font.</code> </p> <p><button class="retro-button" style="margin-bottom: 10px; display: block;">Button Text</button></p> </div> <h2 id="font-sizes-comparison">Font Sizes Comparison</h2> <div style="margin: 30px 0; padding: 20px; background-color: #1e1e1e; border: 1px solid #333;"> <h1 style="font-family: 'VT323', 'Perfect DOS VGA 437', monospace;">Heading 1 (26px)</h1> <h2 style="font-family: 'VT323', 'Perfect DOS VGA 437', monospace;">Heading 2 (22px)</h2> <h3 style="font-family: 'VT323', 'Perfect DOS VGA 437', monospace;">Heading 3 (20px)</h3> <p style="font-family: 'VT323', monospace;">Regular paragraph text (20px)</p> <p style="font-family: 'VT323', monospace; font-size: 16px;">Small text (16px)</p> <p style="font-family: 'VT323', monospace; font-size: 14px;">Extra small text (14px)</p> </div> <h1 id="shortcodes">Shortcodes</h1> <p>The theme includes various shortcodes to enhance your content with retro-style elements.</p> <h2 id="infoboxes">Infoboxes</h2> <p>Infoboxes are used to highlight important information in different styles:</p> <h3 id="information-box">Information Box</h3> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ INFORMATION </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>This is a standard information box for general notices and information.</p> </td> </tr> </table> <h3 id="warning-box">Warning Box</h3> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ WARNING </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>This is a warning box for important notices and potential issues.</p> </td> </tr> </table> <h3 id="tip-box">Tip Box</h3> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 TIP </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>This is a helpful tip to improve your experience with the theme.</p> </td> </tr> </table> <h2 id="retro-dividers">Retro Dividers</h2> <p>Dividers help separate content sections with retro-style lines:</p> <h3 id="single-line-divider">Single Line Divider</h3> <!-- Retro-Trennlinie Shortcode - Kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: retro_divider(style="dots") --> <!-- Styles: dots, double, dashed, solid, shadow --> <hr size="1" noshade color="#666666" style="margin: 15px 0;"> <h3 id="double-line-divider">Double Line Divider</h3> <!-- Retro-Trennlinie Shortcode - Kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: retro_divider(style="dots") --> <!-- Styles: dots, double, dashed, solid, shadow --> <hr size="2" noshade color="#666666" style="margin: 15px 0; border-style: double;"> <h3 id="dashed-line-divider">Dashed Line Divider</h3> <!-- Retro-Trennlinie Shortcode - Kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: retro_divider(style="dots") --> <!-- Styles: dots, double, dashed, solid, shadow --> <hr size="1" noshade color="#666666" style="margin: 15px 0; border-style: dashed;"> <h2 id="ascii-art">ASCII Art</h2> <p>The theme supports ASCII art through a dedicated shortcode:</p> <!-- ASCII-Art Shortcode - Kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: ascii_art() mit ASCII-Kunst als Inhalt --> <pre style="font-family: 'Perfect DOS VGA 437', monospace; line-height: 1.0; color: #e0e0e0; background-color: #121212; padding: 15px; border: 1px solid #666666; overflow: auto; white-space: pre; font-size: 14px;">____ _ ____ _ &#x2F; ___|_ __(_) |_ _ _ | __ ) __ _ ___(_) ___ ___ | | | &#x27;__| | __| | | | | _ \ &#x2F; _` &#x2F; __| |&#x2F; __&#x2F; __| | |___| | | | |_| |_| | | |_) | (_| \__ \ | (__\__ \ \____|_| |_|\__|\__, | |____&#x2F; \__,_|___&#x2F;_|\___|___&#x2F; |___&#x2F;</pre> <!-- ASCII-Art Shortcode - Kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: ascii_art() mit ASCII-Kunst als Inhalt --> <pre style="font-family: 'Perfect DOS VGA 437', monospace; line-height: 1.0; color: #e0e0e0; background-color: #121212; padding: 15px; border: 1px solid #666666; overflow: auto; white-space: pre; font-size: 14px;">_____ _____ _____ _____ _____ _____ _____ _____ _____ _____ |_____||_____||_____||_____||_____||_____||_____||_____||_____||_____| _____ _____ |_____| _____ _____ _____ _____ _____ _____ _____ _____ |_____| |_____||_____||_____||_____||_____||_____||_____| _____ _____ |_____| _____ _____ _____ _____ _____ _____ _____ _____ |_____| |_____||_____||_____||_____||_____||_____||_____| _____ _____ |_____||_____||_____||_____||_____||_____||_____||_____||_____||_____|</pre> <!-- ASCII-Art Shortcode - Kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: ascii_art() mit ASCII-Kunst als Inhalt --> <pre style="font-family: 'Perfect DOS VGA 437', monospace; line-height: 1.0; color: #e0e0e0; background-color: #121212; padding: 15px; border: 1px solid #666666; overflow: auto; white-space: pre; font-size: 14px;">_______ _ _ ______ __ __ ______ _______ _ _ _____ ______ _______ ______ |__ __| | | | ____|&#x2F;_ |&#x2F;_ |&#x2F; __ \ \ &#x2F; &#x2F; ____| | | | __ \| ____| &#x2F;\ |__ __| ____| | | | |__| | |__ | | | | | | \ \ &#x2F; &#x2F; (___ | |__| | | | | |__ &#x2F; \ | | | |__ | | | __ | __| | | | | | | |\ \&#x2F; &#x2F; \___ \| __ | | | | __| &#x2F; &#x2F;\ \ | | | __| | | | | | | |____ | | | | |__| | \ &#x2F; ____) | | | | |__| | |____ &#x2F; ____ \ | | | |____ |_| |_| |_|______| |_| |_|\____&#x2F; \&#x2F; |_____&#x2F;|_| |_|_____&#x2F;|______&#x2F;_&#x2F; \_\ |_| |______| _______ _ _ ______ __ __ ______ _______ _ _ _____ ______ _______ ______ |__ __| | | | ____|&#x2F;_ |&#x2F;_ |&#x2F; __ \ \ &#x2F; &#x2F; ____| | | | __ \| ____| &#x2F;\ |__ __| ____| | | | |__| | |__ | | | | | | \ \ &#x2F; &#x2F; (___ | |__| | | | | |__ &#x2F; \ | | | |__ | | | __ | __| | | | | | | |\ \&#x2F; &#x2F; \___ \| __ | | | | __| &#x2F; &#x2F;\ \ | | | __| | | | | | | |____ | | | | |__| | \ &#x2F; ____) | | | | |__| | |____ &#x2F; ____ \ | | | |____ |_| |_| |_|______| |_| |_|\____&#x2F; \&#x2F; |_____&#x2F;|_| |_|_____&#x2F;|______&#x2F;_&#x2F; \_\ |_| |______| _______ _ _ ______ __ __ ______ _______ _ _ _____ ______ _______ ______ |__ __| | | | ____|&#x2F;_ |&#x2F;_ |&#x2F; __ \ \ &#x2F; &#x2F; ____| | | | __ \| ____| &#x2F;\ |__ __| ____| | | | |__| | |__ | | | | | | \ \ &#x2F; &#x2F; (___ | |__| | | | | |__ &#x2F; \ | | | |__ | | | __ | __| | | | | | | |\ \&#x2F; &#x2F; \___ \| __ | | | | __| &#x2F; &#x2F;\ \ | | | __| | | | | | | |____ | | | | |__| | \ &#x2F; ____) | | | | |__| | |____ &#x2F; ____ \ | | | |____ |_| |_| |_|______| |_| |_|\____&#x2F; \&#x2F; |_____&#x2F;|_| |_|_____&#x2F;|______&#x2F;_&#x2F; \_\ |_| |______|</pre> <h2 id="additional-code-examples">Additional Code Examples</h2> <h3 id="rust-example-zola-is-written-in-rust">Rust Example (Zola is written in Rust!)</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F97583;">use</span><span style="color: #B392F0;"> std</span><span style="color: #F97583;">::</span><span style="color: #B392F0;">collections</span><span style="color: #F97583;">::</span><span style="color: #B392F0;">HashMap</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F97583;">fn</span><span style="color: #B392F0;"> main</span><span>() {</span></span> <span class="giallo-l"><span style="color: #6A737D;"> // Create a new HashMap to store user scores</span></span> <span class="giallo-l"><span style="color: #F97583;"> let mut</span><span> scores</span><span style="color: #F97583;"> =</span><span style="color: #B392F0;"> HashMap</span><span style="color: #F97583;">::</span><span style="color: #B392F0;">new</span><span>();</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #6A737D;"> // Insert some values</span></span> <span class="giallo-l"><span> scores</span><span style="color: #F97583;">.</span><span style="color: #B392F0;">insert</span><span>(</span><span style="color: #B392F0;">String</span><span style="color: #F97583;">::</span><span style="color: #B392F0;">from</span><span>(</span><span style="color: #9ECBFF;">&quot;Blue&quot;</span><span>),</span><span style="color: #79B8FF;"> 10</span><span>);</span></span> <span class="giallo-l"><span> scores</span><span style="color: #F97583;">.</span><span style="color: #B392F0;">insert</span><span>(</span><span style="color: #B392F0;">String</span><span style="color: #F97583;">::</span><span style="color: #B392F0;">from</span><span>(</span><span style="color: #9ECBFF;">&quot;Yellow&quot;</span><span>),</span><span style="color: #79B8FF;"> 50</span><span>);</span></span> <span class="giallo-l"><span> scores</span><span style="color: #F97583;">.</span><span style="color: #B392F0;">insert</span><span>(</span><span style="color: #B392F0;">String</span><span style="color: #F97583;">::</span><span style="color: #B392F0;">from</span><span>(</span><span style="color: #9ECBFF;">&quot;Red&quot;</span><span>),</span><span style="color: #79B8FF;"> 25</span><span>);</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #6A737D;"> // Access a value</span></span> <span class="giallo-l"><span style="color: #F97583;"> let</span><span> team_name</span><span style="color: #F97583;"> =</span><span style="color: #B392F0;"> String</span><span style="color: #F97583;">::</span><span style="color: #B392F0;">from</span><span>(</span><span style="color: #9ECBFF;">&quot;Blue&quot;</span><span>);</span></span> <span class="giallo-l"><span style="color: #F97583;"> let</span><span> score</span><span style="color: #F97583;"> =</span><span> scores</span><span style="color: #F97583;">.</span><span style="color: #B392F0;">get</span><span>(</span><span style="color: #F97583;">&amp;</span><span>team_name)</span><span style="color: #F97583;">.</span><span style="color: #B392F0;">unwrap_or</span><span>(</span><span style="color: #F97583;">&amp;</span><span style="color: #79B8FF;">0</span><span>);</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #B392F0;"> println!</span><span>(</span><span style="color: #9ECBFF;">&quot;Team {} score: {}&quot;</span><span>, team_name, score);</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #6A737D;"> // Iterate over all key-value pairs</span></span> <span class="giallo-l"><span style="color: #F97583;"> for</span><span> (key, value)</span><span style="color: #F97583;"> in &amp;</span><span>scores {</span></span> <span class="giallo-l"><span style="color: #B392F0;"> println!</span><span>(</span><span style="color: #9ECBFF;">&quot;{}: {}&quot;</span><span>, key, value);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="html-example">HTML Example</h3> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="html"><span class="giallo-l"><span>&lt;!</span><span style="color: #85E89D;">DOCTYPE</span><span style="color: #B392F0;"> HTML PUBLIC</span><span style="color: #9ECBFF;"> &quot;-//W3C//DTD HTML 4.01//EN&quot; &quot;http://www.w3.org/TR/html4/strict.dtd&quot;</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;</span><span style="color: #85E89D;">html</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;</span><span style="color: #85E89D;">head</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">title</span><span>&gt;Retro Web Page&lt;/</span><span style="color: #85E89D;">title</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">meta</span><span style="color: #B392F0;"> http-equiv</span><span>=</span><span style="color: #9ECBFF;">&quot;Content-Type&quot;</span><span style="color: #B392F0;"> content</span><span>=</span><span style="color: #9ECBFF;">&quot;text/html; charset=utf-8&quot;</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">style</span><span style="color: #B392F0;"> type</span><span>=</span><span style="color: #9ECBFF;">&quot;text/css&quot;</span><span>&gt;</span></span> <span class="giallo-l"><span style="color: #85E89D;"> body</span><span> {</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> background-color</span><span>:</span><span style="color: #79B8FF;"> #000000</span><span>;</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> color</span><span>:</span><span style="color: #79B8FF;"> #33ff33</span><span>;</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> font-family</span><span>:</span><span style="color: #9ECBFF;"> &quot;Courier New&quot;</span><span>,</span><span style="color: #79B8FF;"> monospace</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span style="color: #85E89D;"> table</span><span> {</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> border-collapse</span><span>:</span><span style="color: #79B8FF;"> collapse</span><span>;</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> width</span><span>:</span><span style="color: #79B8FF;"> 100</span><span style="color: #F97583;">%</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span style="color: #85E89D;"> td</span><span> {</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> border</span><span>:</span><span style="color: #79B8FF;"> 1</span><span style="color: #F97583;">px</span><span style="color: #79B8FF;"> solid #444444</span><span>;</span></span> <span class="giallo-l"><span style="color: #79B8FF;"> padding</span><span>:</span><span style="color: #79B8FF;"> 8</span><span style="color: #F97583;">px</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> &lt;/</span><span style="color: #85E89D;">style</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;/</span><span style="color: #85E89D;">head</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;</span><span style="color: #85E89D;">body</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">h1</span><span>&gt;Welcome to My Retro Website&lt;/</span><span style="color: #85E89D;">h1</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">p</span><span>&gt;This is a simple example of HTML 4.01 Strict.&lt;/</span><span style="color: #85E89D;">p</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">table</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">tr</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">td</span><span>&gt;Row 1, Cell 1&lt;/</span><span style="color: #85E89D;">td</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">td</span><span>&gt;Row 1, Cell 2&lt;/</span><span style="color: #85E89D;">td</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span style="color: #85E89D;">tr</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">tr</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">td</span><span>&gt;Row 2, Cell 1&lt;/</span><span style="color: #85E89D;">td</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #85E89D;">td</span><span>&gt;Row 2, Cell 2&lt;/</span><span style="color: #85E89D;">td</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span style="color: #85E89D;">tr</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span style="color: #85E89D;">table</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;/</span><span style="color: #85E89D;">body</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;/</span><span style="color: #85E89D;">html</span><span>&gt;</span></span></code></pre><h1 id="layout-features">Layout Features</h1> <p>The theme uses a three-column layout:</p> <ol> <li><strong>Left Sidebar</strong>: Navigation, search, and status panels</li> <li><strong>Main Content</strong>: Articles and primary content</li> <li><strong>Right Sidebar</strong>: Additional links, visitor counter, and GIF panels</li> </ol> <p>The layout automatically collapses on mobile devices for better readability.</p> <h2 id="retro-panels">Retro Panels</h2> <p>The theme includes various retro-style panels:</p> <ol> <li><strong>Status Panel</strong>: Displays an animated GIF showing the current status</li> <li><strong>Links Panel</strong>: List of useful web links with matching emojis</li> <li><strong>Obligatory GIFs Panel</strong>: Display of animated GIFs in retro style</li> <li><strong>Visitor Counter</strong>: Simulated visitor counter that grows over time</li> </ol> <h1 id="improved-accessibility">Improved Accessibility</h1> <p>The theme has been equipped with numerous accessibility improvements:</p> <ul> <li><strong>Skip Links</strong>: Allow skipping the navigation to get directly to the main content.</li> <li><strong>Focus Indicators</strong>: Clearly visible focus styles for all interactive elements.</li> <li><strong>Screen Reader Support</strong>: Use of ARIA attributes and semantic HTML.</li> <li><strong>High Contrast</strong>: High-contrast color scheme for better readability.</li> </ul> <h1 id="customization-options">Customization Options</h1> <p>The theme offers extensive customization options:</p> <ul> <li><strong>Central configuration</strong> in <code>sass/partials/_variables.scss</code></li> <li><strong>Customizable header</strong> with background image</li> <li><strong>Adjustable logo sizes</strong> for desktop and mobile</li> <li><strong>Configurable GIF panels</strong> in different areas of the page</li> <li><strong>Button styling</strong> and appearance settings</li> </ul> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 CUSTOMIZATION TIP </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>All design elements can be configured centrally in the file <code>sass/partials/_variables.scss</code>, making it easy to maintain a consistent look throughout your site.</p> </td> </tr> </table> <h1 id="form-elements">Form Elements</h1> <p>The theme includes retro-styled form elements:</p> <div style="margin: 30px 0; padding: 20px; background-color: #1e1e1e; border: 1px solid #333;"> <input type="text" class="retro-input-unset" placeholder="Input field text" style="margin-bottom: 10px; display: block;"> <p><button class="retro-button" style="margin-bottom: 10px; display: block;">Button Text</button></p> </div> <h1 id="tables">Tables</h1> <p>The Retro-Compatible Zola Theme offers three different table shortcodes, each optimized for different use cases.</p> <h2 id="table-with-custom-column-widths">Table with Custom Column Widths</h2> <p>The <code>table</code> shortcode allows you to set the width of each column individually. The column widths are specified as percentages and must add up to 100%.</p> <p><strong>Syntax:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>{​% table(cols=&quot;30%,70%&quot;) %​}</span></span> <span class="giallo-l"><span>| Property | Description |</span></span> <span class="giallo-l"><span>|----------|-------------|</span></span> <span class="giallo-l"><span>| Name | The name of the property |</span></span> <span class="giallo-l"><span>| Value | A longer description that needs more space |</span></span> <span class="giallo-l"><span>{​% end %​}</span></span></code></pre> <p><strong>Example:</strong></p> <div class="styled-table-container"> <table id="custom-table" > <colgroup> <col width="30%"> <col width="70%"> </colgroup> <thead><tr><th>Property</th><th>Description</th></tr></thead><tbody> <tr><td>Name</td><td>The name of the property</td></tr> <tr><td>Value</td><td>A longer description that needs more space</td></tr> </tbody> </table> </div> <h3 id="example-with-4-columns-of-different-sizes">Example with 4 Columns of Different Sizes</h3> <p>You can define any number of columns with different widths:</p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>{​% table(cols=&quot;15%,25%,20%,40%&quot;) %​}</span></span> <span class="giallo-l"><span>| ID | Category | Priority | Description |</span></span> <span class="giallo-l"><span>|----|----------|----------|-------------|</span></span> <span class="giallo-l"><span>| 001 | Hardware | High | New graphics card for workstation |</span></span> <span class="giallo-l"><span>| 002 | Software | Medium | Operating system update |</span></span> <span class="giallo-l"><span>| 003 | Network | Low | Office Wi-Fi optimization |</span></span> <span class="giallo-l"><span>{​% end %​}</span></span></code></pre> <p>The result looks like this:</p> <div class="styled-table-container"> <table id="custom-table" > <colgroup> <col width="15%"> <col width="25%"> <col width="20%"> <col width="40%"> </colgroup> <thead><tr><th>ID</th><th>Category</th><th>Priority</th><th>Description</th></tr></thead><tbody> <tr><td>001</td><td>Hardware</td><td>High</td><td>New graphics card for workstation</td></tr> <tr><td>002</td><td>Software</td><td>Medium</td><td>Operating system update</td></tr> <tr><td>003</td><td>Network</td><td>Low</td><td>Office Wi-Fi optimization</td></tr> </tbody> </table> </div> <h2 id="shortcut-table">Shortcut Table</h2> <p>The <code>shortcut_table</code> shortcode is specifically optimized for displaying keyboard shortcuts. It uses fixed column widths (40% for the first column, 60% for the second) to ensure a consistent presentation.</p> <p><strong>Syntax:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>{​% shortcut_table() %​}</span></span> <span class="giallo-l"><span>| Action | Shortcut |</span></span> <span class="giallo-l"><span>|--------|----------|</span></span> <span class="giallo-l"><span>| Copy | Ctrl+C |</span></span> <span class="giallo-l"><span>| Paste | Ctrl+V |</span></span> <span class="giallo-l"><span>{​% end %​}</span></span></code></pre> <p><strong>Example:</strong></p> <div class="styled-table-container shortcut-table"> <table><thead><tr><th>Action</th><th>Shortcut</th></tr></thead><tbody> <tr><td>Copy</td><td>Ctrl+C</td></tr> <tr><td>Paste</td><td>Ctrl+V</td></tr> <tr><td>Save</td><td>Ctrl+S</td></tr> <tr><td>Open</td><td>Ctrl+O</td></tr> </tbody></table> </div> <h2 id="changelog-table">Changelog Table</h2> <p>The <code>changelog_table</code> shortcode is optimized for changelogs. It gives the date column a fixed width (100px) so that dates are displayed uniformly.</p> <p><strong>Syntax:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="plain"><span class="giallo-l"><span>{​% changelog_table() %​}</span></span> <span class="giallo-l"><span>| Date | Changes |</span></span> <span class="giallo-l"><span>|------|--------|</span></span> <span class="giallo-l"><span>| 2025-01-01 | Initial release |</span></span> <span class="giallo-l"><span>| 2025-01-15 | Bug fixes |</span></span> <span class="giallo-l"><span>{​% end %​}</span></span></code></pre> <p><strong>Example:</strong> The changelog table at the beginning of this page uses the <code>changelog_table</code> shortcode.</p> <h2 id="note-on-displaying-shortcode-examples">Note on Displaying Shortcode Examples</h2> <p>To display shortcode examples in the documentation without them being executed, a special trick is used: invisible spaces (Zero-Width Spaces <code>\u200b</code>) are inserted between the curly braces and the percent signs. This prevents Zola from recognizing and executing the shortcodes, but they are not visible to the user.</p> <p>Example: <code>{\u200b% shortcode %\u200b}</code> instead of <code>{% shortcode %}</code> (with an invisible space between <code>{</code> and <code>%</code> and between <code>%</code> and <code>}</code>)</p> <h1 id="markdown-troubleshooting">Markdown Troubleshooting</h1> <h2 id="common-layout-issues">Common Layout Issues</h2> <p>When working with this theme (or any Markdown-based system), certain formatting issues can break your layout. Here are some common problems and solutions:</p> <h3 id="html-like-syntax-in-markdown">HTML-Like Syntax in Markdown</h3> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ffcccc" style="color: #000000; font-weight: bold;"> ⚠️ AVOID RAW HTML TAGS IN TEXT </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>Using angle brackets (<code>&lt;</code> and <code>&gt;</code>) in your Markdown text can cause layout problems because they might be interpreted as HTML tags. This can break the entire page layout if the “tag” is never closed.</p> </td> </tr> </table> <h4 id="problem-example">Problem Example:</h4> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span>Select </span><span style="font-weight: bold;">**&lt;</span><span style="color: #85E89D;font-weight: bold;">Yes</span><span style="font-weight: bold;">&gt;**</span><span> to enable automatic updates.</span></span></code></pre> <p>In this example, <code>&lt;Yes&gt;</code> might be interpreted as an HTML tag named “Yes”, causing layout issues.</p> <h4 id="solutions">Solutions:</h4> <ol> <li> <p><strong>Use quotes instead of angle brackets:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span>Select </span><span style="font-weight: bold;">**&quot;Yes&quot;**</span><span> to enable automatic updates.</span></span></code></pre></li> <li> <p><strong>Use backticks to format as code:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span>Select </span><span style="font-weight: bold;">**</span><span style="color: #79B8FF;font-weight: bold;">`&lt;Yes&gt;`</span><span style="font-weight: bold;">**</span><span> to enable automatic updates.</span></span></code></pre></li> <li> <p><strong>Use HTML entities:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span>Select </span><span style="font-weight: bold;">**&amp;lt;Yes&amp;gt;**</span><span> to enable automatic updates.</span></span></code></pre></li> <li> <p><strong>Use escape characters:</strong></p> <pre class="giallo" style="color: #E1E4E8; background-color: #24292E;"><code data-lang="markdown"><span class="giallo-l"><span>Select </span><span style="font-weight: bold;">**\&lt;</span><span style="color: #85E89D;font-weight: bold;">Yes\</span><span style="font-weight: bold;">&gt;**</span><span> to enable automatic updates.</span></span></code></pre></li> </ol> <h3 id="other-common-markdown-issues">Other Common Markdown Issues</h3> <ul> <li><strong>Unclosed code blocks</strong>: Always ensure your code blocks have opening and closing backticks on their own lines.</li> <li><strong>Malformed tables</strong>: Tables require a specific format with headers and separators.</li> <li><strong>Nested HTML</strong>: Be careful when nesting HTML elements inside Markdown content.</li> </ul> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;"> 💡 DEBUGGING LAYOUT ISSUES </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>If your page layout breaks, try removing sections of content one by one until the layout displays correctly. This can help identify which specific content is causing the problem.</p> </td> </tr> </table> <!-- Retro-Trennlinie Shortcode - Kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: retro_divider(style="dots") --> <!-- Styles: dots, double, dashed, solid, shadow --> <hr size="2" noshade color="#666666" style="margin: 15px 0; border-style: double;"> <hr /> <h1 id="getting-started">Getting Started</h1> <!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre --> <!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box --> <!-- Types: info, warning, tip, note --> <table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1"> <tr> <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;"> ℹ️ GETTING STARTED </td> </tr> <tr> <td bgcolor="#000000" style="color: #ffffff;"> <p>To get started with this theme:</p> <ol> <li>Clone the repository into your Zola <code>themes</code> directory</li> <li>Activate the theme in your <code>config.toml</code></li> <li>Run <code>zola serve</code> to see a preview</li> </ol> <p>For detailed instructions, see the <a href="../../docs/README.md">Main Documentation</a>.</p> </td> </tr> </table> <hr /> <h1 id="conclusion">Conclusion</h1> <p>The Retro-Compatible Zola Theme offers a unique combination of nostalgic design and modern functionality. It’s perfect for:</p> <ul> <li>Retro computing enthusiasts</li> <li>Digital preservation projects</li> <li>Personal websites with a nostalgic touch</li> <li>Anyone who appreciates the aesthetic of early web design</li> </ul>