criticalbasics

Fetch, Review, Accept: Syncing Dotfiles and pass over SSH

Unknown — Thu, 10 Sep 2026 00:00:00 +0000

A useful configuration change should not become a copying exercise every time you switch computers. But a handful of personal machines hardly needs a synchronization platform either.

This guide uses one small routine: when you sit down at a computer, fetch changes from your other reachable computers, inspect them, and decide whether to accept them. Git records the changes; SSH transports them. A short Bash script handles the repetition.

The computers themselves are the peers. Here, “fleet” simply means the few computers you own and administer. Ordinary updates need only a fetch and confirmation. When histories diverge, the script prepares a temporary Git worktree for review; it can then send the accepted result back to the other device after a second confirmation.

Fetch from a known peer
          |
Review changes / resolve conflicts
          |
Accept the local result? [y/N]
          |
Optionally send the result back? [y/N]
          |
Peer checks its checkout before applying

The trade-off is explicit: direct peers must be online at the same time. Commit before leaving one machine, and keep it reachable until the next has fetched those commits. Nothing has to run continuously, but a sleeping laptop cannot serve its repository.

Changelog

Date	Change
2026-09-10	Initial Version: Guide to syncing dotfiles and a pass password store between SSH peers with interactive review, conflict resolution, and optional confirmed return updates.

1. Why Git Fits This Job

Git can fetch from another ordinary checkout over SSH. The remote need not be a hosted service or a bare repository. Fetching downloads history without replacing the current checkout; the downloaded commit is already the intermediate state needed for review. Git fetch documentation

A file synchronizer solves a different problem. Syncthing handles concurrent edits by retaining conflict copies; for configuration, this guide instead keeps the history and the decision to combine changes in Git. Keep live Git repositories outside folders managed by file synchronization software. Syncthing conflict handling

Use two repositories: one for dotfiles and another for the encrypted pass store. Only committed changes travel between peers. This is configuration-file management, not a complete system rebuild: installing packages and configuring system services remain separate tasks.

2. Shared Configuration, Host Differences, and Stow

Keep the shared files together and make the small host-specific parts explicit:

dotfiles/
├── fleet.conf
├── common/
│   └── .config/
│       └── example-app/
│           └── config
└── hosts/
    ├── desktop/
    │   └── .config/example-app/host.conf
    └── laptop/
        └── .config/example-app/host.conf

example-app is a placeholder: use your actual applications and their supported configuration syntax. Where an application supports includes, the shared file can include a local host fragment. Otherwise, keep its entire host-dependent configuration in the host package. Arrange packages so that they do not manage the same file.

GNU Stow links files from these packages into your home directory. Preview before applying, and select exactly one host package:

cd ~/.local/src/dotfiles
stow --simulate --verbose --no-folding --target="$HOME" common
stow --no-folding --target="$HOME" common
stow --dir=hosts --simulate --verbose --no-folding --target="$HOME" desktop
stow --dir=hosts --no-folding --target="$HOME" desktop

Use laptop on the laptop. Resolve existing-file conflicts deliberately before proceeding. --no-folding keeps the directory structure explicit and creates individual file links. Run Stow again when adding newly managed paths. GNU Stow manual

For machines that already have working configurations, start with a file-by-file inventory. Put reviewed, identical files in common; keep intentional differences in the respective host packages. A whole host-specific configuration file is a reasonable starting point when splitting it into includes would add unnecessary work. Track only explicitly selected files, not application caches, histories, session files, or entire configuration directories by default.

Before replacing an existing file with a Stow link, copy its contents and permissions into the intended package and make a separate dated backup outside the repository. Confirm that the package copy matches the live original, then move the original out of the target path. Run Stow’s simulation and apply steps, and verify that the new link resolves to the intended file with the original contents. If installation fails, remove only the links created during that attempt and restore the saved originals. Avoid using --adopt as a shortcut for merging different configurations: it moves existing target files into the package. Stow conflict handling and adoption

Treat theme definitions and hardware settings separately. Share colors, keybindings, and theme-switching scripts; preserve each machine’s DPI, monitor arrangement, and device names. For X resources, one practical arrangement is to assemble common defaults, the selected color palette, and the host’s overrides in that order, then load the result with xrdb. Keep DPI and other hardware values out of the palettes so switching between light and dark does not replace them. Check both modes and a new login. X.Org xrdb manual

Track the sources of generated configuration, rather than giving Stow and a theme switcher competing ownership of the same output. A switcher that replaces a file with mv or recreates a symlink can replace the link Stow installed. In this layout, theme palettes and scripts belong in the repository; the active theme links and assembled resource file are generated locally. Keep the Git checkout outside Syncthing-managed folders even if Syncthing distributes your standalone scripts.

First-Time Setup Is Separate from Everyday Sync

A new machine also needs the programs that read these files. Keep a small, explicit setup routine alongside the dotfiles: a reviewed package list, installation of supporting scripts and fonts, Stow application, and any required service setup. Run it deliberately when onboarding a machine or adding a dependency. The sync script does not install packages, create newly needed Stow links, or activate services. Keep the synchronizer executable itself as an installed copy, rather than a live link to its source in the repository it updates. Install a reviewed script update explicitly on each direct peer.

System configuration needs its own installation step. For example, share the intended appearance of a login manager, but install its configuration under /etc with explicit administrator privileges and a backup. Preserve host-specific session settings. An accepted Git commit must not automatically execute privileged setup or restart the active login session.

Validate workflows, not just file equality: a clipboard shortcut needs its daemon, a status-bar button needs its launcher and application, and a media-control bridge needs a reachable player or server. Record these dependencies in the setup notes. This keeps the everyday sync routine small while making the initial setup repeatable.

⚠️ REVIEW BEFORE UPDATING THE CHECKOUT
Stow links point into the repository. Updating an existing linked file changes the configuration available to the application immediately; there is no separate deployment barrier. Shell startup files can execute commands in the next shell. Review before accepting the merge, then reload applications as appropriate.

Keep private keys, tokens, and plaintext passwords out of the dotfiles repository. An ignore file is a convenience, not a secret detector: inspect what you stage.

For Vim swap files and editor backups, a small .gitignore at the repository root is enough to start:

*.swp
*.swo
*~

Commit this file with your configuration. Ignored, untracked files do not block the script’s clean-checkout check. Keep .orig and .rej files visible for inspection after conflict or patch work rather than ignoring them by default. Ignore rules do not stop tracking files already committed. Git ignore documentation

3. Set Up SSH and the First Repository

The examples assume Linux, Bash, Git, OpenSSH, flock from util-linux, GNU Stow, and pass with GnuPG. Vim supplies the default vimdiff merge editor; whole-file conflict choices do not require an editor. Install them through your distribution’s package manager. Enable the SSH server on machines that should serve repositories, following your distribution’s instructions.

All account names, machine names, paths, and domains below are examples. Replace them with your own. The examples use an ordinary account named user on machines named desktop and laptop, with repositories at the same relative location.

Set your Git author name and email if you have not already done so. On the first machine, create the dotfiles repository, populate it with reviewed configuration files, and make the first commit:

mkdir -p ~/.local/src/dotfiles
cd ~/.local/src/dotfiles
git init -b main
# Add your configuration packages before continuing.
git add common hosts
git commit -m 'Add initial configuration'

Use a separate SSH client key for each device. Verify the destination’s SSH host-key fingerprint through a trusted channel before accepting it. For example, compare the fingerprint displayed during the first connection with the server’s fingerprint viewed locally on that machine:

# Run locally on the destination; this reads its public host key.
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

Use the matching host-key type if the connection presents another type. Then install your client public key using ssh-copy-id user@desktop.local, and test noninteractive authentication:

ssh -o BatchMode=yes -o StrictHostKeyChecking=yes user@desktop.local true

The host key authenticates the destination; your client key authenticates your account access. This workflow trusts those known machines to serve the intended repositories. Manual review checks content; it does not establish the cryptographic authorship of each commit. OpenSSH client settings, ssh-keygen

Clone onto the second machine after SSH works:

mkdir -p ~/.local/src
git clone user@desktop.local:/home/user/.local/src/dotfiles ~/.local/src/dotfiles

Repeat the SSH setup in each direction you intend to fetch. A normal account is the simplest starting point; restrict access further if your threat model requires it. Do not expose SSH publicly just for this workflow.

Names ending in .local require working mDNS on the machines and network; they are not automatic merely because SSH is installed. mDNS is local-link discovery, so these names normally will not work from a café or across routed networks. Existing local DNS names or stable LAN addresses work too. Multicast DNS specification

4. One Peer List, One Interactive Script

Create fleet.conf at the root of the dotfiles repository. Each line contains the peer’s short hostname and its SSH repository URL, separated by whitespace:

# Short hostname    SSH repository URL
desktop    user@desktop.local:/home/user/.local/src/dotfiles
laptop     user@laptop.local:/home/user/.local/src/dotfiles

Commit this file so all clones receive the same list. Labels must match the hostname from uname -n up to the first dot on the corresponding machines, allowing the script to skip itself. Use unique short hostnames. URLs must contain no whitespace. Blank lines and full-line comments are allowed, as are trailing comments introduced by whitespace followed by #. A # within a URL remains part of the URL. The file is read as data, never executed as shell code; malformed entries stop the script with an error.

No git remote add is needed for these peers: Git accepts the URL directly. Adding a machine means adding a line after preparing its SSH access and initial clone. Each repository has its own list because its remote paths differ.

The complete implementation is one standalone Bash script: download fleet-sync. Read it before installing it on each direct peer:

mkdir -p ~/.local/bin
install -m 755 /path/to/downloaded/fleet-sync ~/.local/bin/fleet-sync

Make sure ~/.local/bin is on your interactive shell’s PATH. Run fleet-sync in a terminal; it defaults to ~/.local/src/dotfiles. The repository must already have commits on main and no pending local changes. The script does not automatically create commits for ordinary edits or stash unfinished work.

Before switching devices, commit the changes you want to carry over. For the placeholder layout above:

cd ~/.local/src/dotfiles
git status --short
git diff
git add -- common/.config/example-app/config
git diff --cached
git commit -m 'Adjust example-app settings'

Replace the example path with the specific files you reviewed. Once the checkout is clean, run fleet-sync here to offer the commit to other peers, or fetch it when you arrive at the next device. Equal commits produce no acceptance prompt. Git staging, Git commits

The normal decisions are:

Situation	What the script offers
Both tips are equal	Nothing to do.
The peer is ahead	Show the incoming diff and ask before updating this device.
This device is ahead	Show the outgoing diff and ask whether to update the peer now.
Both made independent commits	Offer an interactive merge, then review the combined result and optionally send it back.

A failed fetch leaves its error visible and moves on. BatchMode=yes prevents interactive SSH authentication prompts; StrictHostKeyChecking=yes requires an already trusted host key. ConnectTimeout=3 limits connection establishment and the initial handshake, not the entire transfer or every name-resolution delay. OpenSSH settings

The peer list is loaded and validated before any peer is processed. The fetched commit ID is fixed for each review; another fetch cannot silently replace the proposal. Nonignored untracked files block updates too. Ignored files may remain, but a merge must not overwrite one that collides with an incoming tracked path.

Updating the Other Device Immediately

SSH access makes a return update possible. After reviewing an outgoing diff, answer the separate prompt:

Proposed update: desktop -> laptop
...
Send and apply this reviewed result on laptop now? [y/N]

This approval authorizes changing the other device’s checkout, including its existing Stow-linked configuration. No second terminal prompt appears there. Applications may read the updated files immediately; the script does not reload them or install new Stow links.

The same script must be installed at ~/.local/bin/fleet-sync on that peer. Git invokes its receiver mode over the existing SSH connection. It transfers the reviewed commit through a temporary Git ref, then the receiver checks that it is still on the expected clean main and applies only a fast-forward. If the target changed, contains unfinished work, is busy, or has a colliding ignored file, the update is refused. A failed return update leaves the accepted local result available for a later retry. The temporary ref is removed on normal completion or handled failure. Git’s custom receive command support provides the transport. Git push documentation

Answer n to leave the other device alone and let it fetch later. A forge with a restricted Git-only SSH service generally cannot run this helper; keep it fetch-only in this script and use an ordinary explicit git push when desired.

More Than Two Devices

Peers are processed sequentially. Each accepted result becomes the starting point for the next comparison; previous approvals are not rolled back if a later peer fails. A peer visited early may need another pass to receive changes discovered later in the list.

A nonblocking flock lock prevents two Fleetsync operations from editing the same repository simultaneously, including the receiver. A busy destination refuses the transfer instead of waiting indefinitely. This coordinates Fleetsync instances, not unrelated editor or Git processes: avoid concurrent manual Git operations in the same checkout. Checks immediately before applying catch common changes during review. flock documentation

5. Use the Same Routine for pass

pass keeps entries encrypted with GnuPG. Start on one machine with the intended recipients’ public keys already imported and a recovery plan for the corresponding private keys. Substitute real public-key fingerprints below:

pass init RECIPIENT_A_FINGERPRINT RECIPIENT_B_FINGERPRINT
pass git init
pass git branch -M main

pass git init records existing contents and configures Git integration; do not add a redundant initialization commit. Clone the resulting store onto another machine only if its destination does not already contain a password store:

git clone user@desktop.local:/home/user/.password-store ~/.password-store

Provision that machine’s decryption key securely and separately, then verify that it can read an entry. Do not put private keys in either repository. pass documentation

If both machines already contain password stores without a shared Git history, stop before cloning or initializing them independently. Back up both stores and compare the encrypted files and recipient configuration first. An entry present on only one device may be a new addition or an intentional deletion on the other; do not automatically take the union. Agree on the intended initial contents, resolve any differing entries deliberately, and create one initial history from that result. Keep the original stores until the replacement and decryption checks succeed.

Add and commit a fleet.conf inside this repository too:

desktop    user@desktop.local:/home/user/.password-store
laptop     user@laptop.local:/home/user/.password-store

pass git add fleet.conf
pass git commit -m 'Add peer list'
fleet-sync ~/.password-store

Keep the confirmation here as well. The script shows additions, modifications, and deletions by filename, plus the text diff for files other than .gpg entries. Inspect recipient changes in .gpg-id carefully: they influence future encryption. Changes to the peer list also deserve review.

A plaintext password comparison is possible: pass git init configures a GPG text-conversion diff driver locally. That Git configuration does not travel with a clone. The script explicitly disables text conversion and excludes encrypted entries from its content diff, so an ordinary sync does not automatically print passwords. Decrypt individual versions deliberately if you need to resolve a password conflict. pass implementation

For a recipient change, first bring the participating machines to a common commit. Run pass init with the complete new recipient list on one machine, inspect its generated commits, and let the others fetch that history. Re-encryption alone does not imply divergent history; independent commits do. Removing a recipient cannot retract old ciphertext or secrets that device already obtained. Rotate affected credentials if access must actually be revoked.

Encryption leaves filenames and Git metadata visible. Choose nonsensitive entry names and protect backups and key recovery material.

6. Resolve Conflicts Without Changing Live Files First

Divergence means both sides contain commits absent from the other. It does not necessarily mean they edited the same lines. The script first shows both histories and asks whether to prepare a merge.

Git performs that merge in a temporary detached worktree, sharing the existing object database. The active checkout and its Stow targets remain unchanged while you review. This is needed for preparing a combined result; ordinary fetch-and-review updates still need no second checkout. Git worktree documentation

Git combines nonconflicting changes. For each remaining conflict, the script identifies the file and offers:

Local = desktop; peer = laptop.
l = whole LOCAL file; p = whole PEER file; e = merge editor; a = abort.
Choose [l/p/e/a]:

l or p selects that side’s entire file, including deletion if it does not exist on that side. To combine individual changes within a text file, choose e. The default is Git’s vimdiff mergetool: LOCAL is this device’s version, REMOTE is the peer’s version, and MERGED is the result to save. You may choose another installed Git mergetool with FLEET_MERGETOOL, for example FLEET_MERGETOOL=meld fleet-sync. Git mergetool documentation

Encrypted .gpg files are never opened in this text editor or decrypted for the displayed diff. Select a complete encrypted version only if you know it is the intended one; otherwise abort and reconcile that entry separately.

After conflict resolution, the script shows the complete proposed change to the local checkout and asks:

Accept and commit this combined result locally? [y/N]

Only y creates the merge commit and fast-forwards the active checkout to it. A conflict-free merge of divergent histories still needs this approval. Aborting or rejecting the result discards the temporary worktree for that peer. After local acceptance, you may separately approve sending the result back. Both original histories remain ancestors of the merge commit, so other peers can receive the convergence through a fast-forward. Git merge documentation

7. Optional Remote and Backups

A private Forgejo repository can provide an extra copy reachable when the direct peers are asleep. If you already use one, push your converged branch to it explicitly:

git remote add forgejo git@forgejo.example.org:example/dotfiles.git
git push forgejo main

Add its SSH URL to fleet.conf under a label such as forgejo if the script should also fetch it. Decline the script’s direct-checkout return update for this remote and use the ordinary push command above instead. Prepare its host key and authentication first. Do the equivalent separately for the password store. This service is optional; it only has commits someone has pushed to it.

Keep independent backups. For a portable Git-history copy, create a bundle outside the checkout, for example on mounted encrypted backup media:

backup_dir=/path/to/mounted/encrypted-backup
bundle="$backup_dir/dotfiles-$(date +%F-%H%M%S).bundle"
git -C ~/.local/src/dotfiles bundle create "$bundle" --all
git -C ~/.local/src/dotfiles bundle verify "$bundle"

Use an existing destination and avoid overwriting an earlier backup. Repeat for the password store. A bundle can seed a clone, but it does not contain uncommitted files, local Git configuration, or private GPG keys; back up recovery material separately. Git bundle documentation

The everyday habit stays small: commit your work; fetch, review, and accept; optionally send the reviewed result back. Add signatures, a fetch-only timer, or VPN reachability later only if a concrete need appears. None is required for a few trusted computers exchanging reviewed changes on the same LAN.

Sources

Duke Nukem II: 5 Handy DOS-Era Tricks for Rigelatin

Unknown — Wed, 09 Sep 2026 00:00:00 +0000

Released for PC in December 1993, Duke Nukem II is Apogee’s colourful 256-colour sequel: four episodes with eight stages apiece, while episode one was the original shareware sampler. GameSpot’s release record and the 3D Realms archive are useful period references.

Five tricks worth remembering

Use the full aiming range. Arrow keys move and aim; Ctrl jumps, Alt fires, and PgUp / PgDn make Duke look up or down. Looking down before a blind drop and aiming up under a ledge makes several enemy placements much less unfair. The control reference documents the keyboard layout.
Restart beacons are your real safety net. Activate one before probing suspicious floors, ceilings, and walls. It moves the retry point forward, so secret hunting costs far less time.
Play the level twice when a secret is tempting. First clear it normally and learn the enemy rhythm; then revisit side passages and odd-looking walls. The first episode contains the famous opening prison sequence and is the best place to learn the game’s visual language.
Keep the registered-version cheats separate from the shareware demo. During play, EAT restores health. NUK (or DUKM) supplies a weapon plus the inventory needed for the current level. These are documented for the PC full game; the shareware episode deliberately rejects cheat input. StrategyWiki’s cheat reference records both the restriction and the effects.
Treat the shareware episode as a proper test run. It is not freeware and not the complete game: it is one episode intended to demonstrate the full release. That distinction matters when collecting old DOS titles.

Play it legally

The archived 3D Realms master download page lists 4duke.zip as the official v1.0 Duke Nukem II shareware episode. The Duke Nukem Repository’s Shareware page also identifies it as the 1.06 MB shareware release. For a complete version, use a current licensed retailer or an official collection rather than treating the shareware episode as the full game.

Sources

3D Realms master download archive — original shareware listing.
Duke Nukem Repository: Shareware — archive details and download classification.
StrategyWiki: Duke Nukem II cheats — cheat behaviour and shareware limitation.
GameSpot: Duke Nukem II — release date, platform, developer and genre record.

⚖ RIGHTS & FAN GUIDE NOTICE

Duke Nukem II. Duke Nukem is a historic Apogee/3D Realms game series; 3D Realms identifies it among its legacy catalogue. This independent, non-commercial guide and its original illustration are not affiliated with or endorsed by any rights holder. The title, characters, game software and original artwork remain with their respective rights holders.

Micro Machines: Tiny Cars, Giant Kitchen-Table Chaos

Unknown — Wed, 09 Sep 2026 00:00:00 +0000

Micro Machines turns ordinary surfaces into impossibly fast racetracks: breakfast tables, desks, bathtubs and garden furniture become worlds for toy-sized vehicles. The series began on NES in 1991; the MS-DOS port arrived in 1994 and was developed by Big Red Software. The release overview lists the DOS version alongside the other ports, while the original manual makes its toy licence unusually explicit: the Micro Machines mark belonged to Lewis Galoob Toys and Codemasters used it under licence.

The central idea is wonderfully mean: this is a top-down racer, but the tight single-screen duel rewards gaining a whole screen length over the other driver, rather than merely counting down a lap timer. The gameplay history explains the resulting colour-light score system and why it was used instead of split-screen.

The useful stuff the game barely tells you

Steer for the car’s direction, not the screen. The manual says left and right rotate the vehicle anti-clockwise and clockwise regardless of whether it currently points up or down. That sounds obvious, but it is the source of many first-lap crashes: resist “screen-left” instincts and steer as though holding a tiny physical car. Original control notes
Use the qualifier as a handling laboratory. The opening Micro Machines Challenge race takes place in a bathtub and is explicitly described as a place to practise. Test the turn-in point with no ambition to win, then repeat with a shorter acceleration burst before the next corner. Original manual: qualifier race
Brake early; reverse is a recovery tool. Holding the fire control accelerates until full speed. Moving down while already travelling forward slows the vehicle; once stopped, it becomes reverse. That makes a tiny correction after a missed corner much cheaper than a wide high-speed loop around the table. Original control notes
Second place is success in Challenge. A first- or second-place finish advances you to another track and vehicle. Third or fourth costs a chance and repeats the course; the run starts with three chances. Treat a safe second as a genuine tactical result, especially on an unfamiliar vehicle class. Original Challenge rules
The route is the real opponent. Every course has a defined path; lingering off it sends a car back onto the circuit. So a dramatic-looking shortcut over crumbs, paper or carpet is usually slower unless it reconnects immediately. The top-down route rule is explained in the gameplay reference.
Head-to-head is a score-light tug-of-war. Both sides begin with four coloured lights. Pull a screen ahead and one light changes to your colour; take all eight, or lead after three laps, to win. A tie goes to sudden death. It means that a clean escape from one corner can matter more than defending every pixel of the lap. Original head-to-head rules
Choose opponents with the campaign in mind. After qualifying, the manual lets you select three opponents, then replace drivers as they drop out. It even advises reserving weaker characters for later rounds. That is a rare bit of tournament planning hiding inside an arcade racer. Original opponent-selection notes
Do not copy random console cheats into DOS. Cheats documented online are often explicitly tied to CD-i, Master System, Game Gear or NES releases—for example, the hard-mode sequences and the secret-credits trick. They are interesting port trivia, but not verified DOS codes. Version-labelled cheat list
A famous bug belongs to the NES original, too. The first race could crash if the player reversed; the fix was a small add-on in affected cartridges. It is a great piece of launch-era lore, but it is not a reason to expect the DOS port to reproduce it. Development history

Play it legally

The surviving DOS manual is useful documentation, but it is not a licence to redistribute the game. I have not found a current authorised DOS download from the rights holders, so the sensible route is original media or a verified authorised re-release if one becomes available. The period manual itself identifies the Galoob trademark licence and Codemasters copyright notice. Manual copyright and trademark page

Sources

Micro Machines DOS manual — controls, Challenge rules, head-to-head scoring, settings and original rights notice.
Micro Machines release and development overview — DOS release year, platforms, top-down route mechanic and development trivia.
GameFAQs version-labelled codes — comparison point for cheats that belong to other ports rather than DOS.

⚖ RIGHTS & FAN GUIDE NOTICE

Micro Machines. The original DOS manual identifies Micro Machines as a registered trademark of Lewis Galoob Toys, Inc. and credits Codemasters Software Company Ltd. for the game. This independent, non-commercial guide and its original illustration are not affiliated with or endorsed by the trademark or copyright owners. Game software, names, characters and original art remain with their respective rights holders.

Stunts: The DOS Racer That Lets You Build the Impossible

Unknown — Wed, 09 Sep 2026 00:00:00 +0000

Stunts (also sold as 4D Sports Driving) is a 1990 DOS racing game by Distinctive Software. Its enduring trick is simple: race against an opponent, then build a more ridiculous course and save the replay. It has 11 cars, automatic or manual transmission, multiple camera angles and a grid-based track editor. Wikipedia’s overview and the Stunts Wiki version notes give the useful release context.

Five tricks for better laps and better tracks

Drive from the keyboard first. Ctrl+K switches to keyboard control; Ctrl+J calibrates and switches to joystick control. The old analogue-joystick default can feel imprecise on modern setups, so keyboard steering is an excellent baseline. Luke’s key reference documents both modes.
Use the replay as a diagnostic tool. During a replay, R toggles the VCR panel. F1–F4, C, D, T and P retain their driving-view functions, so watch the same jump from more than one camera before blaming the car. The original manual’s reference card lists R as the replay-panel toggle. Manual scan
Make the approach to a stunt boring. Give a loop, ramp or corkscrew a straight approach and a straight exit. A difficult stunt after a blind bend mostly tests luck; a clean approach lets you learn speed and steering.
Build with the editor’s limits in mind. The original editor is tile-based, which is why tracks can create wonderfully abrupt transitions. Use it deliberately: first make a reliable closed lap, then add one stunt section at a time. The Stunts Wiki notes that v1.1 from February 1991 is the usual version for current competitions.
Race your own ghost. Save a clean replay before experimenting. It gives you a personal benchmark and preserves the satisfying evidence when a wild shortcut finally works.

Play it legally

The Stunts Wiki download page distinguishes the historical v1.0 and v1.1 releases, provides manual scans and explains the modern DOSBox requirement. It also points to the preserved v1.1 disk copy. Treat this as preservation information: verify the licensing position in your jurisdiction before downloading a game package, and prefer an authorised re-release where one is available.

Sources

Stunts Wiki: Download — version history, manuals and modern-running notes.
Luke’s 4D Sports Driving page — driving, replay and editor key reference.
4D Sports Driving manual — original control reference.
German Wikipedia overview — game and editor overview.

⚖ RIGHTS & FAN GUIDE NOTICE

Stunts / 4D Sports Driving. The game was developed by Distinctive Software and historically published by Broderbund and Mindscape, as documented by DOS Days. Rights in the game, its names and its original artwork remain with their respective holders. This independent, non-commercial guide and its original illustration are not affiliated with or endorsed by them.

Total Recall (1990): Details Worth a Second Memory

Unknown — Wed, 09 Sep 2026 00:00:00 +0000

Paul Verhoeven’s Total Recall (1990), starring Arnold Schwarzenegger as Douglas Quaid, turns a Mars holiday into a question about memory, identity and whether an adventure can be too perfectly tailored. It is a loose adaptation of Philip K. Dick’s 1966 story We Can Remember It for You Wholesale, whose original premise already pairs an ordinary man, an unaffordable Mars trip and purchased memories. Philip K. Dick’s archive gives the useful literary starting point.

Details worth watching for

Watch the Rekall sales pitch as a checklist. It promises a very specific fantasy: Mars, espionage, romance and a mission. The film later keeps returning to those ingredients. That does not prove one reading of the ending, but it makes the “implant gone wrong” interpretation deliberately tempting.
The film preserves two possible realities. Edgemar’s warning sounds tailored to Quaid’s experience, and IMDb’s production trivia notes that several of his predictions are echoed visually later. The white fade-out is therefore less a solution than a prompt to revisit the film with the opposite interpretation in mind. IMDb trivia
Mexico City provides much of its future concrete. The production began there because the Metro’s angular, brutalist architecture looked futuristic and Estudios Churubusco could hold the huge indoor sets. Mars feels like a constructed world because, in large part, it literally was one. IMDb production trivia
The special effects were formally exceptional. The Academy gave Total Recall a Special Achievement Award for Visual Effects at the 63rd Academy Awards. It is a useful reminder to look for physical transformations, miniature-scale machinery and makeup effects rather than assuming the spectacle was computer-generated. Academy Awards database
Compare the story’s name before and after the adaptation. Dick’s protagonist is Douglas Quail, not Quaid, and he dreams of Mars before he can afford to go there. The film expands that compact identity puzzle into a muscular conspiracy thriller; reading the short story afterwards highlights exactly what changed. Story background

Sources

Philip K. Dick: story background and story text/archive.
IMDb: Total Recall trivia — production and narrative-detail reference.
Academy Awards database — 1990 Special Achievement Award for Visual Effects.

⚖ RIGHTS & FAN GUIDE NOTICE

Total Recall (1990). The 1990 film is presented by Paramount Pictures. The title, characters, screenplay, original imagery and film footage remain with their respective rights holders. This independent, non-commercial guide and its original pixel-art illustration are not affiliated with or endorsed by Paramount or any other rights holder.

Deploying the Nextcloud Talk AIO Recording Backend as a Standalone Container

Unknown — Sun, 06 Sep 2026 00:00:00 +0000

This guide deploys the official Nextcloud AIO Talk Recording image as a standalone container. It complements an existing Nextcloud Talk High-Performance Backend and does not require a full Nextcloud AIO installation.

The recording backend joins Talk calls as a participant, captures the selected media, and uploads the result back to Nextcloud. It needs its own resources, storage for temporary recordings, and a secure internal connection to the matching signaling backend.

The deployment uses the pre-built image from the Nextcloud AIO project and follows the upstream Recording Backend installation documentation.

⚠️ RECORDING IS A SEPARATE COMPONENT
The standalone AIO Talk container provides signaling, Janus, NATS, and TURN. It does not include recording. Deploy the Recording Backend separately and configure it in Nextcloud Talk afterwards.

Changelog

Date	Change
2026-09-06	Initial Version: Added the standalone AIO Talk Recording Backend guide.

1. Prerequisites

You need:

A working Nextcloud Talk installation.
A working Talk High-Performance Backend (HPB).
Docker Engine and Docker Compose v2.
A Traefik v3 reverse proxy on an external Docker network named proxy.
A DNS name and TLS certificate for the recording endpoint, or a dedicated path below the existing signaling hostname.
At least 2 GB of shared memory available to the recording container.

This guide is designed to follow Running the Nextcloud Talk AIO Container as a Standalone High-Performance Backend.

The following internal tutorials provide the surrounding infrastructure:

For Compose syntax, reverse-proxy behavior, and trusted-proxy settings, see the Docker Compose documentation, Traefik documentation, and Nextcloud reverse-proxy documentation.

ℹ️ PLAN CAPACITY FOR RECORDINGS
Recording uses a browser, video capture, and transcoding. CPU, memory, and temporary storage requirements rise with the number, duration, and resolution of concurrent recordings. Start with one recorder per HPB and monitor it before increasing capacity.

2. Create the project directory and secrets

Create an isolated project directory:

sudo mkdir -p /opt/containers/nextcloud-aio-talk-recording
cd /opt/containers/nextcloud-aio-talk-recording
sudo chmod 700 .

Generate a new recording secret:

openssl rand -hex 32

The INTERNAL_SECRET is not a new value: it must be the same value used by the corresponding AIO Talk container. The recording backend uses it to authenticate to that signaling server.

Create .env and replace every placeholder:

sudo tee .env > /dev/null << 'EOF'
# The existing Nextcloud hostname, without https://
NC_DOMAIN=cloud.example.com

# The public hostname of the matching AIO Talk backend
HPB_DOMAIN=talk.example.com

# Leave empty for a dedicated hostname, or use a matching Traefik path prefix
HPB_PATH=

# Generate this specifically for the recording backend.
RECORDING_SECRET=REPLACE_WITH_A_RANDOM_64_HEX_CHARACTER_SECRET

# Copy this value from the matching AIO Talk container only.
INTERNAL_SECRET=REPLACE_WITH_THE_MATCHING_TALK_INTERNAL_SECRET
EOF

sudo chmod 600 .env

⚠️ KEEP THE TWO SECRETS DISTINCT
`RECORDING_SECRET` is shared with Nextcloud’s Recording Backend setting. `INTERNAL_SECRET` is shared only with the matching Talk HPB. Do not reuse either value between unrelated Nextcloud instances.

3. Create the Docker Compose file

The example below exposes the recorder through a dedicated hostname. It stores temporary recordings in a named Docker volume and gives the browser enough shared memory.

sudo tee docker-compose.yml > /dev/null << 'EOF'
services:
  recording:
    image: ghcr.io/nextcloud-releases/aio-talk-recording:latest
    container_name: nextcloud-aio-talk-recording
    user: "122"
    init: true
    restart: unless-stopped
    read_only: true
    shm_size: 2gb
    tmpfs:
      - /conf
    env_file:
      - .env
    environment:
      ALLOW_ALL: "false"
      SKIP_VERIFY: "false"
      NC_PROTOCOL: https
      HPB_PROTOCOL: https
      AIO_LOG_LEVEL: warn
      TZ: Europe/Vienna
    volumes:
      - recording-tmp:/tmp
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.nextcloud-aio-talk-recording.rule=Host(`recording.example.com`)"
      - "traefik.http.routers.nextcloud-aio-talk-recording.entrypoints=websecure"
      - "traefik.http.routers.nextcloud-aio-talk-recording.tls=true"
      - "traefik.http.routers.nextcloud-aio-talk-recording.middlewares=nextcloud-aio-talk-recording-headers@docker,crowdsec-bouncer@docker"
      - "traefik.http.middlewares.nextcloud-aio-talk-recording-headers.headers.customRequestHeaders.X-Forwarded-Proto=https"
      - "traefik.http.services.nextcloud-aio-talk-recording.loadbalancer.server.port=1234"

volumes:
  recording-tmp:

networks:
  proxy:
    external: true
EOF

ℹ️ USING A PATH PREFIX
If the recorder is published at a path such as `https://talk.example.com/recording-one`, change the Traefik router rule to include `PathPrefix`, add a `StripPrefix` middleware, and use the same full URL in the Nextcloud Recording Backend setting. `HPB_PATH` is independent: it points from the recorder to its matching Talk signaling endpoint.

4. Start and verify the recorder

Pull and start the image:

cd /opt/containers/nextcloud-aio-talk-recording
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps

Wait until Docker reports a healthy container:

sudo docker inspect nextcloud-aio-talk-recording \
  | sed -n '/"Health": {/,/},/p'

Inspect logs when the health check does not become healthy:

sudo docker logs --tail 100 nextcloud-aio-talk-recording

The recorder must be able to resolve and reach both NC_DOMAIN and the signaling URL constructed from HPB_DOMAIN and HPB_PATH.

5. Configure the Recording Backend in Nextcloud Talk

In Nextcloud, open Administration settings → Talk and enter:

Setting	Value
Recording backend URL	`https://recording.example.com`
Shared secret	The value of `RECORDING_SECRET`
Verify SSL certificate	Enabled

Save the settings and confirm that the Talk setup check reports a successful Recording Backend.

⚠️ MIGRATE BEFORE REMOVING THE OLD RECORDER
When replacing an existing recording service, start and health-check the new recorder first. Change the Nextcloud setting, verify the Talk setup check, and make a real recording before stopping the old service.

6. Make a real recording test

The health check proves that the container starts, but it cannot verify browser capture, TURN fallback, or upload permissions. Create a test room and:

Start an audio/video recording as a room moderator.
Let the call run briefly and stop the recording.
Confirm that the recording appears in the configured Nextcloud location and can be played.
Check the recorder logs while the recording is being processed.

sudo docker logs -f nextcloud-aio-talk-recording

7. Multiple independent Nextcloud instances

Use a separate recorder for every isolated AIO Talk container.

Item	First instance	Second instance
Recording project	`nextcloud-aio-talk-recording-one`	`nextcloud-aio-talk-recording-two`
Recording endpoint	`recording-one.example.com`	`recording-two.example.com`
`NC_DOMAIN`	`cloud-one.example.com`	`cloud-two.example.com`
HPB endpoint	`talk-one.example.com`	`talk-two.example.com`
`INTERNAL_SECRET`	From Talk container one	From Talk container two
`RECORDING_SECRET`	Unique to instance one	Unique to instance two

Do not point one recorder at two isolated AIO Talk containers. The internal signaling secret must match the one HPB that the recorder joins.

8. Maintenance and troubleshooting

Update the image during a maintenance window:

cd /opt/containers/nextcloud-aio-talk-recording
sudo docker compose pull
sudo docker compose up -d

Before updating, back up .env and docker-compose.yml. The temporary recording volume is cleared by the container at startup; failed or in-progress recordings should therefore be investigated before restarting it.

If recordings fail:

Confirm that both the recorder and the matching Talk HPB are healthy.
Confirm that INTERNAL_SECRET matches the matching AIO Talk container exactly.
Confirm that RECORDING_SECRET matches the Talk administration setting exactly.
Check available RAM, /dev/shm, disk capacity, and container logs.
Verify that the recorder can reach Nextcloud and the Talk endpoint using valid TLS certificates.

For upstream configuration details, consult the official Nextcloud Talk Recording installation documentation.

Running the Nextcloud Talk AIO Container as a Standalone High-Performance Backend
Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack
Deploying the classic Nextcloud Talk High-Performance Backend with Docker — retained as an archive and migration reference.

Running the Nextcloud Talk AIO Container as a Standalone High-Performance Backend

Unknown — Sun, 06 Sep 2026 00:00:00 +0000

This guide deploys the official pre-built Nextcloud Talk container as a standalone High-Performance Backend (HPB). It is intended for an existing, non-AIO Nextcloud installation and does not migrate Nextcloud, its database, files, or reverse proxy to Nextcloud All-in-One.

The container bundles the components needed for a modern Talk backend: the signaling server, Janus media gateway, NATS, and an integrated TURN service. Compared with maintaining the classic multi-container signaling stack yourself, it removes the custom builds and most component-level configuration.

It follows the upstream Nextcloud Talk quick-install documentation and uses the pre-built image maintained in the Nextcloud AIO project.

ℹ️ WHAT THIS GUIDE INSTALLS
This is the AIO Talk container only, not the complete Nextcloud AIO appliance. Your existing Nextcloud Docker Compose stack stays in place and is configured to use this backend afterwards.

Changelog

Date	Change
2026-09-06	Initial Version: Added the standalone AIO Talk container tutorial.

1. Prerequisites

This guide assumes that you already have:

A working Nextcloud instance with the Talk app enabled.
Docker Engine and Docker Compose v2.
A Traefik v3 reverse proxy with a shared external Docker network named proxy.
A dedicated DNS name for the signaling and TURN service, such as talk.example.com, pointing to the Docker host.
A valid TLS certificate for that DNS name.
sudo or root access on the Docker host.

The reverse-proxy setup from the following guide is a suitable foundation:

Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack
Debian Server Initial Setup for a baseline host and firewall configuration.

For Docker Compose fundamentals and reverse-proxy behavior, refer to the Docker Compose documentation and the Traefik documentation. If your Nextcloud instance is already behind a proxy, also verify the Nextcloud reverse-proxy settings.

⚠️ ONE CONTAINER, ONE NEXTCLOUD BACKEND
The standalone AIO Talk container creates one configured signaling backend from `NC_DOMAIN`. Do not add multiple unrelated Nextcloud URLs to one container. For two independent Nextcloud instances, deploy two containers with separate endpoints, secrets, and TURN ports as shown in section 8.

1.1. Firewall configuration

The reverse proxy handles HTTPS on ports 80 and 443. The integrated TURN server must be reachable directly on the Talk port over both TCP and UDP. The examples use 3478.

sudo ufw allow 3478/tcp
sudo ufw allow 3478/udp

If your firewall is managed by a cloud provider or hardware router, open and forward the same two ports there as well.

ℹ️ TURN IS NOT HTTP TRAFFIC
The TURN port bypasses Traefik and its HTTP middleware. Keep the Talk container updated, use a long random TURN secret, and restrict host access with your firewall policy where appropriate.

2. Create the project directory and secrets

Create a dedicated directory for the backend. Keeping the .env file separate prevents secrets from being committed or copied into a public Compose example.

sudo mkdir -p /opt/containers/nextcloud-aio-talk
cd /opt/containers/nextcloud-aio-talk
sudo chmod 700 .

Generate three independent secrets:

openssl rand -hex 32
openssl rand -hex 32
openssl rand -hex 32

Create .env and replace every placeholder. NC_DOMAIN and TALK_HOST are host names only, without https:// or a path.

sudo tee .env > /dev/null << 'EOF'
# Existing Nextcloud instance that will use this container
NC_DOMAIN=cloud.example.com

# Public DNS name for signaling and TURN
TALK_HOST=talk.example.com

# Keep all three values private and use different random values.
TURN_SECRET=REPLACE_WITH_A_RANDOM_64_HEX_CHARACTER_SECRET
SIGNALING_SECRET=REPLACE_WITH_A_RANDOM_64_HEX_CHARACTER_SECRET
INTERNAL_SECRET=REPLACE_WITH_A_RANDOM_64_HEX_CHARACTER_SECRET
EOF

sudo chmod 600 .env

The secrets have different roles:

Secret	Purpose	Used in Nextcloud?
`SIGNALING_SECRET`	Authenticates the Nextcloud server to the signaling backend.	Yes
`TURN_SECRET`	Creates short-lived TURN credentials for Talk clients.	Yes
`INTERNAL_SECRET`	Protects internal communication within the backend.	No

⚠️ DO NOT REUSE PLACEHOLDER VALUES
Never use the placeholder strings from this article. Generate unique random secrets for every Talk container and store the `.env` file in your password manager or encrypted backup.

3. Create the Docker Compose file

The following Compose file uses Traefik for TLS and WebSocket forwarding. The TURN service is published directly on port 3478, while signaling remains internal and is exposed only through Traefik on port 8081.

sudo tee docker-compose.yml > /dev/null << 'EOF'
services:
  talk:
    image: ghcr.io/nextcloud-releases/aio-talk:latest
    container_name: nextcloud-aio-talk
    init: true
    restart: unless-stopped
    env_file:
      - .env
    environment:
      # Required by the standalone AIO Talk image
      TALK_PORT: "3478"
      TURN_DOMAIN: ${TALK_HOST}
      AIO_LOG_LEVEL: warn
      SKIP_CERT_VERIFY: "false"
    ports:
      - "3478:3478/tcp"
      - "3478:3478/udp"
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.nextcloud-aio-talk.rule=Host(`${TALK_HOST}`)"
      - "traefik.http.routers.nextcloud-aio-talk.entrypoints=websecure"
      - "traefik.http.routers.nextcloud-aio-talk.tls=true"
      - "traefik.http.routers.nextcloud-aio-talk.middlewares=nextcloud-aio-talk-headers@docker,crowdsec-bouncer@docker"
      - "traefik.http.middlewares.nextcloud-aio-talk-headers.headers.customRequestHeaders.X-Forwarded-Proto=https"
      - "traefik.http.services.nextcloud-aio-talk.loadbalancer.server.port=8081"

networks:
  proxy:
    external: true
EOF

ℹ️ PATH PREFIXES
The preferred layout is one dedicated signaling hostname per container. If a path prefix is unavoidable, add a Traefik `StripPrefix` middleware and use the same prefix in the High-Performance Backend URL in Nextcloud. A dedicated hostname is simpler to operate and troubleshoot.

4. Start and verify the backend

Pull the image and start the container:

cd /opt/containers/nextcloud-aio-talk
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps

Verify the public signaling endpoint. The response contains a version string and a welcome message:

curl https://talk.example.com/api/v1/welcome

Check the container logs if the endpoint does not respond:

sudo docker logs --tail 100 nextcloud-aio-talk

Common causes of an unsuccessful start are a DNS record that does not point to the Docker host, a missing TLS certificate, port 3478 already being occupied, or an unreachable NC_DOMAIN from inside the container.

5. Configure Nextcloud Talk

Open Administration settings → Talk in Nextcloud and configure:

Setting	Value
High-performance backend URL	`https://talk.example.com`
Shared secret	The value of `SIGNALING_SECRET`
TURN mode	`turn: only`
TURN server	`talk.example.com:3478`
TURN secret	The value of `TURN_SECRET`
Protocols	UDP and TCP

Save the settings and wait for the connection check to finish successfully.

5.1. Configure it using `occ` (optional)

The same configuration can be added from the Nextcloud container. Replace the placeholders before running the commands.

# Add the signaling endpoint and validate its TLS certificate
php occ talk:signaling:add --verify \
  https://talk.example.com \
  REPLACE_WITH_YOUR_SIGNALING_SECRET

# Add the integrated TURN service
php occ talk:turn:add \
  turn \
  talk.example.com:3478 \
  udp,tcp \
  --secret=REPLACE_WITH_YOUR_TURN_SECRET

List configured endpoints with:

php occ talk:signaling:list
php occ talk:turn:list

⚠️ MIGRATION FROM ANOTHER HPB
Run the new backend alongside the old one first. Verify the new URL, configure it in Nextcloud, make a real test call from two different networks, and only then remove the old signaling entry and containers. Keep the old Compose directory until the migration has been verified.

6. Test a real call

The welcome endpoint proves that Traefik can reach the signaling service, but it does not prove that media relay works. Create a Talk room and test a video call:

Join from two separate devices or networks.
Test microphone, camera, screen sharing, and reconnecting after a network change.
Repeat the test from a mobile connection or a restrictive network to confirm TURN fallback.

During a test call, monitor the container:

sudo docker logs -f nextcloud-aio-talk

7. Maintenance and updates

The image is intentionally pre-built, so normal updates do not require rebuilding Signaling, Janus, or NATS from source.

cd /opt/containers/nextcloud-aio-talk
sudo docker compose pull
sudo docker compose up -d
sudo docker image prune

Before updating, back up the project directory, especially .env and docker-compose.yml:

sudo tar -C /opt/containers \
  -czf nextcloud-aio-talk-backup-$(date +%F).tar.gz \
  nextcloud-aio-talk

Review release notes after updates and repeat the signaling endpoint and real-call checks. Do not use a blind docker image prune -a on a production host, as it may remove images used for rollback.

8. Running multiple independent Nextcloud instances

Each standalone AIO Talk container has exactly one NC_DOMAIN and one SIGNALING_SECRET. For two separate Nextcloud instances, use two isolated deployments.

Item	First instance	Second instance
Project directory	`/opt/containers/nextcloud-aio-talk-one`	`/opt/containers/nextcloud-aio-talk-two`
Signaling hostname	`talk-one.example.com`	`talk-two.example.com`
Talk / TURN port	`3478`	`3479`
Container name	`nextcloud-aio-talk-one`	`nextcloud-aio-talk-two`
`NC_DOMAIN`	`cloud-one.example.com`	`cloud-two.example.com`
Secrets	Three unique secrets	Three different unique secrets

For the second deployment, copy the project directory, change every identifier shown above, and publish its configured TALK_PORT over TCP and UDP. Each Nextcloud instance then receives only its own signaling URL and its own Signaling and TURN secrets.

⚠️ NO SHARED SECRETS ACROSS TENANTS
Do not share `SIGNALING_SECRET`, `TURN_SECRET`, or `INTERNAL_SECRET` between independent Nextcloud instances. Separation makes future rotations, troubleshooting, and decommissioning safer.

9. Recording backend scope

The AIO Talk image provides signaling, media handling, and TURN. It does not include the Talk Recording Backend. Recording is deployed as a separate service and should be planned, secured, and backed up independently.

Continue with Deploying the Nextcloud Talk AIO Recording Backend as a Standalone Container when you need recordings.

10. Troubleshooting

The High-Performance Backend check fails

Verify DNS and TLS with curl https://talk.example.com/api/v1/welcome.
Confirm that SIGNALING_SECRET matches exactly in .env and in Nextcloud Talk settings.
Confirm that NC_DOMAIN is the existing Nextcloud hostname without a scheme or path.
Inspect sudo docker logs nextcloud-aio-talk for certificate or connectivity errors.

Calls connect but media does not work

Confirm that 3478/tcp and 3478/udp are reachable from the internet.
Confirm the TURN hostname, port, secret, and UDP/TCP protocols in Talk settings.
Test from an external mobile network, not only from the same LAN.
Check provider firewalls and router port forwarding in addition to UFW.

The container cannot contact Nextcloud

Ensure the Docker host can resolve and reach https://cloud.example.com.
Use a publicly trusted certificate or mount an additional trusted CA certificate when using a private PKI.
Do not set SKIP_CERT_VERIFY=true as a permanent workaround.

Conclusion

The standalone AIO Talk image is a practical way to use the maintained, pre-built Talk backend without replacing an existing Nextcloud deployment with full Nextcloud AIO. Keep each Nextcloud instance isolated, protect the secrets, verify TURN with real calls, and retain a tested rollback path during migration.

For the upstream quick-install procedure and current image details, see the official Nextcloud Talk documentation.

Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack
Deploying the classic Nextcloud Talk High-Performance Backend with Docker — retained as an archive and migration reference.
Deploying the Nextcloud Talk AIO Recording Backend as a Standalone Container

Running Hermes Agent Across Multiple Devices with Forgejo and Matrix

Unknown — Sat, 05 Sep 2026 00:00:00 +0000

Hermes Agent by Nous Research is a self-hosted AI agent that runs shell, file, and development tools on the machine where its profile is active. That makes a multi-device installation a fleet of independent runtimes, not one database replicated between several computers.

The reference setup in this guide installs the same logical role profiles on a desktop, one or more laptops, and optionally an always-on private VM. A private Forgejo repository distributes reviewed role definitions, skills, prompts, knowledge, and handoffs. Every endpoint keeps its own sessions, memories, credentials, Matrix encryption store, service state, and search index.

The examples use Hermes Agent 0.21.0. Before deploying the design, check the release notes, pin the version you have tested, and use that same revision on every endpoint.

Changelog

Date	Change
2026-09-05	Authentication Update: Documented independent and centrally managed provider-login models without placing credentials in Forgejo.
2026-09-01	Hermes 0.21 Update: Added the fleet-relevant Hermes 0.21 features, clarified the boundary between Forgejo synchronization and runtime deployment, generalized the examples, and added bounded deterministic snapshots for faster scheduled briefings.
2026-08-31	Fleet Update: Replaced the workstation/server model with role-based profiles, documented guarded automatic synchronization, gateway ownership, and one provider login per host.
2026-07-18	Always-on Update: Added private-home deployment, sizing considerations, controlled host migration, and local mail/PIM mirror guidance.
2026-07-17	Security Update: Corrected backup scope and clarified full-trust operation, approvals, Matrix recovery, and off-host protection.
2026-07-16	Fleet Update: Added profile-scoped gateways, machine-aware Matrix identities, session boundaries, and the profile-versus-sandbox distinction.
2026-07-16	Initial Version: Added the multi-instance Hermes design with Forgejo, profile distributions, QMD knowledge, handoffs, Matrix hardening, and backups.

1. Reference Architecture

The fleet standardizes roles and reviewed capabilities across endpoints. It does not replicate a live Hermes home.

                                Private Forgejo
                    ┌─────────────────────────────────┐
                    │ hermes-shared                   │
                    │ distributions/{roles}/         │
                    │ skills/{profiles,shared}/       │
                    │ knowledge/  handoffs/  scripts/ │
                    └───────────────┬─────────────────┘
                                    │ guarded Git sync
                  ┌─────────────────┼─────────────────┐
                  │                 │                 │
             Desktop          Laptop(s)        Private VM
          active/standby   active/standby      always-on
                  │                 │                 │
          main · personal · business · specialist · ops
          same roles and policy; independent local runtime state

The following five roles are one useful example. Rename, remove, or add roles to match your own trust boundaries:

Profile	Surface	Responsibility
`main`	Interactive	Global Chief of Staff. Correlates reviewed cross-domain signals, prepares briefings, and delegates mutations to the owning role.
`personal`	Interactive	Private mail, calendars, contacts, tasks, notes, and personal files.
`business`	Interactive	Single conversational entry point for business work and customers; delegates specialist tasks where needed.
`specialist`	Internal worker	Isolated customer or domain-specific files, connectors, and memory.
`ops`	Internal worker	Infrastructure diagnosis and execution without standing mail, cloud-file, Paperless, or customer-data authority.

An always-on private VM can host the primary gateways and scheduled work. Desktop and laptop nodes may run additional identities or remain disabled as prepared fallbacks. Give each Matrix identity exactly one active owner; never start a copied identity or encryption store concurrently on two hosts. Internal workers such as specialist and ops do not need a chat gateway unless they have a genuine user-facing delivery path.

📝 A PUBLIC SERVICE HOST IS NOT AUTOMATICALLY A FLEET NODE
A public mail or web server can run unrelated automation without joining the fleet. Install role profiles there only when they genuinely need to act on that host. Keeping an old, stopped Hermes installation on such a server does not make it an active fleet endpoint.

Matrix gateways establish outbound connections to the homeserver. A Matrix-only endpoint therefore needs no public inbound port. A private LAN VM administered over VPN is a good default for personal mail, calendars, contacts, and documents. A public VPS remains useful when the agent must directly administer services on that VPS or remain available during a home outage.

2. Shared and Local Boundaries

Share through Forgejo:

reviewed profile distributions and role-specific SOUL.md files,
reviewed shared and profile-specific skills,
device-independent Markdown knowledge,
compact project handoffs,
reviewed cron prompts, policy files, deployment scripts, and version metadata.

Keep endpoint-local:

state.db, WAL files, sessions, and memories,
.env, auth.json, API keys, OAuth tokens, and password-store data,
Matrix access tokens, device IDs, recovery material, and E2EE stores,
Maildir, CalDAV/CardDAV mirrors, and synchronization journals,
logs, caches, QMD indexes, gateway state, and backups.

⚠️ NEVER REPLICATE LIVE RUNTIME STATE
SQLite WAL mode supports concurrent access on one machine; it is not a conflict-free multi-master database. Do not synchronize Hermes databases, Matrix crypto stores, Maildir state, or cloud-sync journals through Git, Syncthing, or Nextcloud. Each active instance owns its local state exclusively.

3. Prerequisites and Version Discipline

You need:

a private Forgejo repository reachable from every endpoint,
Hermes Agent installed at the same reviewed version on every fleet node,
Git, flock (usually provided by util-linux), and user-level systemd services on Linux endpoints,
a Matrix Synapse homeserver for remote chat,
Node.js >= 22 and QMD when local hybrid knowledge search is enabled.

This guide was tested with:

Component	Version
Hermes Agent	`0.21.0` (`v2026.8.31`)
Example profile distributions	`1.0.0`
QMD	`2.5.3`
Node.js for QMD	`>= 22`

Use these as known-good reference versions, not as an instruction to ignore newer releases. Pin the Hermes release you have tested, record it in VERSIONS.md, and deploy the same revision to every endpoint. If you carry local patches, record their revision separately from the upstream version.

Hermes 0.21 Features Relevant to a Fleet

Hermes 0.21 introduced several facilities worth considering in a multi-device design:

built-in Bot Mode for persistent autonomous operation,
hermes peer for direct agent-to-agent collaboration,
cron continuity through memory and prior-run context,
live steering of running subagents,
an MCP command center and a gateway control socket,
selective multiplex-profile serving,
write approval for protected agent-instruction files,
additional model providers and security hardening.

These are optional building blocks, not a reason to blur endpoint boundaries. Enable Bot Mode, peer links, or multiplexing only after defining their identity, trust, lifecycle, and failure behavior.

4. Build the Shared Repository

The active part of hermes-shared has this shape:

hermes-shared/
├── README.md
├── VERSIONS.md
├── SOUL.md
├── USER.shared.md
├── cron/
│   └── prompts/
├── distributions/
│   ├── main/
│   ├── personal/
│   ├── business/
│   ├── specialist/
│   └── ops/
├── skills/
│   ├── profiles/
│   │   ├── main/
│   │   ├── personal/
│   │   ├── business/
│   │   ├── specialist/
│   │   └── ops/
│   └── shared/
├── knowledge/
├── projects/
├── handoffs/
├── scripts/
└── systemd/user/

The repository .gitignore and server-side protection must exclude at least:

.env
auth.json
*.key
*.pem
state.db*
memories/
sessions/
logs/
cache/
pending/
platforms/matrix/store/
matrix/store/
*.tmp
*.swp

Clone the repository on each endpoint:

git clone git@git.example.com:user/hermes-shared.git ~/hermes-shared

5. Profile Distributions and Capability Policy

Hermes profile distributions package reviewed agent-owned files behind a distribution.yaml manifest. They deliberately exclude credentials, memories, sessions, and live state.

Each active distribution contains only the stable role payload:

distributions/main/
├── distribution.yaml
├── SOUL.md
├── config.yaml
└── mcp.json

The role-specific skills live outside the distribution root under skills/profiles/<profile>/ and are loaded through skills.external_dirs. Runtime cron state is also endpoint-owned. This prevents a distribution update from deleting or replacing local skill and scheduler state.

A manifest starts with the role name and version:

name: main
version: 1.0.0
description: Global cross-domain coordinator and Chief of Staff
hermes_requires: ">=0.21.0"

Profiles separate Hermes configuration and state, but they are not an operating-system sandbox. With terminal.backend: local and terminal.home_mode: real, commands run with the permissions and home directory of the service user. Use this mode only when that level of host access is intentional.

The declarative fleet capability policy is therefore important:

all profiles use approvals.mode: smart and approvals.cron_mode: deny,
main and business receive orchestration capabilities,
personal and specialist receive only their required domain integrations,
ops uses an explicit infrastructure-tool allowlist and no standing customer, mail, search, or creative-suite connector,
each role loads only its reviewed external skill directories.

Hard isolation still requires separate Unix users, filesystem ACLs, restricted SSH credentials, or a correctly configured sandbox/container.

6. Install and Update the Role Profiles

Because the distributions are subdirectories of one repository, install them from their local paths on the first endpoint:

cd ~/hermes-shared
git pull --ff-only --prune

for profile in main personal business specialist ops; do
  hermes profile install "$PWD/distributions/$profile" --alias --yes
done

On later updates, pull the reviewed repository and update each installed profile by name:

cd ~/hermes-shared
git pull --ff-only --prune

for profile in main personal business specialist ops; do
  hermes profile update "$profile" --yes
done

hermes profile update reloads distribution-owned files from the source recorded during installation. It preserves memories, sessions, authentication, .env, and the existing config.yaml unless you explicitly pass --force-config.

⚠️ CONFIG.YAML IS LOCAL ON EXISTING PROFILES
`hermes profile update <name>` preserves an existing local `config.yaml` by default. Use `--force-config` only when you intentionally want the distribution’s config to replace endpoint-specific settings. If you use a fleet helper, have it apply only the policy you have explicitly declared and reviewed.

USER.shared.md is curated source material, not an automatically loaded Hermes memory file. Stable cross-device rules belong in SOUL.md. If a role needs a local user-memory seed, copy it deliberately into that profile once; do not symlink it into a writable Hermes memory path.

7. Provider Authentication Ownership

Hermes 0.21 lets a named profile fall back to the global provider store at ~/.hermes/auth.json when that profile has no credential for the provider. Several profiles on one host therefore do not need separate provider logins.

Authenticate once without --profile:

hermes auth add openai-codex --type oauth --no-browser

Then verify resolution from the roles:

for profile in main personal business specialist ops; do
  hermes --profile "$profile" auth status openai-codex
done

The per-host invariant is:

one authoritative openai-codex entry in the host-global auth store,
no duplicate openai-codex entry in profile-local auth.json files,
profile-local credentials only where a role truly requires a different identity.

A profile-local provider entry takes precedence over the global fallback. Keep it absent unless a role deliberately uses a different provider identity.

Choose the Cross-Host Model Deliberately

There are two valid operational models. In an independent-host fleet, every active host completes its own provider login. In a centrally managed fleet, one selected source host owns the interactive provider login and a reviewed local synchronizer distributes that chosen account to enrolled private hosts.

The central model removes repeated browser logins, but it is credential distribution and must be designed as such. Keep the following boundary:

Forgejo carries the reviewed synchronizer, policy, and status format—never auth.json, tokens, or backups.
Transfer the credential only over a dedicated encrypted host-to-host channel with a key restricted to the exact read operation it needs.
Store an atomic local backup before replacing a host credential, record only a short one-way account fingerprint in the status file, and restart affected gateways in a controlled way.
Stop the adoption when the source is unavailable or the received data is malformed; it must never fall back to a token in Git, a log, or a chat message.

The provider’s account terms, workforce policy, and token-rotation behavior determine whether this model is appropriate. Test the chosen model with a small inference and a gateway restart before enabling it for scheduled work.

⚠️ NEVER PUT PROVIDER CREDENTIALS IN FORGEJO
Whether the fleet uses independent or centrally managed logins, Git remains a transport for reviewed code and knowledge only. Do not commit or publish `auth.json`, OAuth records, API keys, refresh-token backups, or account identifiers.

8. Guarded Forgejo Synchronization

A guarded fleet should not run a blind git pull --rebase loop. The following pull-only synchronizer refuses dirty worktrees and divergent history, fast-forwards clean clones, and never executes files it has downloaded.

8.1. Create the Synchronizer

Create the local runtime directory:

install -d -m 0700 ~/.local/libexec

Create ~/.local/libexec/hermes-fleet-sync:

cat > ~/.local/libexec/hermes-fleet-sync <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

repo="${HERMES_FLEET_REPO:-$HOME/hermes-shared}"
lock_root="${XDG_RUNTIME_DIR:-/tmp}"

exec 9>"$lock_root/hermes-fleet-sync-${UID}.lock"
flock -n 9 || exit 0

if [[ ! -d "$repo/.git" ]]; then
  echo "Not a Git repository: $repo" >&2
  exit 1
fi

if [[ -n "$(git -C "$repo" status --porcelain)" ]]; then
  echo "Refusing to sync a dirty worktree: $repo" >&2
  exit 1
fi

export GIT_TERMINAL_PROMPT=0
git -C "$repo" fetch --prune origin main

local_rev="$(git -C "$repo" rev-parse HEAD)"
remote_rev="$(git -C "$repo" rev-parse origin/main)"
base_rev="$(git -C "$repo" merge-base HEAD origin/main)"

if [[ "$local_rev" == "$remote_rev" ]]; then
  echo "Already current: $local_rev"
elif [[ "$local_rev" == "$base_rev" ]]; then
  git -C "$repo" merge --ff-only origin/main

  if command -v qmd >/dev/null 2>&1 \
    && qmd collection list 2>/dev/null | grep -q '^hermes-shared ';
  then
    qmd update
    qmd embed -c hermes-shared --max-docs-per-batch 32 --max-batch-mb 16
  fi
elif [[ "$remote_rev" == "$base_rev" ]]; then
  echo "Local commits exist; refusing to push automatically." >&2
  exit 1
else
  echo "Local and remote history diverged; manual review required." >&2
  exit 1
fi
EOF

chmod 0700 ~/.local/libexec/hermes-fleet-sync

This script deliberately does not push. Publication is a separate, explicit workflow, so a forgotten local commit cannot silently propagate to every device.

8.2. Create the systemd User Units

Create the user-unit directory:

install -d -m 0700 ~/.config/systemd/user

Create ~/.config/systemd/user/hermes-fleet-sync.service:

[Unit]
Description=Fast-forward the reviewed Hermes fleet repository
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
Environment=HERMES_FLEET_REPO=%h/hermes-shared
ExecStart=%h/.local/libexec/hermes-fleet-sync

Create ~/.config/systemd/user/hermes-fleet-sync.timer:

[Unit]
Description=Synchronize the Hermes fleet repository periodically

[Timer]
OnBootSec=2min
OnUnitActiveSec=10min
RandomizedDelaySec=2min
Persistent=true

[Install]
WantedBy=timers.target

Enable the timer and run the first synchronization:

systemctl --user daemon-reload
systemctl --user enable --now hermes-fleet-sync.timer
systemctl --user start hermes-fleet-sync.service

The synchronizer now:

takes a per-host flock,
refuses to operate on a dirty worktree,
fetches without interactive credential prompts,
fast-forwards only when the host is behind,
stops when local commits or divergent history require review,
refreshes QMD after a successful fast-forward.

⚠️ SYNCHRONIZATION IS NOT RUNTIME DEPLOYMENT
The timer fast-forwards the reviewed repository but does not run newly downloaded installers, profile updates, or scripts. This prevents a pushed Forgejo commit from becoming immediate code execution on every fleet host. Apply Hermes and profile upgrades explicitly, or design and audit a separately installed, version-pinned updater before granting that authority.

Inspect it with:

systemctl --user status hermes-fleet-sync.timer
journalctl --user -u hermes-fleet-sync.service -n 100

8.3. Publish Reviewed Changes Explicitly

Inspect and commit only the intended file. Do not use a blanket git add . in a repository that may contain generated or sensitive data:

cd ~/hermes-shared
git pull --ff-only --prune
git status --short
git diff -- handoffs/current/example.md
git add -- handoffs/current/example.md
git diff --cached --check
git commit -m "Update project handoff"
git push

Add a secret scanner and protected branches on Forgejo when several people or agents can publish. If the remote advances before the push, stop and review the histories instead of rebasing an unattended automation branch.

9. Knowledge Search and Handoffs

Hermes memories are small, profile-local working context. Durable knowledge belongs in Markdown under knowledge/, projects/, and handoffs/.

QMD provides local keyword, vector, and reranked search:

npm install -g @tobilu/qmd
qmd collection add ~/hermes-shared --name hermes-shared
qmd update
qmd embed -c hermes-shared --max-docs-per-batch 32 --max-batch-mb 16

The generated index stays under ~/.cache/qmd/; it is reproducible and never synchronized. The sync timer can update and embed it after the Git revision changes.

To continue work on another device, maintain a compact topic handoff such as:

handoffs/current/hermes-architecture.md

Record the goal, verified current state, decisions, changed files, open risks, and the next concrete action. On the new endpoint, read the handoff and re-read live external state before any mutation. A handoff transfers intent and evidence; it does not pretend to resume the other endpoint’s live process.

Hermes can also export sessions for deliberate archival or review, but exports must be redacted and inspected before publication. They are not a substitute for a concise handoff.

10. Matrix Gateways and E2EE

Each profile has independent messaging configuration, session namespace, and Matrix crypto state. Separate profile gateways are a straightforward default because their failures and restarts are easy to reason about.

Install and manage a gateway with the profile explicitly selected:

hermes --profile main gateway install
hermes --profile main gateway start
hermes --profile main gateway status
hermes gateway list

Use a host- and profile-specific Matrix device ID, for example:

MATRIX_ALLOWED_USERS=@you:matrix.example.org
MATRIX_ALLOWED_ROOMS=!roomid:matrix.example.org
MATRIX_DEVICE_ID=NODE1_MAIN
MATRIX_E2EE_MODE=required
MATRIX_APPROVAL_REQUIRE_SENDER=true

Never reuse one Matrix device/E2EE store on two hosts. A controlled gateway migration is:

stop and disable the old profile gateway,
verify that no old process is running,
copy the profile’s Matrix credentials and crypto store through an encrypted channel,
start the new gateway and test encrypted send/receive,
leave the old copy disabled as a rollback snapshot.

Provider auth and Matrix identity are separate concerns. A model credential may use the host-global fallback described above; every Matrix adapter still needs its own correctly scoped account/token and exclusive crypto store.

Hermes also supports an opt-in multiplexing gateway through gateway.multiplex_profiles. It can be useful for many low-traffic profiles, but it changes lifecycle, listener, route, and failure behavior. Prefer independent gateway processes until you have a specific reason and test plan for multiplexing.

CLI and Matrix sessions share the selected profile’s home and database, but not a live response channel. Matrix-started work replies to Matrix; a CLI background task does not automatically report there. Use an explicit handoff or delivery workflow when the result must appear in Matrix.

11. Mail, Calendar, and File Mirrors

Hermes can read existing local mirrors without receiving the remote account password itself:

NeoMutt reads Maildir,
Notmuch indexes mail,
Khal, Khard, and Todoman read local vdirs,
mbsync and vdirsyncer own remote synchronization credentials.

For unattended mail collection, prefer a pull-oriented command:

mbsync --pull --create-near --expunge-near account@example.org
notmuch new

Keep actual sending behind a task-specific approval. A read/triage workflow does not require SMTP. Mirror only the cloud subtrees and collections that a role needs, and keep each endpoint’s synchronization journal local.

11.1. Use Bounded Domain Snapshots for Scheduled Briefings

A scheduled agent that repeatedly discovers commands, searches every source, reads large tool results, and decides what to fetch next spends time and tokens on data collection before it starts the actual analysis. A better pattern for stable recurring work is:

mail ───────┐
calendar ───┤
tasks ──────┤  deterministic, read-only collectors
projects ───┤              │
documents ──┤              ▼
weather ────┘      one bounded JSON snapshot
                            │
                            ▼
                  one cross-domain analysis

Run independent read-only collectors concurrently, but keep the reasoning in one model call when relationships between domains matter. Splitting mail, calendar, and project analysis among isolated agents can hide a conflict that only becomes visible when the evidence is combined.

Every source envelope should include at least:

generation time and source freshness,
collector duration and success or error state,
total records found, included, and omitted,
the limit or reason responsible for an omission,
a complete flag and a targeted read-only retrieval hint,
an explicit warning that source fields are untrusted data.

Enforce a hard serialized-output budget, not merely a record count. A practical starting point is a compact 25–40 KB snapshot, adjusted after measuring real coverage. If the budget removes an item, record that removal in the envelope; the model must never turn “omitted” into “does not exist.” Keep high-value evidence first—for example, recent overdue and upcoming tasks before an old backlog—and trim low-priority tails deterministically.

The snapshot collector should not silently take ownership of synchronization. Let dedicated timers update Maildir, Notmuch, and CalDAV/CardDAV mirrors. The briefing collector reads their current state without changing seen state, flags, folders, drafts, attachments, or remote objects. This keeps the fast path reproducible and makes failures source-specific rather than losing the whole report.

An illustrative deployment reduced the collection phase to roughly five or six seconds while producing a 30–39 KB combined snapshot. Its older end-to-end briefings took several minutes, but those runs also included model inference, graphics, speech synthesis, cloud verification, and message delivery, so the numbers are not a like-for-like model benchmark. Record collection time, inference usage, rendering time, and delivery time separately.

12. Security Model

Choose and document the trust model for each endpoint:

Restricted automation identity: separate Unix user or sandbox, narrowly scoped paths and SSH identities.
Full-trust personal assistant: the agent intentionally has the same files and administration capabilities as its owner.

A Hermes profile alone implements neither boundary at OS level. SOUL.md, model instructions, and approvals.mode: smart reduce mistakes but are not containment against prompt injection.

Treat mail, websites, documents, issues, repositories, and tool output as untrusted data. Require concrete authorization for the destination, payload, and purpose before sending mail, uploading files, pushing Git commits, publishing, buying, inviting users, changing cloud resources, or mutating another host.

Audit the effective service identity:

id
sudo -n -l
stat -c '%A %U:%G %n' /var/run/docker.sock 2>/dev/null

Passwordless sudo and access to a rootful Docker socket are both root-equivalent. If that authority is intentional, protect Matrix identities, model/tool supply chains, outbound-action policy, and recoverable backups accordingly.

13. Backups and Recovery

hermes backup creates a machine-level archive of the Hermes root, including named profiles. Run it once per endpoint, not once per profile:

hermes backup --output /secure/staging/hermes-backup.zip

The archive contains secrets and is not encrypted by Hermes. Encrypt it before it leaves the machine and store it off-host with deletion-resistant retention.

A profile export has a different purpose:

hermes profile export main --output ./main-profile.tar.gz

It strips .env and auth.json, making it useful for a controlled profile transfer, but it is not complete disaster recovery. Quick snapshots are local rollback aids, not off-host backups.

Back up separately:

the Forgejo repository and server configuration,
encrypted Matrix crypto stores, device IDs, and matching recovery material,
external project and synchronization configuration,
credentials stored outside the Hermes root.

Test an actual restore with the original runtime stopped. Never start the same restored database or E2EE store on two hosts.

14. Verification Checklist

Before relying on the fleet, verify:

Every endpoint has the intended role profiles at the approved distribution versions.
Obsolete or experimental distributions are not active.
All active endpoints run the same reviewed Hermes upstream and patch revisions.
Each profile has its own sessions, memories, SQLite state, Matrix state, and endpoint credentials.
No runtime database, secret, OAuth record, E2EE store, Maildir, or sync journal is in Forgejo.
One global model login serves the profiles on a host; duplicate profile-local entries do not shadow it.
The selected cross-host authentication model is documented, tested after gateway restart, and keeps credentials out of Forgejo.
The intended gateway owners are documented; fallback units remain disabled until deliberately started, and no Matrix identity has two active owners.
Matrix allowlists, requester-bound approvals, stable device IDs, and MATRIX_E2EE_MODE=required are set.
The guarded sync timer is active and stops on a dirty tree or divergent history.
QMD returns current results after a synchronized commit.
The coordinator only coordinates cross-domain writes; the owning Personal, Business, Specialist, or Ops role performs them.
approvals.mode: smart and approvals.cron_mode: deny are explicit.
Root-equivalent permissions and outbound-action paths were reviewed consciously.
One encrypted off-host backup exists per endpoint and a restore was tested.

Useful read-only checks:

hermes --version
hermes profile list
hermes gateway list
git -C ~/hermes-shared status --short --branch
systemctl --user status hermes-fleet-sync.timer
journalctl --user -u hermes-fleet-sync.service -n 20
qmd --version

15. Updates and Maintenance

Roll out changes in this order:

update and test one endpoint,
record the exact upstream, patch, distribution, QMD, and Node versions,
fast-forward the clean repository clone on the other endpoints,
run hermes profile update <name> --yes for each installed role,
review and reinstall the local synchronizer if its implementation changed,
compare hermes --version, hermes profile list, and the Git revision across endpoints,
test provider auth, Matrix E2EE, role routing, and a QMD query,
only then restore normal always-on gateway and cron operation.

Do not treat a successful git pull as deployment: downloaded scripts and distributions take effect only after the reviewed apply/install step.

Conclusion

The durable design is a consistent set of logical roles on every endpoint, with an optional always-on home, explicitly selected active gateways, and independent on-demand fallbacks. Forgejo synchronizes only reviewed, device-independent material; guarded automation refuses dirty or divergent histories; runtime state and credentials stay local.

The key distinctions are simple: share roles, knowledge, and handoffs; do not share live databases, Matrix crypto state, or credentials through Git. A provider login can be independent per host or centrally managed through a separately reviewed private channel. Consolidate user-facing coordination while preserving role ownership and endpoint-level recovery.

📚HERMES DOCUMENTATION 🤖PROFILES & GATEWAYS 🛰️MULTI-PROFILE GATEWAYS 📦PROFILE DISTRIBUTIONS 💾SESSIONS & EXPORT 💬MATRIX INTEGRATION

Deploying GoToSocial with Traefik and Phanpy

Unknown — Fri, 04 Sep 2026 00:00:00 +0000

GoToSocial is a lightweight ActivityPub server for small Fediverse instances. It is especially attractive for single-user or small-group deployments where a full Mastodon stack would be unnecessarily heavy.

This guide focuses on a fresh GoToSocial installation in an existing Traefik v3 and CrowdSec Docker ecosystem. GoToSocial runs as a normal Docker Compose stack on the shared proxy network, Traefik handles public HTTPS, and Phanpy is deployed as a separate static web client.

ℹ️ FRESH INSTALL FIRST
The main path below is a clean installation. If you are replacing an existing Mastodon account, use the optional migration section near the end after GoToSocial itself is already working.

Changelog

Date	Change
2026-09-04	Maintenance Update: Updated the pinned GoToSocial image to 0.22.1 and added a safer SQLite-first update procedure with explicit version and HTTP checks.
2026-07-01	Initial Version: Fresh GoToSocial install with SQLite, Traefik, Phanpy, and optional Mastodon account-move notes.

1. Prerequisites

You need:

A working Traefik v3 and CrowdSec stack.
A subdomain for GoToSocial, e.g. gotosocial.your-domain.com.
A subdomain for Phanpy, e.g. phanpy.your-domain.com.
DNS A/AAAA records pointing both subdomains at your server.
Docker and Docker Compose.

This guide assumes the Traefik external Docker network is named proxy.

2. GoToSocial Directory

sudo mkdir -p /opt/containers/gotosocial
cd /opt/containers/gotosocial

sudo mkdir -p data cache
sudo chown -R 1000:1000 data cache

The example below runs the container as UID/GID 1000:1000. If your deployment uses another unprivileged user, adjust ownership and user: accordingly.

3. GoToSocial Docker Compose

Create /opt/containers/gotosocial/docker-compose.yml:

services:
  gotosocial:
    image: docker.io/superseriousbusiness/gotosocial:0.22.1
    container_name: gotosocial
    user: 1000:1000
    restart: unless-stopped
    environment:
      GTS_HOST: gotosocial.your-domain.com
      GTS_DB_TYPE: sqlite
      GTS_DB_ADDRESS: /gotosocial/storage/sqlite.db
      GTS_LETSENCRYPT_ENABLED: "false"
      GTS_TRUSTED_PROXIES: 172.18.0.0/16
      GTS_WAZERO_COMPILATION_CACHE: /gotosocial/.cache
      GTS_MEDIA_REMOTE_CACHE_DURATION: "14 days"
      GTS_STATUSES_CLEANUP_REMOTE_OLDER_THAN: "30 days"
      GIN_MODE: release
      TZ: Europe/Berlin
    volumes:
      - ./data:/gotosocial/storage
      - ./cache:/gotosocial/.cache
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.gotosocial.rule=Host(`gotosocial.your-domain.com`)"
      - "traefik.http.routers.gotosocial.entrypoints=websecure"
      - "traefik.http.routers.gotosocial.tls.certresolver=tls_resolver"
      - "traefik.http.routers.gotosocial.middlewares=security-headers@file,crowdsec-bouncer@docker"
      - "traefik.http.services.gotosocial.loadbalancer.server.port=8080"

networks:
  proxy:
    external: true

Configuration notes:

GTS_LETSENCRYPT_ENABLED=false: Traefik handles public TLS.
GTS_TRUSTED_PROXIES: restrict this to your Docker proxy subnet.
GTS_MEDIA_REMOTE_CACHE_DURATION: limits cached remote media growth.
GTS_STATUSES_CLEANUP_REMOTE_OLDER_THAN: cleans old remote statuses.
SQLite is appropriate for a small personal instance.

Start the service:

sudo docker compose pull
sudo docker compose up -d
sudo docker compose logs -f gotosocial

4. Create the First Account

Create the account from inside the container:

sudo docker exec -it gotosocial \
  /gotosocial/gotosocial admin account create \
  --username yourusername \
  --email you@your-domain.com \
  --password 'REPLACE_WITH_A_STRONG_TEMPORARY_PASSWORD'

Promote it to admin:

sudo docker exec -it gotosocial \
  /gotosocial/gotosocial admin account promote \
  --username yourusername

https://gotosocial.your-domain.com/settings

Change the temporary password immediately.

5. Phanpy Web Client

GoToSocial provides settings pages and API endpoints, but you usually want a full client for daily use. Phanpy works well as a static web client.

Create the directory:

sudo mkdir -p /opt/containers/phanpy/html
cd /opt/containers/phanpy

Download and verify the Phanpy release asset you want to run, then extract it into html/.

💡 VERIFY RELEASE ASSETS
When using prebuilt static client assets, verify the checksum from the release page before serving them publicly.

Create /opt/containers/phanpy/nginx.conf:

worker_processes 2;
user www-data;

events {
    use epoll;
    worker_connections 128;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;

    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml image/svg+xml;

    server {
        listen 80;
        server_name _;

        root /usr/share/nginx/html;
        index index.html;

        location ~* \.(?:css|js|mjs|png|jpg|jpeg|gif|svg|webp|avif|ico|woff2?)$ {
            try_files $uri =404;
            access_log off;
            expires 30d;
            add_header Cache-Control "public, immutable";
        }

        location / {
            try_files $uri $uri/ /index.html;
            add_header Cache-Control "no-cache";
        }
    }
}

Create /opt/containers/phanpy/docker-compose.yml:

services:
  phanpy:
    image: nginx:1.27.1
    container_name: phanpy
    restart: unless-stopped
    volumes:
      - ./html:/usr/share/nginx/html:ro
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.phanpy.rule=Host(`phanpy.your-domain.com`)"
      - "traefik.http.routers.phanpy.entrypoints=websecure"
      - "traefik.http.routers.phanpy.tls.certresolver=tls_resolver"
      - "traefik.http.routers.phanpy.middlewares=security-headers@file,crowdsec-bouncer@docker"
      - "traefik.http.services.phanpy.loadbalancer.server.port=80"
    networks:
      - proxy

networks:
  proxy:
    external: true

Start it:

sudo docker compose up -d

Open:

https://phanpy.your-domain.com/

Choose your GoToSocial instance as the server when logging in.

6. Verification

Check the public profile:

curl -I https://gotosocial.your-domain.com/@yourusername

Check WebFinger:

curl -s 'https://gotosocial.your-domain.com/.well-known/webfinger?resource=acct:yourusername@gotosocial.your-domain.com'

Check logs:

cd /opt/containers/gotosocial
sudo docker compose logs -f gotosocial

Verify the Phanpy route:

curl -I https://phanpy.your-domain.com/

At this point, the fresh GoToSocial installation is ready. You can use Phanpy or any compatible Mastodon/ActivityPub client to log in.

A fresh GoToSocial instance only knows local accounts and remote objects it has already discovered. Global search is not a search engine over the entire Fediverse.

To discover more content:

Follow accounts from known instances.
Open remote profile URLs directly in your client.
Follow hashtags.
Interact with posts so your instance learns about those actors and threads.

It is normal for trending posts or broad search results to look empty at first.

8. Backups and Updates

Back up:

/opt/containers/gotosocial/data
/opt/containers/gotosocial/docker-compose.yml
/opt/containers/phanpy/html
/opt/containers/phanpy/docker-compose.yml
/opt/containers/phanpy/nginx.conf

Read the release notes before every update. For SQLite deployments, stop the service before copying the database so the backup is a consistent single file. Then change the pinned image tag, validate the Compose file, and recreate the service:

cd /opt/containers/gotosocial

# Download the target image before starting the maintenance window.
sudo docker pull docker.io/superseriousbusiness/gotosocial:0.22.1

sudo docker compose stop gotosocial
sudo cp -a data/sqlite.db "data/sqlite-pre-update-$(date +%F).db"
sudo cp -a docker-compose.yml "docker-compose.yml.pre-update-$(date +%F)"

# Edit docker-compose.yml and pin the reviewed release, for example 0.22.1.
sudo docker compose config -q
sudo docker compose up -d --remove-orphans

# Confirm startup, the exact running version, and the public routes.
sudo docker compose logs --tail=100 gotosocial
curl -fsS https://gotosocial.your-domain.com/api/v1/instance
curl -I https://gotosocial.your-domain.com/settings

Do not interrupt startup while GoToSocial reports database migrations. The update from 0.22.0 to 0.22.1 has no new database migration, but this is release-specific and must not be assumed for later versions.

For Phanpy, replace the static release files in html/ with a verified newer release and recreate the Nginx container if needed.

9. Optional: Migrating from Mastodon

GoToSocial is not a drop-in Mastodon database replacement. If you are replacing an existing Mastodon account, treat it as an ActivityPub identity move after the new GoToSocial instance has been installed and tested.

The migration flow is:

Keep the old Mastodon account reachable.
Create the new GoToSocial account.
Add an alias in GoToSocial pointing to the old Mastodon account.
Trigger the account move from the old Mastodon account to the new GoToSocial account.
Import or recreate follows.
Recreate hashtag follows separately if needed.

⚠️ KEEP THE OLD ACCOUNT REACHABLE
ActivityPub account moves depend on the old account being reachable long enough for other servers to observe the move. Do not shut down the old Mastodon hostname immediately after changing DNS.

9.1. Add the GoToSocial Alias

In GoToSocial settings:

https://gotosocial.your-domain.com/settings/user/migration

Add the old Mastodon account as an alias, for example:

https://mastodon.your-domain.com/@yourusername

or:

https://mastodon.your-domain.com/users/yourusername

9.2. Trigger the Move in Mastodon

@yourusername@gotosocial.your-domain.com

Mastodon will mark the old profile as moved and notify followers’ servers. Propagation is not instant.

9.3. Following and Hashtags

Follower migration is handled by the ActivityPub move. Following relationships are different: export your Mastodon following list and import it into GoToSocial if the UI supports it, or recreate the follows through a client/API workflow.

Hashtag follows are not guaranteed to migrate with account moves or account CSV imports. Export and recreate them separately.

After the account move, search for the old Mastodon account from another Fediverse instance and verify that it points to the new GoToSocial account.

10. Optional: Legacy Mastodon Proxy

During a migration, it can be useful to keep mastodon.your-domain.com reachable even after the new server handles DNS. A temporary Traefik file-provider route can proxy the old Mastodon host back to the old server.

Remove this after the fallback window has ended. Keeping a legacy proxy forever makes the migration harder to reason about.

Conclusion

GoToSocial fits neatly into a Traefik-based Docker setup: one small application container, SQLite storage for small instances, no public host port, and a separate static web client through the same reverse proxy. If you later replace Mastodon, handle that as an ActivityPub account move, not as a database transplant.

📚GOTOSOCIAL DOCUMENTATION 📦GOTOSOCIAL CODEBERG 🌐PHANPY

Deploying Lemmy with Docker, Traefik, and Nginx

Unknown — Fri, 04 Sep 2026 00:00:00 +0000

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.

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.

Changelog

Date	Change
2026-09-04	Maintenance Update: Updated Lemmy and Lemmy UI to 0.19.20 and pict-rs to 0.5.24, reduced production log verbosity, added post-update proxy/API/federation checks, and documented recovery of missing legacy ActivityPub uniqueness constraints.
2026-07-01	Migration Update: Updated image versions and added database-first migration and pict-rs storage guidance.
2025-10-30	Fixed mixed-content issues by enabling HTTPS settings and proper proxy headers in Lemmy behind Traefik.
2025-09-26	Initial Version: Guide created using the official Nginx internal proxy method for maximum compatibility and update safety, integrated with the Traefik v3 stack.

1. Prerequisites

This guide builds upon a secure Docker environment. Before you begin, you must have a fully functional Traefik v3 and CrowdSec stack.

⚠️ HARD REQUIREMENT
The following steps will not work correctly without the Traefik stack running as described in the prerequisite guide. Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack: This is the foundation for our public-facing reverse proxy and security.

You will also need:

A dedicated subdomain for your Lemmy instance (e.g., lemmy.your-domain.com) pointed to your server’s IP address.
sudo or root access.
The openssl utility for generating secrets (sudo apt install openssl).

2. Directory Structure

First, create a dedicated directory for your Lemmy configuration and data. This structure will hold all necessary config files.

# Create the main directory
sudo mkdir -p /opt/containers/lemmy
cd /opt/containers/lemmy

# Create directories for persistent data and configs
sudo mkdir -p volumes/pictrs
sudo mkdir -p volumes/postgres
sudo mkdir -p config
sudo chown -R 991:991 volumes/pictrs

3. Configuration

We will now create all the necessary configuration files for Nginx, PostgreSQL, Lemmy, and Docker Compose.

3.1. Generate Secrets

Let’s generate strong, unique secrets for the database, image service, and admin account.

# Generate a strong password for the Postgres database
POSTGRES_PASSWORD=$(openssl rand -hex 32)
echo "Your Postgres password is: $POSTGRES_PASSWORD"

# Generate a strong API key for Pictrs
PICTRS_API_KEY=$(openssl rand -hex 32)
echo "Your Pictrs API key is: $PICTRS_API_KEY"

# Generate a strong password for the Lemmy admin user
LEMMY_ADMIN_PASSWORD=$(openssl rand -hex 32)
echo "Your Lemmy Admin password is: $LEMMY_ADMIN_PASSWORD"

ℹ️ SAVE THESE SECRETS
Copy these generated values into a temporary text file. You will need to paste them into the configuration files in the upcoming steps.

3.2. Nginx Configuration (`config/nginx.conf`)

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.

sudo tee config/nginx.conf > /dev/null << 'EOF'
worker_processes 1;
events {
    worker_connections 1024;
}
http {
    upstream lemmy { server "lemmy:8536"; }
    upstream lemmy-ui { server "lemmy-ui:1234"; }

    server {
        listen 1236;
        listen 8536;
        server_name lemmy.criticalbasics.xyz;
        server_tokens off;

        gzip on;
        gzip_types text/css application/javascript image/svg+xml;
        gzip_vary on;

        client_max_body_size 20M;

        add_header X-Frame-Options SAMEORIGIN;
        add_header X-Content-Type-Options nosniff;
        add_header X-XSS-Protection "1; mode=block";

        location / {
            set $proxpass "http://lemmy-ui";
            if ($http_accept = "application/activity+json") { set $proxpass "http://lemmy"; }
            if ($http_accept = "application/ld+json; profile=\"https://www.w3.org/ns/activitystreams\"") { set $proxpass "http://lemmy"; }
            if ($request_method = POST) { set $proxpass "http://lemmy"; }

            proxy_pass $proxpass;
            rewrite ^(.+)/+$ $1 permanent;

            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
            proxy_set_header X-Forwarded-Ssl on;
        }

        location ~ ^/(api|pictrs|feeds|inbox|outbox|nodeinfo|version|socket\.io|federation|\.well-known) {
            proxy_pass "http://lemmy";
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";

            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
            proxy_set_header X-Forwarded-Ssl on;

            proxy_redirect off;
        }
    }
}
EOF

3.3. PostgreSQL Configuration

For better performance, we’ll provide a custom configuration file for PostgreSQL.

`config/custom.conf` (Performance Tuning)

sudo tee config/custom.conf > /dev/null << 'EOF'
# Generated by https://pgtune.leopard.in.ua
# DB Version: 16, OS: linux, RAM: 12 GB, CPUs: 16, Storage: ssd
max_connections = 200
shared_buffers = 3GB
effective_cache_size = 9GB
maintenance_work_mem = 768MB
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 100
random_page_cost = 1.1
effective_io_concurrency = 200
work_mem = 3932kB
min_wal_size = 1GB
max_wal_size = 8GB
max_worker_processes = 16
max_parallel_workers_per_gather = 4
max_parallel_workers = 16
max_parallel_maintenance_workers = 4
EOF

`config/pg_hba.conf` (Authentication Rules)

sudo tee config/pg_hba.conf > /dev/null << 'EOF'
# TYPE  DATABASE        USER            ADDRESS                 METHOD
local   all             all                                     trust
host    all             all             0.0.0.0/0               md5
host    all             all             ::/0                    md5
EOF

3.4. Lemmy Configuration (`config/lemmy.hjson`)

This file controls the Lemmy application itself.

sudo tee config/lemmy.hjson > /dev/null << 'EOF'
{
  database: {
    user: "lemmy"
    password: "PASTE-YOUR-POSTGRES-PASSWORD-HERE"
    host: "postgres"
    port: 5432
    database: "lemmy"
  }
  pictrs: {
    url: "http://pictrs:8080/"
    api_key: "PASTE-YOUR-PICTRS-API-KEY-HERE"
    image_mode: "None"
  }
  cache_external_link_previews: false
  email: {
    smtp_server: "your-mail-server.com:587"
    smtp_login: "lemmy@your-domain.com"
    smtp_password: "PASTE-YOUR-EMAIL-PASSWORD-HERE"
    smtp_from_address: "Lemmy <lemmy@your-domain.com>"
    tls_type: "starttls"
  }
  setup: {
    admin_username: "admin"
    admin_password: "PASTE-YOUR-LEMMY-ADMIN-PASSWORD-HERE"
    site_name: "My Lemmy Instance"
    admin_email: "your-admin@example.com"
  }
  hostname: "lemmy.your-domain.com"
  bind: "0.0.0.0"
  port: 8536
  tls_enabled: true
}
EOF

💡 KEEP MEDIA GROWTH UNDER CONTROL
For small personal instances, `image_mode: "None"` and `cache_external_link_previews: false` keep Lemmy from aggressively storing external link-preview images. This does not replace backups or monitoring, but it reduces avoidable media growth.

3.5. Docker Compose (`docker-compose.yml`)

This file ties all the services together. Notice that only the lemmy-proxy service has Traefik labels and is exposed to the external proxy network.

sudo tee docker-compose.yml > /dev/null << 'EOF'
services:
  lemmy-proxy:
    image: nginx:stable-alpine
    container_name: lemmy-proxy
    restart: unless-stopped
    volumes:
      - ./config/nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - lemmy
      - lemmy-ui
      - pictrs
    networks:
      - proxy
      - lemmy-net
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.lemmy.rule=Host(`lemmy.your-domain.com`)"
      - "traefik.http.routers.lemmy.entrypoints=websecure"
      - "traefik.http.routers.lemmy.tls.certresolver=tls_resolver"
      - "traefik.http.routers.lemmy.middlewares=security-headers@file,crowdsec-bouncer@docker"
      - "traefik.http.services.lemmy.loadbalancer.server.port=8536"
      - "traefik.docker.network=proxy"

  lemmy:
    image: dessalines/lemmy:0.19.20
    hostname: lemmy
    container_name: lemmy
    restart: unless-stopped
    environment:
      - RUST_LOG=warn,lemmy_server=info
    volumes:
      - ./config/lemmy.hjson:/config/config.hjson:ro
    depends_on:
      - postgres
      - pictrs
    networks:
      - lemmy-net

  lemmy-ui:
    image: dessalines/lemmy-ui:0.19.20
    container_name: lemmy-ui
    hostname: lemmy-ui
    restart: unless-stopped
    environment:
      - LEMMY_UI_LEMMY_INTERNAL_HOST=lemmy:8536
      - LEMMY_UI_LEMMY_EXTERNAL_HOST=lemmy.your-domain.com
      - LEMMY_UI_HTTPS=true
    depends_on:
      - lemmy
    networks:
      - lemmy-net

  pictrs:
    image: asonix/pictrs:0.5.24
    hostname: pictrs
    container_name: pictrs
    restart: unless-stopped
    environment:
      - PICTRS__API_KEY=PASTE-YOUR-PICTRS-API-KEY-HERE
      - RUST_LOG=info
    user: 991:991
    volumes:
      - ./volumes/pictrs:/mnt
    networks:
      - lemmy-net

  postgres:
    image: postgres:16-alpine
    hostname: postgres
    container_name: postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=lemmy
      - POSTGRES_PASSWORD=PASTE-YOUR-POSTGRES-PASSWORD-HERE
      - POSTGRES_DB=lemmy
    volumes:
      - ./volumes/postgres:/var/lib/postgresql/data
      - ./config/custom.conf:/etc/postgresql/postgresql.conf:ro
      - ./config/pg_hba.conf:/var/lib/postgresql/data/pg_hba.conf:ro
    networks:
      - lemmy-net

networks:
  proxy:
    external: true
  lemmy-net:
    driver: bridge
EOF

3.6. Update Configuration with Your Values

Carefully replace all placeholders in the files you just created.

Domain Name: In config/nginx.conf, config/lemmy.hjson, and docker-compose.yml, replace all instances of lemmy.your-domain.com with your actual domain.
Secrets: In config/lemmy.hjson and docker-compose.yml, paste the secrets you generated in step 3.1. Ensure the Postgres password and Pictrs API key are identical where required.
Email Settings: In config/lemmy.hjson, update the email section with your SMTP server details.

4. Launch the Stack

With all configuration files in place, you can start your Lemmy instance.

# From within the /opt/containers/lemmy directory
sudo docker compose up -d

The first launch will take a few minutes as Docker downloads all the necessary images. You can monitor the progress with:

sudo docker compose logs -f

Press CTRL+C to exit the logs view once the services are stable.

5. Verify the Installation

Check Running Containers:
```
docker ps --format '{{.Names}}'
```
You should see lemmy-proxy, lemmy, lemmy-ui, pictrs, and postgres running.
Access Your Site: Open a web browser and navigate to https://lemmy.your-domain.com. You should see the Lemmy welcome page.
Log In as Admin: Log in using the admin username (admin) and the strong password you generated for it. You can now begin administering your instance.

6. Maintenance

Updating Lemmy

Updating is now safer. You typically only need to update the image tags in docker-compose.yml for lemmy, lemmy-ui, and pictrs.

cd /opt/containers/lemmy

# Back up the database before applying migrations
sudo docker compose exec -T postgres \
  pg_dump -Fc -U lemmy -d lemmy > lemmy-pre-update.dump

# Pull only the application images being updated. This avoids an
# unintended PostgreSQL major/minor image change during the same operation.
sudo docker compose pull lemmy lemmy-ui pictrs

# Restart the stack with the new images
sudo docker compose up -d --remove-orphans

# Nginx resolves Docker service names when it starts. Restart the internal
# proxy so it does not retain the old Lemmy container IP after a recreation.
sudo docker compose restart lemmy-proxy

# Verify container state and the public API version
sudo docker compose ps
curl -fsS https://lemmy.your-domain.com/api/v3/site | jq \
  '{version: .version, federation_enabled: .site_view.local_site.federation_enabled}'

💡 CHECK RELEASE NOTES
Always consult the official Lemmy release notes before updating for any special instructions or potential changes to configuration files like `nginx.conf`.

⚠️ A 502 AFTER UPDATING USUALLY MEANS STALE PROXY DNS
If Lemmy responds inside its container but the public route returns `502 Bad Gateway`, restart `lemmy-proxy`. The long-running Nginx process may still be using the IP address of the container that was replaced during the update.

Federation Verification

Do not treat a working home page as proof that federation is healthy. Check the public API, WebFinger, and an ActivityPub actor as well:

# Federation must be enabled and the reported version must match the image tag.
curl -fsS https://lemmy.your-domain.com/api/v3/site | jq \
  '{version: .version, federation_enabled: .site_view.local_site.federation_enabled}'

# Replace admin with an existing local user.
curl -fsS \
  'https://lemmy.your-domain.com/.well-known/webfinger?resource=acct:admin@lemmy.your-domain.com' | jq .

curl -fsS \
  -H 'Accept: application/activity+json' \
  https://lemmy.your-domain.com/u/admin | jq \
  '{type, id, preferredUsername, inbox, outbox}'

# Review recent delivery and queue failures after an update.
sudo docker compose logs --since=30m lemmy | \
  grep -Ei 'federation queue|could not send|inbox.*error|outbox.*error|panic|fatal'

# Confirm that current remote posts are actually being stored and surfaced.
curl -fsS \
  'https://lemmy.your-domain.com/api/v3/post/list?type_=All&sort=New&limit=10' | jq \
  '.posts[] | {published: .post.published, post: .post.ap_id, community: .community.actor_id}'

⚠️ A WORKING UI CAN HIDE A BROKEN FEDERATION SCHEMA
On a database with a long upgrade history, federation can stop while the UI and public API still return HTTP 200. Repeated PostgreSQL errors such as `there is no unique or exclusion constraint matching the ON CONFLICT specification` indicate a schema/data problem, not a network problem. Check that the official unique constraints for `community.actor_id`, `person.actor_id`, `post.ap_id`, and `comment.ap_id` exist. If duplicates have accumulated, do not simply delete them or add the constraints blindly: dependent posts, comments, likes, follows, reports, and aggregate rows must be merged transactionally. Take a full database backup and test the repair against a restored database first.

Migration Notes

For a server migration, treat Lemmy as a database-first service. The PostgreSQL database contains the instance identity, local users, subscriptions, site settings, instance keys, and federation state. If you want the same instance to continue federating as itself, migrate the database and core config/secrets.

pict-rs media is a separate decision:

If historical images matter, back up and restore volumes/pictrs.
If old media is not important, you can intentionally skip the old pict-rs store and keep only the database and active config.
Remote/federated content can often be fetched again, but local uploads and avatars may be lost if you skip media.

⚠️ DO NOT PRUNE PICT-RS BY FILE AGE
Do not run ad-hoc commands like `find volumes/pictrs -mtime +21 -delete`. pict-rs keeps metadata and aliases in addition to files. Deleting files directly can leave broken references. Use application-level deletion, pict-rs tooling, or a planned media-retention strategy instead.

After a migration, watch the federation workers. If federation_queue_state points to activity IDs that no longer exist in sent_activity, Lemmy can repeatedly log queue errors. Treat this as a database repair task and take a database backup before touching federation queue tables.

Backing Up

A complete backup consists of the database and the uploaded images.

# From your /opt/containers/lemmy directory
# 1. Stop services to ensure data consistency
sudo docker compose stop lemmy lemmy-ui lemmy-proxy

# 2. Back up the database
sudo docker compose exec -T postgres pg_dump -U lemmy -d lemmy | gzip > lemmy_db_backup_$(date +%F).sql.gz

# 3. Back up the images
sudo tar -czvf pictrs_backup_$(date +%F).tar.gz volumes/pictrs

# 4. Restart services
sudo docker compose start

Conclusion

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.

📚OFFICIAL LEMMY DOCS 📦OFFICIAL DOCKER REPO

Deploying Mox Mail Server with systemd and Traefik: A Lightweight Mailcow Alternative

Unknown — Wed, 02 Sep 2026 00:00:00 +0000

This guide deploys Mox as a native mail server managed by systemd, while keeping Traefik v3 responsible for the public HTTPS routes. This is the cleanest pattern when Traefik already terminates TLS for your web stack, but you still need a real mail server that owns the mail protocols directly.

Mox is a good lightweight alternative to a larger stack such as Mailcow. It includes SMTP, submission, IMAP, webmail, admin pages, account pages, MTA-STS, autoconfig, DNS checks, and spam filtering in one service.

ℹ️ TRAEFIK DOES NOT PROXY MAIL PROTOCOLS
Traefik is only used for HTTPS routes such as webmail, admin, autoconfig, autodiscover, and MTA-STS. SMTP and IMAP must be reachable directly on the host. Reverse-proxying the web UI alone is not a complete mail server setup.

Changelog

Date	Change
2026-09-02	Junk Filtering and Updates: Added Introbox, safe Junk/Trash training, retraining, and a backup-first verified upgrade procedure.
2026-08-31	TLS Renewal: Added validated automatic Traefik-to-Mox certificate synchronization with a systemd path trigger and timer fallback.
2026-07-01	DNS Notes: Added SPF, DKIM, DMARC, TLSRPT, MTA-STS, and SRV record pitfalls from a production setup.
2026-07-01	Major Rework: Switched from Docker-only Mox to a native systemd deployment with direct mail ports, Traefik web routes, DNS, and migration notes.
2025-11-12	Initial Version: Guide created for integrating Mox with the Traefik v3 stack.

1. Architecture

The target architecture looks like this:

Internet
  |
  | 25, 465, 587, 993
  v
Mox on the host via systemd

Internet
  |
  | 443
  v
Traefik -> Mox internal HTTP listeners

Mox runs as a host service under /home/mox. It binds the mail ports directly, then drops privileges to the mox user. Traefik reaches Mox over an internal Docker bridge address for the HTTPS-facing helper endpoints.

Function	Public hostname	Public port	Handler
SMTP delivery	`mail.your-domain.com`	`25/tcp`	Mox directly
Submission	`mail.your-domain.com`	`587/tcp`	Mox directly
SMTPS	`mail.your-domain.com`	`465/tcp`	Mox directly
IMAPS	`mail.your-domain.com`	`993/tcp`	Mox directly
Account/admin/webmail	`mail.your-domain.com`	`443/tcp`	Traefik -> Mox HTTP
Autoconfig	`autoconfig.your-domain.com`	`443/tcp`	Traefik -> Mox HTTP
Autodiscover	`autodiscover.your-domain.com`	`443/tcp`	Traefik -> Mox HTTP
MTA-STS	`mta-sts.your-domain.com`	`443/tcp`	Traefik -> Mox HTTP

⚠️ PROVIDER SMTP BLOCKS
Many VPS providers block outbound SMTP by default. Hetzner Cloud, for example, blocks outgoing ports `25` and `465` until the account is eligible and the limit is lifted. Request this before relying on direct delivery, or configure a relayhost.

2. Prerequisites

You need:

A working Traefik v3 and CrowdSec stack.
A public IPv4 address. IPv6 is strongly recommended.
Control over DNS records for the mail domain.
Open firewall ports 25/tcp, 465/tcp, 587/tcp, and 993/tcp.
git, golang, jq, and openssl installed.

sudo apt update
sudo apt install -y git golang jq openssl

3. Create the Mox User and Build the Binary

Create a dedicated system user and build Mox from an explicit release tag.

sudo useradd --system --home-dir /home/mox --create-home --shell /usr/sbin/nologin mox
sudo install -d -o mox -g mox /home/mox/src

sudo -u mox git clone https://github.com/mjl-/mox.git /home/mox/src/mox
cd /home/mox/src/mox

# Replace this with the release tag you want to run.
sudo -u mox git checkout --detach vX.Y.Z
sudo -u mox git show --no-patch --format=fuller
sudo -u mox env CGO_ENABLED=0 go build \
  -trimpath -ldflags="-s -w" -o ./mox.new .

sudo install -o root -g mox -m 0750 ./mox.new /home/mox/mox

💡 USE RELEASE NOTES
Mox moves quickly. Check the upstream release notes before choosing or changing a release tag, especially on production mail systems. Compare the full commit shown by `git show` with the commit linked from the release page. The Mox command is built from the repository root (`.`), not from `./cmd/mox`.

4. Initial Mox Configuration

Run the quickstart in existing-webserver mode. Use -skipdial if DNS still points at an old server during a migration.

cd /home/mox

sudo /home/mox/mox quickstart \
  -hostname mail.your-domain.com \
  -adminemail postmaster@your-domain.com \
  -existing-webserver \
  -skipdial

This creates Mox configuration and data under /home/mox/config and /home/mox/data.

Now edit the generated config:

sudoedit /home/mox/config/mox.conf

For the internal listener, enable the HTTP services that Traefik will route to. In this example:

Account, admin, webmail, and web API use internal port 1080.
Autoconfig, autodiscover, and MTA-STS use internal port 81.
Forwarded: true tells Mox to respect the reverse proxy headers for rate limiting and secure cookies.
NonTLS: true is used for the internal listener because Traefik handles public HTTPS.

Conceptually, the internal listener should expose:

AccountHTTP    -> port 1080, Forwarded: true
AdminHTTP      -> port 1080, Forwarded: true
WebmailHTTP    -> port 1080, Forwarded: true
WebAPIHTTP     -> port 1080, Forwarded: true
AutoconfigHTTPS -> port 81, NonTLS: true
MTASTSHTTPS     -> port 81, NonTLS: true
WebserverHTTP   -> port 81

The public listener should bind your server’s real public IP addresses and enable SMTP, submission, SMTPS, and IMAPS.

ℹ️ EXPLICIT PUBLIC IPS
Prefer explicit public IPs in the Mox public listener. This makes outgoing mail source addresses predictable and helps Mox validate that your DNS and reverse DNS are consistent.

For MTA-STS, keep the generated short MaxAge while testing. Once the domain is reachable, certificates work, and the DNS records are stable, raise it to a production value such as:

MTASTS:
	PolicyID: 20260701T110042
	Mode: enforce
	MaxAge: 720h0m0s
	MX:
		- mail.your-domain.com

Change PolicyID whenever you materially change the MTA-STS policy. The matching DNS record under _mta-sts.your-domain.com must use the same new ID so remote mail servers fetch the updated policy.

5. systemd Service

Create /etc/systemd/system/mox.service:

[Unit]
Description=mox mail server
After=network-online.target
Wants=network-online.target

[Service]
UMask=007
LimitNOFILE=65535
Type=simple
WorkingDirectory=/home/mox
ExecStart=/home/mox/mox serve
ExecStop=/home/mox/mox stop
Restart=always
RestartSec=5s
SyslogFacility=mail

# Mox starts as root to bind low ports, then drops privileges.
PrivateDevices=yes
PrivateTmp=yes
ProtectSystem=strict
ReadWritePaths=/home/mox/config /home/mox/data
ProtectKernelTunables=yes
ProtectControlGroups=yes
CapabilityBoundingSet=CAP_SETUID CAP_SETGID CAP_NET_BIND_SERVICE CAP_CHOWN CAP_FSETID CAP_DAC_OVERRIDE CAP_DAC_READ_SEARCH CAP_FOWNER CAP_KILL
NoNewPrivileges=yes
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK
ProtectProc=invisible
RestrictNamespaces=yes
RestrictRealtime=yes
RemoveIPC=yes
ProtectHostname=yes
ProtectClock=yes
ProtectKernelLogs=yes
ProtectKernelModules=yes
MemoryDenyWriteExecute=yes
LockPersonality=yes
DevicePolicy=closed
SystemCallArchitectures=native
SystemCallFilter=@system-service

[Install]
WantedBy=multi-user.target

Enable it:

sudo systemctl daemon-reload
sudo systemctl enable --now mox
sudo systemctl status mox

6. Traefik File Provider Route

Because Mox is not a Docker container in this setup, use the Traefik file provider instead of Docker labels.

Create /opt/containers/traefik-stack/traefik/dynamic/mox.yml:

http:
  routers:
    mox-mail:
      rule: "Host(`mail.your-domain.com`)"
      entryPoints:
        - websecure
      service: mox-account
      tls:
        certResolver: tls_resolver
      middlewares:
        - security-headers@file
        - crowdsec-bouncer@docker

    mox-autoconfig:
      rule: "Host(`autoconfig.your-domain.com`) || Host(`autodiscover.your-domain.com`)"
      entryPoints:
        - websecure
      service: mox-web
      tls:
        certResolver: tls_resolver
      middlewares:
        - security-headers@file
        - crowdsec-bouncer@docker

    mox-mta-sts:
      rule: "Host(`mta-sts.your-domain.com`)"
      entryPoints:
        - websecure
      service: mox-web
      tls:
        certResolver: tls_resolver
      middlewares:
        - security-headers@file
        - crowdsec-bouncer@docker

  services:
    mox-account:
      loadBalancer:
        servers:
          - url: "http://172.18.0.1:1080"

    mox-web:
      loadBalancer:
        servers:
          - url: "http://172.18.0.1:81"

Replace 172.18.0.1 with the Docker bridge gateway address Traefik can use to reach the host.

docker network inspect proxy \
  --format '{{range .IPAM.Config}}{{println .Gateway}}{{end}}'

If UFW is enabled, allow only the Traefik Docker network to reach those host ports:

sudo ufw allow in on br-REPLACE_WITH_PROXY_BRIDGE_IFACE \
  from 172.18.0.0/16 to 172.18.0.1 port 1080 proto tcp

sudo ufw allow in on br-REPLACE_WITH_PROXY_BRIDGE_IFACE \
  from 172.18.0.0/16 to 172.18.0.1 port 81 proto tcp

Without these narrow bridge rules, Traefik may return 504 Gateway Timeout even though Mox is listening correctly.

7. TLS for Mail Protocols

Traefik can terminate HTTPS for web routes, but Mox still needs certificates for SMTP and IMAP TLS. You have two practical options:

Let Mox manage its own ACME certificates for the mail host.
Export the Traefik ACME certificate for the mail-related names and configure it in mox.conf.

For a Traefik-centered setup, exporting from acme.json keeps one certificate authority flow. The exact script depends on your resolver name and SAN layout, but the important result is that Mox has PEM files for:

/home/mox/tls/mail.your-domain.com-chain.crt.pem
/home/mox/tls/mail.your-domain.com.key.pem

Then reference them under the public listener’s TLS section:

TLS:
	KeyCerts:
		-
			CertFile: /home/mox/tls/mail.your-domain.com-chain.crt.pem
			KeyFile: /home/mox/tls/mail.your-domain.com.key.pem

ℹ️ A ONE-TIME EXPORT IS NOT ENOUGH
Traefik renews the certificate inside `acme.json`, but it does not update separate PEM files used by Mox. Automate the export and restart Mox after a validated certificate change, or the mail protocols will eventually serve an expired certificate even while HTTPS on port `443` remains valid.

The following root-owned script finds the certificate by hostname across all Traefik resolvers, validates its hostname, remaining lifetime, and private key, and only restarts Mox when the files actually change.

Create /usr/local/sbin/sync-traefik-cert-to-mox and adjust host_name, acme_json, and tls_dir if your paths differ:

#!/usr/bin/env bash
set -euo pipefail

readonly host_name="mail.your-domain.com"
readonly acme_json="/opt/containers/traefik-stack/traefik/certs/acme.json"
readonly tls_dir="/home/mox/tls"
readonly cert_dst="${tls_dir}/${host_name}-chain.crt.pem"
readonly key_dst="${tls_dir}/${host_name}.key.pem"

exec 9>/run/lock/mox-traefik-cert-sync.lock
flock 9

umask 077
tmp_dir="$(mktemp -d "${tls_dir}/.traefik-cert-sync.XXXXXX")"
cleanup() {
    find "$tmp_dir" -mindepth 1 -maxdepth 1 -type f -delete
    rmdir "$tmp_dir"
}
trap cleanup EXIT

jq -er --arg host "$host_name" '
  [
    to_entries[].value.Certificates[]?
    | select(
        .domain.main == $host
        or ((.domain.sans // []) | index($host))
      )
  ]
  | if length == 1 then .[0].certificate
    elif length == 0 then error("certificate not found for " + $host)
    else error("multiple certificates found for " + $host)
    end
' "$acme_json" | base64 --decode >"${tmp_dir}/certificate.pem"

jq -er --arg host "$host_name" '
  [
    to_entries[].value.Certificates[]?
    | select(
        .domain.main == $host
        or ((.domain.sans // []) | index($host))
      )
  ]
  | if length == 1 then .[0].key
    elif length == 0 then error("private key not found for " + $host)
    else error("multiple private keys found for " + $host)
    end
' "$acme_json" | base64 --decode >"${tmp_dir}/private-key.pem"

openssl x509 -in "${tmp_dir}/certificate.pem" \
  -noout -checkhost "$host_name" >/dev/null
openssl x509 -in "${tmp_dir}/certificate.pem" \
  -noout -checkend 86400 >/dev/null
openssl x509 -in "${tmp_dir}/certificate.pem" -pubkey -noout \
  | openssl pkey -pubin -outform DER >"${tmp_dir}/certificate.pub"
openssl pkey -in "${tmp_dir}/private-key.pem" -pubout -outform DER \
  >"${tmp_dir}/private-key.pub"
cmp -s "${tmp_dir}/certificate.pub" "${tmp_dir}/private-key.pub"

chmod 0600 "${tmp_dir}/certificate.pem" "${tmp_dir}/private-key.pem"
chown root:root "${tmp_dir}/certificate.pem" "${tmp_dir}/private-key.pem"

if [[ -f "$cert_dst" && -f "$key_dst" ]] \
  && cmp -s "${tmp_dir}/certificate.pem" "$cert_dst" \
  && cmp -s "${tmp_dir}/private-key.pem" "$key_dst"; then
    echo "Mox TLS certificate for ${host_name} is already current."
    exit 0
fi

install -o root -g root -m 0600 \
  "${tmp_dir}/certificate.pem" "${cert_dst}.next"
install -o root -g root -m 0600 \
  "${tmp_dir}/private-key.pem" "${key_dst}.next"
mv -f "${cert_dst}.next" "$cert_dst"
mv -f "${key_dst}.next" "$key_dst"

systemctl restart mox.service
systemctl is-active --quiet mox.service

echo "Updated Mox TLS certificate for ${host_name}:"
openssl x509 -in "$cert_dst" \
  -noout -subject -dates -serial -fingerprint -sha256

Install it with restricted permissions:

sudo chown root:root /usr/local/sbin/sync-traefik-cert-to-mox
sudo chmod 0750 /usr/local/sbin/sync-traefik-cert-to-mox

Create /etc/systemd/system/mox-traefik-cert-sync.service:

[Unit]
Description=Synchronize Traefik ACME certificate to Mox
After=docker.service
RequiresMountsFor=/opt/containers/traefik-stack/traefik/certs
ConditionPathExists=/opt/containers/traefik-stack/traefik/certs/acme.json

[Service]
Type=oneshot
ExecStart=/usr/local/sbin/sync-traefik-cert-to-mox

Create /etc/systemd/system/mox-traefik-cert-sync.path to react when Traefik changes acme.json:

[Unit]
Description=Watch Traefik ACME storage for Mox certificate updates

[Path]
PathChanged=/opt/containers/traefik-stack/traefik/certs/acme.json
Unit=mox-traefik-cert-sync.service

[Install]
WantedBy=paths.target

Create /etc/systemd/system/mox-traefik-cert-sync.timer as a fallback in case a filesystem event is missed:

[Unit]
Description=Periodic fallback sync of Traefik certificate to Mox

[Timer]
OnBootSec=2min
OnUnitActiveSec=6h
RandomizedDelaySec=5min
Persistent=true
Unit=mox-traefik-cert-sync.service

[Install]
WantedBy=timers.target

Run the first synchronization, then enable both triggers:

sudo systemctl daemon-reload
sudo systemctl start mox-traefik-cert-sync.service
sudo systemctl enable --now \
  mox-traefik-cert-sync.path \
  mox-traefik-cert-sync.timer

Confirm that Mox, the watcher, and the fallback timer are active:

sudo systemctl is-active \
  mox.service \
  mox-traefik-cert-sync.path \
  mox-traefik-cert-sync.timer

sudo systemctl list-timers mox-traefik-cert-sync.timer --all

8. Firewall

Open the mail ports:

sudo ufw allow 25/tcp
sudo ufw allow 465/tcp
sudo ufw allow 587/tcp
sudo ufw allow 993/tcp

Keep the Mox internal HTTP ports restricted to Traefik’s Docker bridge only. Do not expose 1080 or 81 publicly.

9. DNS Checklist

Mox has a built-in DNS record generator and checker. Use both:

sudo /home/mox/mox -config /home/mox/config/mox.conf config dnsrecords your-domain.com
sudo /home/mox/mox -config /home/mox/config/mox.conf config dnscheck your-domain.com

The generated output is authoritative for your installation. Do not copy the example values below blindly, but use them as a checklist for the record types your DNS provider should contain.

Core Mail Records

At minimum, configure the mail host, MX, and SPF:

mail.your-domain.com.       A      YOUR_IPV4
mail.your-domain.com.       AAAA   YOUR_IPV6
mail.your-domain.com.       TXT    "v=spf1 a -all"
your-domain.com.            MX     10 mail.your-domain.com.
your-domain.com.            TXT    "v=spf1 ip4:YOUR_IPV4 ip6:YOUR_IPV6 mx ~all"

Only publish one SPF TXT record per name. Two TXT records beginning with v=spf1 on the same name are invalid and Mox will report multiple spf txt records in dns.

If you do not use IPv6, omit the AAAA record and the ip6: mechanism. If you do use IPv6, make sure Mox binds to that same address and that reverse DNS exists for it.

DKIM

Add all DKIM selector records generated by Mox, for example:

2026a._domainkey.your-domain.com. TXT "v=DKIM1;h=sha256;p=..."
2026b._domainkey.your-domain.com. TXT "v=DKIM1;h=sha256;p=..."

When entering DKIM through a DNS provider web UI, combine the zonefile-style split strings into one long TXT value. Keep old DKIM selectors only if you still need to validate mail sent before the migration or from another system; Mox itself signs with the selectors configured in domains.conf.

DMARC and TLS Reporting

Mox can route technical reports into dedicated mailboxes on an existing account. A typical generated domain config looks like this:

DMARC:
	Localpart: dmarcreports
	Account: operator
	Mailbox: DMARC
TLSRPT:
	Localpart: tlsreports
	Account: operator
	Mailbox: TLSRPT

That means the following addresses do not have to be normal login accounts:

dmarcreports@your-domain.com
tlsreports@your-domain.com
tlsreports@mail.your-domain.com

They are technical report sinks. Mox delivers them to the configured account and mailbox.

Example records:

_dmarc.your-domain.com.             TXT "v=DMARC1;p=reject;rua=mailto:dmarcreports@your-domain.com!10m"
_smtp._tls.your-domain.com.         TXT "v=TLSRPTv1; rua=mailto:tlsreports@your-domain.com"
_smtp._tls.mail.your-domain.com.    TXT "v=TLSRPTv1; rua=mailto:tlsreports@mail.your-domain.com"

The !10m suffix in the DMARC rua value is a report size limit, not part of the mailbox name.

MTA-STS

MTA-STS needs both the HTTPS endpoint and the TXT policy ID:

mta-sts.your-domain.com.       CNAME mail.your-domain.com.
_mta-sts.your-domain.com.      TXT "v=STSv1; id=20260701T110042"

The TXT id must match the current policy ID in Mox. Whenever you change the MTA-STS policy, change both the Mox PolicyID and this DNS TXT value. Do not leave multiple _mta-sts TXT records behind; Mox will report multiple mta-sts records.

Autoconfig and SRV Records

For client autoconfiguration:

autoconfig.your-domain.com.          CNAME mail.your-domain.com.
autodiscover.your-domain.com.        CNAME mail.your-domain.com.
_autodiscover._tcp.your-domain.com.  SRV 0 1 443 mail.your-domain.com.
_imaps._tcp.your-domain.com.         SRV 0 1 993 mail.your-domain.com.
_submissions._tcp.your-domain.com.   SRV 0 1 465 mail.your-domain.com.

Mox may also generate optional SRV records that explicitly disable plaintext IMAP, plaintext submission, and POP3:

_imap._tcp.your-domain.com.          SRV 0 0 0 .
_submission._tcp.your-domain.com.    SRV 0 0 0 .
_pop3._tcp.your-domain.com.          SRV 0 0 0 .
_pop3s._tcp.your-domain.com.         SRV 0 0 0 .

These optional records are useful for a completely quiet dnscheck, but some DNS web interfaces do not accept . as a target. If your provider rejects them, leave them out; the secure IMAPS and submissions SRV records above are the important ones.

Reverse DNS

Set reverse DNS/PTR at your server provider, not at the domain DNS provider:

YOUR_IPV4 -> mail.your-domain.com
YOUR_IPV6 -> mail.your-domain.com

Forward and reverse DNS should agree: mail.your-domain.com must resolve back to the same public IP addresses.

Checking Authoritative DNS

Resolver caches can show stale values for a while. If dnscheck still reports an old DMARC, TLSRPT, SPF, or MTA-STS record after you changed it, query the authoritative nameserver directly:

dig +short @ns1.your-dns-provider.example TXT _dmarc.your-domain.com
dig +short @ns1.your-dns-provider.example TXT _smtp._tls.your-domain.com
dig +short @ns1.your-dns-provider.example TXT _mta-sts.your-domain.com

If the authoritative nameserver is correct but Mox still sees old records, wait for the previous TTL to expire.

⚠️ DNSBL RESOLVER WARNINGS
Some cloud provider resolvers can trigger DNSBL “open resolver” warnings, especially with Spamhaus checks. If you use DNSBLs in production, make sure your recursive resolver and DNSBL access pattern are acceptable for the provider.

10. Accounts and Passwords

Create accounts in the admin UI at:

https://mail.your-domain.com/admin/

Users can change their own account settings and password at:

https://mail.your-domain.com/

You can also set account passwords from the CLI:

printf '%s\n' 'NEW_PASSWORD' | \
  sudo /home/mox/mox -config /home/mox/config/mox.conf setaccountpassword user

Use the account name without the domain if that is how the account exists in Mox.

11. Client Configuration

For IMAP clients:

Server: mail.your-domain.com
Port: 993
TLS: IMAPS / implicit TLS
Username: full email address

For SMTP clients:

Server: mail.your-domain.com
Port: 465
TLS: implicit TLS
Username: full email address

For mbsync, Mox worked reliably with PLAIN over IMAPS. The credentials are still protected by the TLS connection:

IMAPStore user@your-domain.com-remote
Host mail.your-domain.com
Port 993
User user@your-domain.com
PassCmd "pass user@your-domain.com"
AuthMechs PLAIN
TLSType IMAPS
CertificateFile /etc/ssl/certs/ca-certificates.crt

If you see this with AuthMechs LOGIN:

LOGIN unrecognized syntax/command: invalid escape char

switch to AuthMechs PLAIN. Do not enable plaintext IMAP; TLSType IMAPS must remain set.

12. Junk Training and Introbox

Mox combines sender reputation with a per-account Bayesian junk filter. Authentication results such as SPF, DKIM, and DMARC establish sender identity, but an authenticated domain can still send spam. Correct user feedback is therefore essential.

The generated account configuration commonly treats Junk or Spam as junk, Inbox and technical mailboxes as neutral, and all remaining mailboxes as not-junk. That can be surprising: deleting spam into Trash may teach the filter that the message is legitimate.

For users who delete unwanted mail before classifying it, make Trash neutral and enable an Introbox for first-time correspondents:

Accounts:
	user:
		Introbox: Introbox
		AutomaticJunkFlags:
			Enabled: true
			JunkMailboxRegexp: ^(junk|spam)
			NeutralMailboxRegexp: ^(inbox|introbox|neutral|postmaster|dmarc|tlsrpt|rejects|trash)

Create the Introbox mailbox in webmail or through IMAP before enabling it. With this configuration:

Move actual spam to Junk; moving it only to Trash no longer trains the filter.
Move legitimate messages incorrectly placed in Junk to Archive or explicitly mark them as not junk.
Messages from first-time correspondents are separated in Introbox. Moving a wanted message out of Introbox establishes positive reputation for future messages.
Keep enough classified messages for useful training. Emptying all training mail immediately makes the content filter less effective.

After correcting classifications or changing junk-filter parameters, rebuild the account filter:

cd /home/mox
sudo ./mox retrain user

⚠️ TRASH CAN POISON JUNK TRAINING
When `AutomaticJunkFlags` is enabled and neither `Trash` nor another mailbox matches the junk or neutral expressions, it can fall into the implicit not-junk category. Repeatedly deleting a spam campaign into that mailbox then gives its senders and vocabulary positive reputation. Inspect the `X-Mox-Reason` header and Mox logs if obviously repetitive spam starts receiving `msgfromdomain` or very low content-spam scores.

13. Migrating from Mailcow

Do not blindly copy Mailcow/Dovecot files into Mox.

Mailcow installations may use Dovecot plugins such as mail_crypt and zlib. In that case, the files in the Mailcow vmail volume can be encrypted or compressed in a Dovecot-specific format. Importing those raw files into Mox produces broken messages with binary-looking headers.

Safer migration options:

IMAP-to-IMAP migration with a tool such as imapsync.
Local decrypted Maildir import from an existing mbsync cache that was synced through Dovecot/IMAP before the migration.
Selective migration of only active mailboxes and folders.

For a lightweight move, migrate active accounts and skip stale test folders. Keep the old Mailcow server stopped but preserved for a short rollback window.

14. Verification

Web routes:

curl -I https://mail.your-domain.com/
curl -I https://autoconfig.your-domain.com/
curl -I https://mta-sts.your-domain.com/.well-known/mta-sts.txt

IMAPS:

openssl s_client -connect mail.your-domain.com:993 \
  -servername mail.your-domain.com -brief

SMTPS:

openssl s_client -connect mail.your-domain.com:465 \
  -servername mail.your-domain.com -brief

Submission:

openssl s_client -starttls smtp -connect mail.your-domain.com:587 \
  -servername mail.your-domain.com -brief

SMTP delivery:

nc -vz mail.your-domain.com 25

Finally, send mail to and from an external mailbox and check:

sudo journalctl -u mox -f
sudo /home/mox/mox -config /home/mox/config/mox.conf config dnscheck your-domain.com

15. Backups and Updates

Do not replace a production binary first and hope that its data migration succeeds. Read the release notes for every version between the installed and target releases, then test the candidate against a disposable backup.

Build the candidate from an explicit release tag:

sudo install -d -o mox -g mox /home/mox/src

if [ ! -d /home/mox/src/mox/.git ]; then
  sudo -u mox git clone https://github.com/mjl-/mox.git /home/mox/src/mox
fi

cd /home/mox/src/mox
sudo -u mox git fetch --tags --force
sudo -u mox git checkout --detach vNEW.VERSION
sudo -u mox git show --no-patch --format=fuller
sudo -u mox env CGO_ENABLED=0 go build \
  -trimpath -ldflags="-s -w" -o ./mox.new .
sudo -u mox ./mox.new version

Create and verify a dry-run backup with the currently installed binary, then inspect the same copy with the candidate:

cd /home/mox
sudo ./mox config test
sudo ./mox backup data/tmp/testupgrade
sudo ./mox verifydata data/tmp/testupgrade/data
sudo /home/mox/src/mox/mox.new verifydata data/tmp/testupgrade/data

The candidate verifydata may upgrade database files inside testupgrade. Never use that modified dry-run directory as the rollback backup. Create a fresh backup with the old binary after the dry run succeeds:

cd /home/mox
sudo ./mox backup data/tmp/pre-upgrade
sudo ./mox verifydata data/tmp/pre-upgrade/data
sudo cp -p ./mox ./mox.rollback

Install, restart, and verify:

sudo install -o root -g mox -m 0750 \
  /home/mox/src/mox/mox.new /home/mox/mox
sudo systemctl restart mox
sudo systemctl is-active mox
sudo /home/mox/mox version
sudo /home/mox/mox -config /home/mox/config/mox.conf config test
sudo journalctl -u mox --since "5 minutes ago" --no-pager -p warning

Also include these locations in normal off-host backups:

/home/mox/config
/home/mox/data
/home/mox/tls

Conclusion

Mox works best as a real mail server with direct ownership of SMTP and IMAP. Traefik remains valuable for the browser-facing endpoints, but it should not hide the fact that mail delivery depends on DNS, reverse DNS, provider port policy, TLS on mail protocols, and careful migration of existing mail data.

📚MOX DOCUMENTATION 📦MOX GITHUB REPOSITORY

Adding Authelia 2FA to Matrix Synapse with OpenID Connect

Unknown — Fri, 17 Jul 2026 00:00:00 +0000

Synapse does not provide native TOTP login for local Matrix passwords. It can, however, delegate interactive login to an OpenID Connect Provider. This guide connects Authelia to Synapse so a human Matrix login can require an Authelia password plus TOTP or WebAuthn.

The difficult part is not the redirect. It is preserving the identity of an existing Matrix user. If automatic OIDC registration remains enabled, a careless first login can create a second account; a premature password shutdown can then lock you out of the original account. The migration below disables new OIDC registration and keeps the old login available until the mapping is proven.

Changelog

Date	Change
2026-07-17	Initial Version: Added Authelia OIDC, Element X compatibility warning, safe existing-account linking, E2EE-aware session cleanup, bot-token checks, rollback, and password-login cutover.

1. Read This Compatibility Gate First

⚠️ ELEMENT X REQUIRES A DIFFERENT ARCHITECTURE
The `matrix-docker-ansible-deploy` project currently warns that newer clients such as Element X support SSO only through Matrix Authentication Service (MAS), not through legacy Synapse OIDC. The direct Synapse-to-Authelia setup in this article is suitable only if every required client supports Synapse’s legacy SSO flow, such as the compatible Element Web/Desktop path you have tested. If Element X is mandatory, stop here. Keep password login for now or design MAS with Authelia as its upstream OIDC Provider. Do not discover the incompatibility after disabling passwords.

This is the most important correction to the seemingly simple “Authelia → Synapse → disable passwords” plan. Authelia itself is not the compatibility problem; the client-facing Matrix authentication architecture is.

2. Prerequisites and Scope

Complete these guides first:

This article assumes:

Authelia is available at https://auth.your-domain.com;
Synapse is available at https://matrix.your-domain.com;
the Matrix ID to preserve is @your-username:your-domain.com;
the Authelia username is exactly your-username;
Synapse is managed by matrix-docker-ansible-deploy in /opt/containers/matrix;
the existing Matrix password login remains enabled during migration.

The integration has four independent identifiers. Do not conflate them:

Value	Example	Purpose
Matrix localpart	`your-username`	Left side of the existing Matrix ID.
OIDC `preferred_username`	`your-username`	Candidate localpart used only when linking/creating the Matrix user.
OIDC `sub`	opaque stable value	Permanent external identity key stored by Synapse.
OIDC provider ID	`authelia`	Becomes `oidc-authelia` in Synapse’s external-ID Admin API.

The sub claim does not become the Matrix username. It is the opaque anchor that Synapse binds to the account after mapping. The mapping template uses preferred_username to find the existing localpart.

3. Protect the Existing Matrix Account Before Migration

Before changing authentication:

Confirm the exact Matrix ID in the currently logged-in client.
Secure the Matrix recovery key or recovery phrase.
Keep at least one verified, working Element session.
Review the client/device list and record which sessions are yours.
Create consistent backups of Synapse’s database and configuration.
Back up the Authelia configuration, database, and secrets as one set.
Test the required Matrix clients against a non-critical account if possible.

⚠️ DO NOT LOG OUT EVERY E2EE SESSION YET
Matrix access tokens issued before 2FA remain valid until revoked, so they must eventually be reviewed. But blindly logging out every device can also remove the easiest route to verify a new session and recover encrypted history. First prove that account recovery and the OIDC login work; then revoke unknown or deliberately retired sessions.

4. Add the Matrix Group to Authelia

Edit /opt/containers/authelia/config/users_database.yml and add a dedicated group to every human allowed to log in to Matrix:

users:
  your-username:
    disabled: false
    displayname: 'Your Name'
    password: '$argon2id$v=19$m=65536,t=3,p=4$YOUR-EXISTING-DIGEST'
    email: 'you@your-domain.com'
    groups:
      - 'admins'
      - 'synapse-users'

Synapse will require the synapse-users claim, so an authenticated Authelia user outside this group still cannot use this OIDC client.

5. Generate OIDC Keys and the Client Secret

Authelia needs an HMAC secret and at least one RSA signing key. Create them as protected files:

cd /opt/containers/authelia

sudo install -o 1000 -g 1000 -m 600 /dev/null secrets/OIDC_HMAC_SECRET
openssl rand -hex 64 | sudo tee secrets/OIDC_HMAC_SECRET >/dev/null

sudo openssl genrsa -out secrets/OIDC_JWKS_RSA_PRIVATE_KEY 4096
sudo chown 1000:1000 secrets/OIDC_JWKS_RSA_PRIVATE_KEY
sudo chmod 600 secrets/OIDC_JWKS_RSA_PRIVATE_KEY

Replace 1000:1000 if the Authelia stack uses different PUID and PGID values.

Generate a random RFC 3986-safe plaintext client secret and its PBKDF2-SHA512 digest:

docker run --rm authelia/authelia:4.39.20 \
  authelia crypto hash generate pbkdf2 \
  --variant sha512 \
  --random \
  --random.length 72 \
  --random.charset rfc3986

The command prints two different values:

Random Password: the plaintext secret, stored on the Synapse side as client_secret;
Digest: the $pbkdf2-sha512$... value, stored in Authelia’s client definition.

Do not swap them. Save the plaintext directly in your secret manager; do not paste it into a chat, issue, or Git repository.

6. Enable Authelia’s OIDC Provider

6.1. Enable the Configuration Template Filter

The official Authelia documentation recommends reading the private signing key from a file through its configuration template filter. Add these variables to the Authelia service in /opt/containers/authelia/compose.yml:

environment:
  # Keep all variables from the base Authelia guide.
  X_AUTHELIA_CONFIG_FILTERS: 'template'
  AUTHELIA_IDENTITY_PROVIDERS_OIDC_HMAC_SECRET_FILE: /secrets/OIDC_HMAC_SECRET

The existing read-only ./secrets:/secrets:ro mount makes both OIDC files available without baking them into the image.

6.2. Add the Provider and Synapse Client

Append this block to /opt/containers/authelia/config/configuration.yml. Replace the client digest with the Digest from the previous section:

identity_providers:
  oidc:
    jwks:
      - algorithm: 'RS256'
        use: 'sig'
        key: {{ secret "/secrets/OIDC_JWKS_RSA_PRIVATE_KEY" | mindent 10 "|" | msquote }}
    clients:
      - client_id: 'synapse'
        client_name: 'Synapse'
        client_secret: '$pbkdf2-sha512$REPLACE-WITH-THE-DIGEST'
        public: false
        authorization_policy: 'two_factor'
        require_pkce: false
        pkce_challenge_method: ''
        redirect_uris:
          - 'https://matrix.your-domain.com/_synapse/client/oidc/callback'
        scopes:
          - 'openid'
          - 'profile'
          - 'email'
          - 'groups'
        response_types:
          - 'code'
        grant_types:
          - 'authorization_code'
        access_token_signed_response_alg: 'none'
        userinfo_signed_response_alg: 'none'
        token_endpoint_auth_method: 'client_secret_basic'

authorization_policy: 'two_factor' is the hard Authelia policy for this OIDC client. A logged-in one-factor Authelia session alone is not sufficient to authorize Synapse.

ℹ️ WHY PKCE IS DISABLED FOR THIS CLIENT
This follows the current official Authelia/Synapse integration profile: Synapse is a confidential client authenticating with `client_secret_basic`, while this integration does not use PKCE. Do not generalize this setting to public browser or mobile OIDC clients.

Validate and restart Authelia:

cd /opt/containers/authelia
docker compose config --quiet
docker compose up -d
docker compose exec authelia authelia config validate --config /config/configuration.yml
docker compose logs --tail=150 authelia

Check the discovery endpoint:

curl -fsS https://auth.your-domain.com/.well-known/openid-configuration | jq .issuer

It must report the exact HTTPS issuer URL used in the Synapse configuration.

7. Configure Synapse OIDC Without Disabling Passwords

Edit:

/opt/containers/matrix/inventory/host_vars/matrix.your-domain.com/vars.yml

Add the following variables. Replace the client secret with the Random Password generated in section 5:

matrix_synapse_oidc_enabled: true
matrix_synapse_oidc_providers:
  - idp_id: 'authelia'
    idp_name: 'Authelia'
    discover: true
    issuer: 'https://auth.your-domain.com'
    client_id: 'synapse'
    client_secret: 'REPLACE-WITH-THE-RANDOM-PASSWORD'
    scopes:
      - 'openid'
      - 'profile'
      - 'email'
      - 'groups'
    allow_existing_users: true
    enable_registration: false
    user_profile_method: 'userinfo_endpoint'
    user_mapping_provider:
      config:
        subject_template: "{{ user.sub }}"
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"
        email_template: "{{ user.email }}"
    attribute_requirements:
      - attribute: 'groups'
        value: 'synapse-users'

# Keep local password login enabled throughout the migration.
matrix_synapse_password_config_enabled: true

# Keep normal Matrix registration disabled as a second, global control.
matrix_synapse_enable_registration: false

user_profile_method: 'userinfo_endpoint' is the current Authelia-documented compatibility escape hatch for Synapse’s claim handling. The provider-level enable_registration: false is distinct from the global Matrix setting and makes this OIDC flow sign-in-only.

⚠️ ALLOW_EXISTING_USERS IS POWERFUL
`allow_existing_users: true` permits an OIDC identity whose mapped localpart matches a pre-existing Matrix user to bind to that account. This is necessary for the migration, but it also means control of Authelia’s usernames and claims is security-critical. Restrict the client to `synapse-users`, keep public Matrix registration disabled, and do not let users claim another person’s `preferred_username`.

Apply the playbook using the same Ansible environment and conventions as the main Matrix guide:

cd /opt/containers/matrix
sudo ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start

At this point both OIDC and the original password login should be available.

8. Prove the Existing-Account Mapping

8.1. Test in a Separate Browser Session

Keep the current verified Matrix client open. In a private browser window:

Open the compatible Element Web login page.
Choose the Authelia SSO option.
Complete the password and second factor.
Check the Matrix ID after login.
Confirm it is exactly @your-username:your-domain.com.
Confirm the expected joined rooms and account data are present.
Verify the new E2EE session from the existing trusted session or recovery material.

Seeing an empty room list or a different Matrix ID means the mapping did not land on the existing account. Stop immediately and keep password login enabled.

ℹ️ A WRONG MAPPING DOES NOT DELETE THE OLD ACCOUNT
With this guide’s provider-level `enable_registration: false`, an unknown mapping should fail instead of creating a new Matrix user. If automatic OIDC registration was enabled elsewhere and a mismatch created a separate account, it still did not erase the original one. A lockout happens only if you then disable the original login route or discard its remaining sessions. Correct the mapping and retry while the original account is still accessible.

8.2. Verify the External ID with Synapse’s Admin API

Use a Synapse administrator token without writing it into shell history:

read -rsp 'Synapse admin token: ' SYNAPSE_ADMIN_TOKEN
echo

curl -fsS \
  -H "Authorization: Bearer ${SYNAPSE_ADMIN_TOKEN}" \
  'https://matrix.your-domain.com/_synapse/admin/v2/users/%40your-username%3Ayour-domain.com' \
  | jq '{name, external_ids}'

unset SYNAPSE_ADMIN_TOKEN

The result should show the original Matrix ID and an external entry resembling:

{
  "auth_provider": "oidc-authelia",
  "external_id": "an-opaque-stable-subject"
}

The external_id is Authelia’s sub, not the username.

⚠️ DO NOT PATCH THE SYNAPSE DATABASE WITH SQL
Do not use an ad-hoc `INSERT INTO user_external_ids ...` as the normal migration method. Synapse provides a supported User Admin API for external IDs. If manual pre-binding is genuinely necessary, use that API, preserve every existing account field and external ID from a preceding `GET`, and take a database backup first. A partial `PUT` can replace array-valued fields, so this is a break-glass procedure, not a copy-and-paste shortcut.

9. Review Sessions Without Losing E2EE Recovery

OIDC 2FA protects new interactive logins. It does not retroactively add a second factor to existing Matrix access tokens.

After the mapping and E2EE recovery path are proven:

Review every Matrix device/session.
Revoke unknown sessions immediately.
Retire old sessions you no longer need.
Keep enough verified sessions or recovery material to bootstrap new E2EE clients.
If you require a strict clean cutover, revoke all pre-2FA human sessions only after the new OIDC session is verified and recovery has been tested.

“Log out all other devices” is therefore a policy choice, not an automatic prerequisite. It closes old-token bypasses but must be sequenced around encrypted-session recovery.

10. Verify Bots and Automation

Before disabling password login, verify that Hermes bots, bridges, and other automations use existing Matrix access tokens rather than logging in with a username and password.

Disabling password_config.enabled prevents new password logins; it does not invalidate already-issued access tokens. Token-authenticated bots should continue to work. However, if a bot token is later lost or revoked, the bot cannot obtain a replacement through password login while the feature is disabled. Document a recovery path, such as temporarily re-enabling password login under controlled conditions.

Test each automation before and after the cutover:

receive an allowed Matrix message;
send a reply;
restart the bot and confirm it reconnects with the stored token;
confirm Matrix user and room allowlists remain enforced.

Only continue after all of the following are true:

every required client is compatible with legacy Synapse OIDC;
the OIDC login reaches the exact old Matrix ID;
the Admin API shows oidc-authelia on that account;
E2EE recovery and session verification work;
bot and bridge token authentication has been tested;
a current rollback backup exists.

Then change the playbook variable:

matrix_synapse_password_config_enabled: false

Apply and test again:

cd /opt/containers/matrix
sudo ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start

Confirm that:

Authelia SSO still reaches the existing account.
The second factor is required in a genuinely new Authelia session.
Direct Matrix password login is rejected.
Hermes and other token-based integrations still work after restart.

📝 YOU MAY KEEP PASSWORD LOGIN AS A RECOVERY ROUTE
Running OIDC and local passwords in parallel is a valid compatibility phase, but the local password remains a 2FA bypass for new logins. If you keep it, treat it as an explicit risk decision: use a long unique password, tightly control who has one, monitor sessions, and periodically retest the OIDC path.

12. Rollback

If the cutover fails:

Set matrix_synapse_password_config_enabled: true again.
Re-apply the playbook.
Use the retained verified session or local password to regain the original account.
Do not delete the OIDC external-ID binding unless you have identified a mapping error.
Inspect Synapse and Authelia logs before retrying.

sudo journalctl -u matrix-synapse.service --since '30 minutes ago'

cd /opt/containers/authelia
docker compose logs --since=30m authelia

If a separate account was accidentally created, deactivate it only after confirming that it is not the original account and contains no data you need.

13. What This Setup Protects

The final login path is:

Element Web/Desktop
        │
        ▼
     Synapse ──OIDC redirect──> Authelia
        ▲                         │
        │                         ├─ password
        └──── authorization code ─└─ TOTP or WebAuthn

This protects new human SSO logins against password-only compromise. It does not make the following disappear:

already-issued Matrix access tokens;
a compromised verified Element session;
loss of the Matrix recovery key;
an administrator who can change Authelia claims or Synapse mappings;
a stolen bot token;
application or host compromise.

That is not a flaw in OIDC; it is the normal boundary between authentication, sessions, authorization, and host security.

Conclusion

Authelia can add real TOTP or WebAuthn enforcement to compatible Synapse SSO logins without replacing the existing Matrix account. The safe sequence is what matters: preserve E2EE recovery, enable OIDC alongside passwords, map preferred_username to the exact existing localpart, verify the persistent sub binding, review old tokens, test bots, and only then decide whether password login should disappear.

For Element X, use the compatibility gate rather than forcing this legacy path: evaluate MAS with Authelia upstream or retain a supported login method.

📚OFFICIAL AUTHELIA + SYNAPSE GUIDE 🔐SYNAPSE OIDC DOCUMENTATION 🧩MATRIX PLAYBOOK OIDC NOTES ↩️GENERAL AUTHELIA GUIDE

Authelia with Docker Compose and Traefik: Lightweight SSO and 2FA

Unknown — Fri, 17 Jul 2026 00:00:00 +0000

Authelia is a self-hosted authentication and authorization server. It can add a central login and a second factor to web applications through a reverse proxy, and it can act as an OpenID Connect (OIDC) Provider for applications with native SSO support.

This guide builds a small, single-node Authelia deployment with Docker Compose, a file-based user directory, SQLite storage, SMTP notifications, and the Traefik stack used throughout this site. It is a practical fit for a personal server or a small trusted group; it is not a high-availability design.

Changelog

Date	Change
2026-07-17	Initial Version: Added a pinned Authelia deployment, Traefik ForwardAuth, TOTP/WebAuthn enrollment, secret files, testing, backups, and upgrade guidance.

1. What Authelia Does — and What It Does Not Do

Authelia provides two related integration modes:

Mode	Best for	How it works
Traefik ForwardAuth	Browser-based services without native OIDC	Traefik asks Authelia whether each request may pass.
OpenID Connect Provider	Applications with native SSO support	The application redirects the user to Authelia and receives an identity token.

Both modes can share the same account and second-factor registration. That makes Authelia more useful than a Matrix-only authentication component: one instance can protect dashboards through ForwardAuth and also provide OIDC to services such as Synapse, Forgejo, or other compatible applications.

⚠️ DO NOT PUT EVERY API BEHIND FORWARDAUTH
ForwardAuth is ideal for interactive browser applications. Native mobile clients, webhooks, CalDAV/CardDAV endpoints, and machine APIs may not understand a redirect to a login portal. Prefer the application’s native OIDC integration, a dedicated API token, or a narrowly scoped bypass rule for those endpoints.

Authelia strengthens the login path. It does not revoke sessions that an application already issued, repair weak application permissions, replace backups, or make a compromised reverse proxy harmless.

Browser ──HTTPS──> Traefik ──ForwardAuth──> Authelia
                       │                       │
                       │ allowed               ├─ password file
                       ▼                       ├─ TOTP / WebAuthn state
                 protected app                └─ SQLite + SMTP

OIDC-capable app ──redirect──> Authelia ──signed identity──> app

2. Prerequisites and Design Choices

Complete the Traefik v3 and CrowdSec guide first. This article reuses its:

external Docker network named proxy;
HTTPS entrypoint named websecure;
certificate resolver named tls_resolver;
security-headers@file and crowdsec-bouncer@docker middlewares.

You also need:

a DNS record such as auth.your-domain.com pointing to the server;
working SMTP credentials for registration and recovery messages;
Docker Compose and OpenSSL;
a password manager and an authenticator or security key.

This guide pins Authelia 4.39.20, the current release tested by the official Synapse integration guide at the time of writing. Review the Authelia releases before changing the pin.

ℹ️ WHY SQLITE HERE?
Authelia supports SQLite for a single instance. It is simple and sufficient for this small deployment, but it prevents a multi-instance high-availability setup. Use PostgreSQL or MySQL if you later run multiple Authelia replicas.

3. Create the Directory Structure

sudo mkdir -p /opt/containers/authelia/{config,data,secrets}
cd /opt/containers/authelia

sudo touch config/configuration.yml config/users_database.yml
sudo chmod 600 config/configuration.yml config/users_database.yml
sudo chmod 700 secrets

The resulting layout is deliberately split by purpose:

/opt/containers/authelia/
├── compose.yml
├── .env
├── config/
│   ├── configuration.yml
│   └── users_database.yml
├── data/
│   └── db.sqlite3             # created by Authelia
└── secrets/
    ├── RESET_PASSWORD_JWT_SECRET
    ├── SESSION_SECRET
    ├── STORAGE_ENCRYPTION_KEY
    └── SMTP_PASSWORD

4. Create the Environment and Secret Files

Create /opt/containers/authelia/.env:

AUTHELIA_HOST=auth.your-domain.com
TZ=Europe/Vienna
PUID=1000
PGID=1000

Replace PUID and PGID with the account that owns the stack:

id -u
id -g

Align the bind-mount ownership with those values (replace 1000:1000 if necessary):

sudo chown -R 1000:1000 config data secrets

Generate the three local cryptographic secrets without printing them to the terminal:

cd /opt/containers/authelia

sudo install -o 1000 -g 1000 -m 600 /dev/null secrets/RESET_PASSWORD_JWT_SECRET
openssl rand -hex 64 | sudo tee secrets/RESET_PASSWORD_JWT_SECRET >/dev/null

sudo install -o 1000 -g 1000 -m 600 /dev/null secrets/SESSION_SECRET
openssl rand -hex 64 | sudo tee secrets/SESSION_SECRET >/dev/null

sudo install -o 1000 -g 1000 -m 600 /dev/null secrets/STORAGE_ENCRYPTION_KEY
openssl rand -hex 64 | sudo tee secrets/STORAGE_ENCRYPTION_KEY >/dev/null

sudo install -o 1000 -g 1000 -m 600 /dev/null secrets/SMTP_PASSWORD
sudo nano secrets/SMTP_PASSWORD

Enter only the SMTP password in the last file. Do not put a trailing explanation or username in it. The -o and -g values must stay aligned with PUID and PGID, otherwise the unprivileged container process cannot read the files.

⚠️ THE STORAGE ENCRYPTION KEY IS NOT DISPOSABLE
Back up `STORAGE_ENCRYPTION_KEY` securely. Authelia encrypts sensitive database values with it, including TOTP material. Losing the key can make the corresponding database state unusable; leaking it weakens the protection of a stolen database.

5. Configure Authelia

Create /opt/containers/authelia/config/configuration.yml:

server:
  address: 'tcp://0.0.0.0:9091/'

log:
  level: 'info'

theme: 'dark'

totp:
  disable: false
  issuer: 'your-domain.com'
  period: 30
  skew: 1

webauthn:
  disable: false
  display_name: 'Your Domain'

identity_validation:
  reset_password:
    jwt_lifespan: '5 minutes'

authentication_backend:
  password_reset:
    disable: false
  refresh_interval: '5 minutes'
  file:
    path: '/config/users_database.yml'
    watch: true
    password:
      algorithm: 'argon2'
      argon2:
        variant: 'argon2id'
        iterations: 3
        memory: 65536
        parallelism: 4
        key_length: 32
        salt_length: 16

access_control:
  default_policy: 'deny'
  rules:
    - domain: 'protected.your-domain.com'
      policy: 'two_factor'

session:
  name: 'authelia_session'
  same_site: 'lax'
  inactivity: '5 minutes'
  expiration: '1 hour'
  remember_me: '1 month'
  cookies:
    - domain: 'your-domain.com'
      authelia_url: 'https://auth.your-domain.com'
      default_redirection_url: 'https://protected.your-domain.com'

regulation:
  max_retries: 3
  find_time: '2 minutes'
  ban_time: '5 minutes'

storage:
  local:
    path: '/data/db.sqlite3'

notifier:
  smtp:
    address: 'submission://mail.your-domain.com:587'
    username: 'authelia@your-domain.com'
    sender: 'Authelia <authelia@your-domain.com>'
    subject: '[Authelia] {title}'

The password, session, reset-token, and storage secrets are intentionally absent. Docker injects them from files in the next section.

Adjust the session cookie domain to the parent domain shared by the portal and protected services. Never set it to a public suffix such as .com. Add one sequential access_control.rules entry per protected host or path; with default_policy: deny, an unlisted destination remains closed.

6. Create the First User

Generate an Argon2id password digest interactively, so the plaintext password does not appear in shell history:

docker run --rm -it authelia/authelia:4.39.20 \
  authelia crypto hash generate argon2

Copy only the resulting $argon2id$... digest into /opt/containers/authelia/config/users_database.yml:

users:
  your-username:
    disabled: false
    displayname: 'Your Name'
    password: '$argon2id$v=19$m=65536,t=3,p=4$REPLACE-WITH-YOUR-DIGEST'
    email: 'you@your-domain.com'
    groups:
      - 'admins'

The username is security-sensitive when an application automatically links OIDC identities to existing accounts. Users must not be allowed to rename themselves to another person’s application username.

7. Create the Docker Compose Stack

Create /opt/containers/authelia/compose.yml:

services:
  authelia:
    image: authelia/authelia:4.39.20
    container_name: authelia
    restart: unless-stopped
    user: '${PUID}:${PGID}'
    environment:
      TZ: ${TZ}
      AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE: /secrets/RESET_PASSWORD_JWT_SECRET
      AUTHELIA_SESSION_SECRET_FILE: /secrets/SESSION_SECRET
      AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE: /secrets/STORAGE_ENCRYPTION_KEY
      AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE: /secrets/SMTP_PASSWORD
    volumes:
      - ./config:/config:ro
      - ./data:/data
      - ./secrets:/secrets:ro
    networks:
      - proxy
    labels:
      - 'traefik.enable=true'
      - 'traefik.docker.network=proxy'
      - 'traefik.http.routers.authelia.rule=Host(`${AUTHELIA_HOST}`)'
      - 'traefik.http.routers.authelia.entrypoints=websecure'
      - 'traefik.http.routers.authelia.tls.certresolver=tls_resolver'
      - 'traefik.http.routers.authelia.middlewares=security-headers@file,crowdsec-bouncer@docker'
      - 'traefik.http.services.authelia.loadbalancer.server.port=9091'

      # Reusable ForwardAuth middleware. Do not add this middleware to
      # the Authelia portal router itself, or you will create a loop.
      - 'traefik.http.middlewares.authelia.forwardAuth.address=http://authelia:9091/api/authz/forward-auth'
      - 'traefik.http.middlewares.authelia.forwardAuth.trustForwardHeader=true'
      - 'traefik.http.middlewares.authelia.forwardAuth.maxResponseBodySize=8192'
      - 'traefik.http.middlewares.authelia.forwardAuth.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email'

networks:
  proxy:
    external: true

Validate the rendered Compose model before starting it:

cd /opt/containers/authelia
docker compose config --quiet
docker compose up -d
docker compose logs --tail=100 authelia

The container runs directly as the unprivileged UID/GID from .env; its entrypoint never needs to start as root. It also has no host port and no Docker socket. Traefik reaches it only through the shared proxy network.

8. Protect a Web Service

Add the authelia@docker middleware to an application’s Traefik router and add a matching Authelia access-control rule.

Example labels for protected.your-domain.com:

labels:
  - 'traefik.enable=true'
  - 'traefik.docker.network=proxy'
  - 'traefik.http.routers.protected.rule=Host(`protected.your-domain.com`)'
  - 'traefik.http.routers.protected.entrypoints=websecure'
  - 'traefik.http.routers.protected.tls.certresolver=tls_resolver'
  - 'traefik.http.routers.protected.middlewares=security-headers@file,crowdsec-bouncer@docker,authelia@docker'
  - 'traefik.http.services.protected.loadbalancer.server.port=8080'

The corresponding rule already exists in the sample configuration:

access_control:
  default_policy: 'deny'
  rules:
    - domain: 'protected.your-domain.com'
      policy: 'two_factor'

Restart Authelia after changing the configuration:

docker compose restart authelia
docker compose logs --tail=100 authelia

💡 KEEP AUTHORIZATION IN THE APPLICATION TOO
Authelia can decide who may reach a service, but the service should still enforce its own roles and permissions. Authentication proves identity; it does not automatically make every authenticated user an administrator.

9. Enroll and Test the Second Factor

Open https://protected.your-domain.com in a private browser window.
Sign in with the Authelia username and password.
Use the portal to register TOTP or a WebAuthn security key.
Confirm that the protected service is inaccessible without completing the second factor.
Test logout and a new private window; an existing remembered session is not a valid 2FA test.
Test the recovery email flow before depending on it.

TOTP is widely compatible. WebAuthn with a hardware security key or platform authenticator is generally more phishing-resistant. Register a second recovery-capable authenticator and store recovery material safely before removing any existing login route.

Useful diagnostics:

curl -fsS https://auth.your-domain.com/api/health
docker compose logs --tail=200 authelia
docker compose exec authelia authelia config validate --config /config/configuration.yml

10. Backups and Recovery

Back up these items together:

config/configuration.yml and config/users_database.yml;
the complete secrets/ directory;
data/db.sqlite3 using an application-consistent snapshot;
the pinned compose.yml and .env;
your SMTP and DNS recovery procedure.

An encrypted off-host backup is the real disaster-recovery copy. A second copy on the same filesystem does not protect against disk loss, ransomware, or a destructive administrative error.

⚠️ RESTORE AS A SET
The database and its storage encryption key belong together. Restoring only one side can leave TOTP registrations and other encrypted state unreadable. Test a restore into an isolated environment before you need it.

11. Safe Upgrades

Read the Authelia release notes and configuration changes.
Create a consistent, encrypted backup.
Change the image pin deliberately; do not switch production to latest.
Pull, validate, and recreate the service.
Test password login, the second factor, SMTP, ForwardAuth, and every OIDC client.

docker compose pull authelia
docker compose config --quiet
docker compose up -d
docker compose logs --tail=100 authelia

12. Extending Authelia with OIDC

ForwardAuth is only half of the design. Applications with native OIDC support should normally use it, because their browser and API flows remain application-aware.

The next guide applies this to an existing Matrix account without accidentally creating a second Matrix identity: Adding Authelia 2FA to Matrix Synapse with OpenID Connect.

Conclusion

You now have a compact central authentication service that can enforce TOTP or WebAuthn for browser applications and later serve native OIDC clients. The useful security boundary is not the login page alone: keep the Traefik routing, Authelia policy, application permissions, existing sessions, secrets, and backups aligned.

📚AUTHELIA DOCKER DOCUMENTATION 🔐TRAEFIK INTEGRATION 💬AUTHELIA + MATRIX GUIDE

Self-Hosting Tandoor Recipes with Docker Compose and Traefik

Unknown — Sun, 12 Jul 2026 00:00:00 +0000

Tandoor Recipes is a self-hosted recipe manager with meal planning, shopping lists, cookbooks, recipe imports, sharing, and a mobile-friendly Progressive Web App. It is designed for private households and small groups rather than as a public recipe website.

This guide deploys Tandoor in an existing Traefik v3 and CrowdSec Docker ecosystem. It stays close to Tandoor’s official Traefik Compose example: PostgreSQL runs as db_recipes, the application runs as web_recipes, static files use a Docker volume, and recipe images are stored in a bind-mounted mediafiles directory.

The only deliberate additions are version pinning, a PostgreSQL healthcheck, the existing proxy network, and the Traefik labels required by our stack.

ℹ️ TANDOOR 2 ARCHITECTURE
Tandoor 2 includes its own Nginx server and exposes container port `80`. Do not add the separate Nginx container found in older Tandoor 1 guides. Traefik connects directly to `web_recipes:80`.

Changelog

Date	Change
2026-07-12	Initial Version: Tandoor 2.6.9 with PostgreSQL 16, Traefik v3, CrowdSec, trusted-proxy configuration, and backups.

1. Architecture

The finished deployment has only one public path:

Internet
   |
   | HTTPS :443
   v
Traefik + CrowdSec
   |
   | Docker network: proxy
   v
web_recipes:80 (Tandoor + built-in Nginx)
   |
   | Private Compose network
   v
db_recipes:5432 (PostgreSQL 16)

PostgreSQL is not attached to the shared proxy network and publishes no host port. Tandoor also publishes no host port; only Traefik can reach it through Docker.

This guide pins:

Tandoor 2.6.9
PostgreSQL 16-alpine

Pinning Tandoor makes updates deliberate and prevents an unattended latest pull from applying irreversible database migrations. Tandoor explicitly warns that database downgrades are not supported.

2. Prerequisites

You need:

A working Traefik v3 and CrowdSec stack.
Docker and Docker Compose.
The external Docker network named proxy.
A DNS A and/or AAAA record for recipes.criticalbasics.xyz pointing to the server.
openssl for secret generation.
Root or sudo access.

Verify the shared network:

docker network inspect proxy >/dev/null

3. Directory Structure

Create a dedicated directory for the stack:

sudo mkdir -p /opt/containers/tandoor/{postgresql,mediafiles}
cd /opt/containers/tandoor

The resulting persistent layout is:

/opt/containers/tandoor/
├── .env
├── docker-compose.yml
├── mediafiles/       # Recipe images and uploaded files
└── postgresql/       # PostgreSQL 16 data directory

Static application assets live in the Docker volume tandoor_staticfiles. They are rebuilt by Tandoor during startup and do not contain user-created recipe data.

4. Generate Secrets

Generate two independent, shell-safe secrets:

TANDOOR_SECRET_KEY=$(openssl rand -hex 32)
POSTGRES_PASSWORD=$(openssl rand -hex 32)

echo "Tandoor secret:  $TANDOOR_SECRET_KEY"
echo "Database secret: $POSTGRES_PASSWORD"

The Django SECRET_KEY must be at least 50 characters and must remain stable for the lifetime of the instance. Save both values in a password manager before continuing.

5. Environment File

Create /opt/containers/tandoor/.env with restrictive permissions:

sudo install -m 0600 /dev/null .env
sudo nano .env

Use the following configuration and insert the secrets generated above:

# ---------------------------------------------------------------------------
# Required Tandoor settings
# ---------------------------------------------------------------------------
SECRET_KEY=REPLACE_WITH_TANDOOR_SECRET_KEY
TZ=Europe/Berlin
ALLOWED_HOSTS=recipes.criticalbasics.xyz
CSRF_TRUSTED_ORIGINS=https://recipes.criticalbasics.xyz

# Tandoor 2 includes its own nginx. Traefik is the second trusted proxy.
TANDOOR_PORT=80
ALLAUTH_TRUSTED_PROXY_COUNT=2
ENABLE_SIGNUP=0

# PostgreSQL
DB_ENGINE=django.db.backends.postgresql
POSTGRES_HOST=db_recipes
POSTGRES_DB=djangodb
POSTGRES_PORT=5432
POSTGRES_USER=djangouser
POSTGRES_PASSWORD=REPLACE_WITH_POSTGRES_PASSWORD

Why `ALLAUTH_TRUSTED_PROXY_COUNT=2`?

Tandoor applies IP-based rate limits to login, signup, and password-reset requests. The request passes through two proxies before reaching Django:

The external Traefik reverse proxy.
Tandoor’s built-in Nginx server.

The default value of 1 accounts only for the built-in Nginx server. Behind Traefik it can produce login failures or HTTP 403 responses because Tandoor selects the wrong address from X-Forwarded-For. Therefore this deployment must use 2.

⚠️ PROTECT THE ENVIRONMENT FILE
The `.env` file contains both the Django signing key and the database password. Keep it at mode `0600`, never commit it to Git, and include it in encrypted off-server backups.

6. Docker Compose

Create /opt/containers/tandoor/docker-compose.yml:

services:
  db_recipes:
    restart: always
    image: postgres:16-alpine
    volumes:
      - ./postgresql:/var/lib/postgresql/data
    env_file:
      - ./.env
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s
    networks:
      - default

  web_recipes:
    restart: always
    image: vabene1111/recipes:2.6.9
    env_file:
      - ./.env
    volumes:
      - staticfiles:/opt/recipes/staticfiles
      - ./mediafiles:/opt/recipes/mediafiles
    depends_on:
      db_recipes:
        condition: service_healthy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.tandoor.rule=Host(`recipes.criticalbasics.xyz`)"
      - "traefik.http.routers.tandoor.entrypoints=websecure"
      - "traefik.http.routers.tandoor.tls.certresolver=tls_resolver"
      - "traefik.http.routers.tandoor.middlewares=security-headers@file,crowdsec-bouncer@docker"
      - "traefik.http.services.tandoor.loadbalancer.server.port=80"
    networks:
      - default
      - proxy

networks:
  default:
  proxy:
    external: true

volumes:
  staticfiles:

This is intentionally close to the upstream Traefik Compose example. The important local adaptations are:

vabene1111/recipes:2.6.9 instead of an unpinned image.
A database healthcheck and health-based startup dependency.
proxy instead of the generic upstream Traefik network name.
The router, TLS resolver, security-header, and CrowdSec labels used by our existing stack.
No ports: section. Traefik reaches Tandoor directly over the Docker network.

Validate the merged configuration without printing the secrets:

sudo docker compose config --quiet

7. Launch the Stack

Pull the pinned images and start the stack:

cd /opt/containers/tandoor
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps

The expected services are:

tandoor-db_recipes-1     postgres:16-alpine         healthy
tandoor-web_recipes-1    vabene1111/recipes:2.6.9   running

Monitor the first startup:

sudo docker compose logs -f web_recipes

Tandoor waits for PostgreSQL, applies all Django migrations, collects static files, and finally starts Gunicorn. Exit the log view with CTRL+C after you see:

Database is ready
Migrating database
Collecting static files, this may take a while...
Done
Starting gunicorn

ℹ️ TEMPORARY 502 DURING FIRST STARTUP
Tandoor starts its internal Nginx before database migrations and Gunicorn are ready. Traefik may therefore return HTTP 502 for a short time during the first launch. This is expected. Do not delete the database or restart repeatedly; wait for the migration and static-file steps to finish.

8. Create the First User

Open:

https://recipes.criticalbasics.xyz/

When the database contains no users, Tandoor automatically redirects to /setup/. Create the first account there. This account becomes the instance superuser.

The setting ENABLE_SIGNUP=0 does not block this one-time setup page. After the first user exists, /setup/ can no longer create another account. Create additional household members from Tandoor’s space settings using invite links.

⚠️ CREATE THE FIRST ACCOUNT PROMPTLY
The initial setup form is publicly reachable until the first account exists. Create the superuser immediately after deployment and use a unique, strong password.

9. Verification

9.1. HTTPS and Redirects

Check the public route:

curl -I https://recipes.criticalbasics.xyz/
curl -I http://recipes.criticalbasics.xyz/

Before the first account is created, HTTPS should return 302 with location: /setup/. Plain HTTP should return a permanent redirect to HTTPS.

9.2. Security Headers

The HTTPS response should include headers such as:

strict-transport-security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
x-frame-options: DENY

These come from the shared security-headers@file Traefik middleware.

9.3. Database Health

cd /opt/containers/tandoor
sudo docker compose exec db_recipes \
  pg_isready -U djangouser -d djangodb

Expected output:

/var/run/postgresql:5432 - accepting connections

9.4. Confirm the Image Version

sudo docker compose images

Confirm that web_recipes uses vabene1111/recipes:2.6.9 and the database remains on PostgreSQL major version 16.

10. Optional Email Configuration

Tandoor works without SMTP, but password-reset emails require a mail server. Add the following variables to .env if needed:

EMAIL_HOST=mail.your-domain.com
EMAIL_PORT=587
EMAIL_HOST_USER=tandoor@your-domain.com
EMAIL_HOST_PASSWORD=REPLACE_WITH_MAILBOX_PASSWORD
EMAIL_USE_TLS=1
EMAIL_USE_SSL=0
DEFAULT_FROM_EMAIL="Tandoor Recipes <tandoor@your-domain.com>"

Recreate the application container after changing the environment:

sudo docker compose up -d --force-recreate web_recipes

Use either STARTTLS on port 587 or implicit TLS on port 465, never both EMAIL_USE_TLS=1 and EMAIL_USE_SSL=1.

11. Backups and Restore

Tandoor stores user data in two places:

PostgreSQL: recipes, users, meal plans, shopping lists, and settings.
mediafiles: recipe images and uploaded files.

The .env file must also be preserved because it contains the stable Django secret key and database credentials.

11.1. Create a Backup

cd /opt/containers/tandoor
sudo mkdir -p backups

# Logical PostgreSQL backup
sudo docker compose exec -T db_recipes \
  pg_dump -U djangouser -d djangodb -Fc \
  | sudo tee "backups/tandoor-db-$(date +%F).dump" > /dev/null

# Media, Compose file, and encrypted-secret source
sudo tar -czf backups/tandoor-files-$(date +%F).tar.gz \
  mediafiles docker-compose.yml .env

Copy the resulting files to encrypted off-server storage. A backup that only remains on the VPS is not sufficient.

11.2. Restore the Database

Stop the web application while keeping PostgreSQL running:

cd /opt/containers/tandoor
sudo docker compose stop web_recipes

sudo docker compose exec -T db_recipes \
  pg_restore -U djangouser -d djangodb \
  --clean --if-exists \
  < backups/tandoor-db-YYYY-MM-DD.dump

sudo docker compose start web_recipes

Restore the mediafiles directory from its matching archive before starting the web service. Always test the complete restore procedure before relying on a backup strategy.

12. Updating Tandoor

Read the Tandoor release notes before every update. Database migrations can move forward automatically, but Tandoor does not support automatic database downgrades.

Create and copy an off-server backup.
Change the pinned image tag in docker-compose.yml.
Pull and recreate the stack:

cd /opt/containers/tandoor
sudo docker compose down
sudo docker compose pull
sudo docker compose up -d
sudo docker compose logs -f web_recipes

Do not change the PostgreSQL major version as part of a routine Tandoor update. PostgreSQL data directories are not directly compatible across major versions; use a logical dump and restore for a major database upgrade.

13. Troubleshooting

HTTP 502 after deployment

Check whether migrations and static-file collection are still running:

sudo docker compose logs --tail=200 web_recipes

On first start, wait several minutes before treating a 502 response as an error.

HTTP 403 when logging in

Confirm this exact setting in .env:

ALLAUTH_TRUSTED_PROXY_COUNT=2

Then recreate the application container:

sudo docker compose up -d --force-recreate web_recipes

CSRF errors or incorrect redirects

Verify:

ALLOWED_HOSTS=recipes.criticalbasics.xyz
CSRF_TRUSTED_ORIGINS=https://recipes.criticalbasics.xyz

Also confirm that the Traefik router uses the same hostname and the websecure entrypoint.

Recipe images are missing

Verify the media mount and filesystem:

sudo docker compose exec web_recipes ls -ld /opt/recipes/mediafiles
sudo ls -ld /opt/containers/tandoor/mediafiles

Do not remove or replace the mediafiles directory during updates.

CrowdSec blocks a legitimate client

Inspect current decisions in the Traefik stack:

cd /opt/containers/traefik-stack
sudo docker compose exec crowdsec cscli decisions list

The normal deployment keeps CrowdSec enabled. Only remove crowdsec-bouncer@docker from the Tandoor router after confirming a persistent false positive and understanding the security tradeoff.

Conclusion

Tandoor Recipes is now running as a small, maintainable two-service stack. PostgreSQL and recipe media are persistent, the database remains private, and all public traffic passes through the existing Traefik TLS and CrowdSec security layer.

By staying close to the official Compose layout, future Tandoor documentation and release notes remain directly applicable, while version pinning, trusted-proxy configuration, tested backups, and explicit Traefik labels make the setup appropriate for a production VPS.

📚OFFICIAL TANDOOR DOCKER DOCS 📦TANDOOR RECIPES ON GITHUB

Essential Initial Setup for a Secure Debian Server

Unknown — Wed, 01 Jul 2026 00:00:00 +0000

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.

We will cover user management, hardening SSH access, configuring a firewall, setting up automatic intrusion prevention, and enabling automatic security updates.

ℹ️ FOLLOW THE ORDER
These steps are designed to be followed sequentially. For example, we will set up SSH key authentication before disabling password logins to ensure you don’t lock yourself out.

Changelog

Date	Change
2026-07-01	Added rsyslog/UFW logging notes and clarified Docker firewall caveats.
2026-03-03	Comprehensive update: hardened SSH config, added backup strategy, monitoring, and WireGuard.
2025-07-10	Initial version of the comprehensive Debian hardening guide.

First, log into your new server as the root user. Your cloud provider will have supplied you with the initial IP address and password.

The very first action should always be to update the package list and upgrade all installed packages. For a fresh server, we use full-upgrade to ensure even kernel updates and new dependencies are handled.

# Log in as root
ssh root@your_server_ip

# Update package lists
apt update

# Upgrade all installed packages (including kernel updates)
apt full-upgrade

# Reboot to ensure the new kernel and all updates are active
reboot

After the reboot, log back in. It’s best practice to set the hostname immediately so all subsequent logs reflect the correct name.

# Set your server's hostname
sudo hostnamectl set-hostname my-awesome-server

You should also edit /etc/hosts to associate the new hostname with 127.0.1.1.

Step 2: Create a Dedicated Admin User

Operating directly as the root user is risky. We will create a new user account with administrative privileges via the sudo command. This improves security and provides better auditing.

Replace adminuser with a username of your choice.

# Create a new user
adduser adminuser

# You will be prompted to set a password and fill in user information.

# Add the new user to the 'sudo' group
usermod -aG sudo adminuser

# Log out from the root session
exit

ℹ️ SUDO PASSWORD SECURITY
By default, `sudo` will ask for your user password before executing administrative commands. Do not configure `NOPASSWD` for your admin user. This password prompt prevents accidental destructive commands and is an additional authentication layer if your SSH session is compromised.

From now on, you will log in as this new user and prefix any administrative commands with sudo.

Step 3: Harden SSH Access

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.

3.1. Set Up SSH Key Authentication

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).

On your local computer (not the server): If you don’t have an SSH key pair yet, generate one. The ed25519 algorithm is modern and highly secure.

# This command is run on your local machine
ssh-keygen -t ed25519 -C "your_email@example.com"

Press Enter to accept the default file location and set an optional (but recommended) passphrase for your key.

Copy your public key to the server: The ssh-copy-id command is the easiest way to do this. It will automatically add your public key to the correct file on the server.

# Replace with your new username and server IP
ssh-copy-id adminuser@your_server_ip

After this, you should be able to log into your server as adminuser without being asked for a password (you might be asked for your key’s passphrase if you set one).

3.2. Configure and Secure the SSH Daemon

Now we will edit the main SSH configuration file to improve security.

⚠️ DO NOT CLOSE YOUR TERMINAL!
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.

Open the configuration file with a text editor:

sudo vim /etc/ssh/sshd_config

Make the following changes to harden the configuration:

# Change port (optional, reduces log noise from bots)
Port 8496

# Authentication
PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes
MaxAuthTries 3
LoginGraceTime 30

# Restrict to specific user(s)
AllowUsers adminuser

# Disable unnecessary features
X11Forwarding no
AllowTcpForwarding no
AllowAgentForwarding no

# Restrict key algorithms to modern, secure options
PubkeyAcceptedAlgorithms ssh-ed25519,sk-ssh-ed25519@openssh.com

Key explanations for these options:

MaxAuthTries 3 — Limits login attempts per connection to 3.
LoginGraceTime 30 — Disconnects after 30 seconds without successful authentication.
AllowUsers adminuser — Only the specified user(s) can log in via SSH.
X11Forwarding no — Disables GUI forwarding, reducing attack surface.
AllowTcp/AgentForwarding no — Prevents SSH tunneling and potential agent exploitation.
PubkeyAcceptedAlgorithms — Restricts to Ed25519 and FIDO2/Hardware keys (YubiKey).

Save the file and exit the editor.

3.3. Test and Restart SSH

⚠️ CRITICAL: TEST BEFORE RESTART
Always validate your configuration before restarting the SSH daemon. A syntax error can lead to a permanent lockout.

# ALWAYS test configuration before restarting
sudo sshd -t

# Only if no errors are shown, restart the service:
sudo systemctl restart sshd.service

Now, open a new terminal window and try to connect using the new port and your key.

# Use your username, IP, and the new port number
ssh adminuser@your_server_ip -p 8496

If the login is successful, your SSH hardening is complete. You can now safely close the old terminal window.

Step 4: Configure a Firewall with UFW

A firewall is essential for controlling network traffic. We will use UFW (Uncomplicated Firewall) because it is user-friendly and effective.

# Install UFW
sudo apt install ufw

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.

# Set default policies
sudo ufw default deny incoming
sudo ufw default allow outgoing

# Allow standard web traffic
sudo ufw allow http  # Port 80
sudo ufw allow https # Port 443

# IMPORTANT: Allow your new SSH port
# We use 'limit' to help protect against brute-force attacks
sudo ufw limit 8496/tcp # Use the port you chose

Now, enable the firewall. It will ask for confirmation to proceed.

sudo ufw enable

# Check the status of the firewall at any time
sudo ufw status verbose

💡 CLOUD FIREWALL
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.

⚠️ DOCKER AND UFW
Docker publishes ports by adding its own iptables/nftables rules. UFW is still useful, but it should not be treated as the only network boundary for a Docker host. Prefer publishing only the reverse proxy ports (`80` and `443`) and keep application containers on internal Docker networks unless a service truly needs direct host ports.

Step 5: Prevent Intrusion with Fail2Ban

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.

# Install Fail2Ban
sudo apt install fail2ban

Fail2Ban’s configuration should be done in a local file, which overrides the default settings without being changed during package updates.

# Create a local configuration file
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local

Now, edit the new local file to configure it for our custom SSH port.

sudo vim /etc/fail2ban/jail.local

Find the [sshd] section. Most settings can be left as default, but you must update the port to match your custom SSH port and ensure it’s enabled.

[sshd]
enabled  = true
port     = 8496
maxretry = 3
bantime  = 1h
findtime = 10m

Save the file and restart Fail2Ban to apply the changes.

sudo systemctl restart fail2ban

# Check the status of the SSH jail
sudo fail2ban-client status sshd

💡 VERSATILE PROTECTION
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.

Step 6: Automate Security Updates

Even with a hardened server, new vulnerabilities are discovered all the time. It is vital to install security updates promptly. The unattended-upgrades package can do this for you automatically.

# Install the package
sudo apt install unattended-upgrades apt-listchanges

Now, run the configuration wizard to enable it.

# This will open a simple text-based interface
sudo dpkg-reconfigure -plow unattended-upgrades

Select “Yes” to enable automatic updates. This will create a configuration file that tells the system to automatically install packages from Debian’s security repository.

To further harden this, you can configure email notifications and an automatic reboot policy (essential for kernel updates) in /etc/apt/apt.conf.d/50unattended-upgrades:

# Email notification (requires a working mail setup like msmtp)
Unattended-Upgrade::Mail "your@email.com";

# Automatic reboot policy (e.g., at 04:00 AM)
Unattended-Upgrade::Automatic-Reboot "true";
Unattended-Upgrade::Automatic-Reboot-Time "04:00";

Step 7: Final System Housekeeping

A few final touches will make your server easier to manage.

1. Set the Timezone: Correct log timestamps are crucial for troubleshooting.

# Set your timezone, e.g., for Berlin
sudo timedatectl set-timezone Europe/Berlin

2. Install Useful Tools: These small utilities are incredibly helpful for administration.

sudo apt install htop ncdu curl git

htop: An interactive process viewer.
ncdu: A disk usage analyzer to easily find large files.
curl: A tool for transferring data with URLs.
git: Version control system, often needed to download software.

Step 8: Basic Monitoring and Logging

A secure server is one where you notice when something goes wrong.

8.1. Persistent Journal Logging

On some Debian installations, journal logs are lost upon reboot. This makes them persistent:

sudo mkdir -p /var/log/journal
sudo systemd-tmpfiles --create --prefix /var/log/journal
sudo systemctl restart systemd-journald

8.2. UFW Logs with rsyslog (Optional)

If you want UFW messages in /var/log/ufw.log instead of relying only on the journal, install rsyslog before adding rsyslog snippets.

sudo apt install rsyslog

Example filter:

sudo tee /etc/rsyslog.d/20-ufw.conf > /dev/null << 'EOF'
:msg,contains,"[UFW " /var/log/ufw.log
& stop
EOF

Validate and restart:

sudo rsyslogd -N1
sudo systemctl restart rsyslog

Without the rsyslog package, this configuration file will simply never be processed.

8.3. Logwatch (Optional)

Logwatch provides a daily summary of SSH attempts, disk usage, and service errors.

sudo apt install logwatch
sudo logwatch --detail Med --range yesterday --output stdout

8.4. Monitoring Disk Space

Full disks are a common cause of service failures.

df -h
sudo ncdu /

Step 9: Backup Strategy

Security = Prevent + Detect + Recover. A server without a backup is not truly secure.

Core Principles

Provider Snapshots: Enable them as your first layer of defense.
Application-Level Backups: Use tools like borgbackup or restic.
3-2-1 Rule: 3 copies, 2 different media, 1 offsite.
Test Restores: A backup is only as good as its last successful restore.

Example with BorgBackup:

sudo apt install borgbackup
borg init --encryption=repokey /path/to/backup/repo

# Note: Adjust paths like /var/lib depending on your data volume (e.g., Docker volumes, databases).
borg create /path/to/backup/repo::$(date +%Y-%m-%d) /etc /home /var/lib

# Verify your backup
borg list /path/to/backup/repo

Step 10 (Optional): Maximum Security — SSH via WireGuard

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.

10.1. Setup WireGuard Server

sudo apt install wireguard

# Create directory with restricted permissions first
umask 077
wg genkey | tee /etc/wireguard/server_private.key | wg pubkey > /etc/wireguard/server_public.key

(Note: The tee command outputs the private key to your terminal. Do not share this output.)

10.2. Server Configuration

Create /etc/wireguard/wg0.conf:

[Interface]
Address = 10.0.0.1/24
ListenPort = 51820
PrivateKey = <contents of server_private.key>

[Peer]
PublicKey = <client_public_key>
AllowedIPs = 10.0.0.2/32

Enable the service:

sudo systemctl enable wg-quick@wg0
sudo systemctl start wg-quick@wg0

10.3. Restrict SSH to VPN

In /etc/ssh/sshd_config, set:

ListenAddress 10.0.0.1

Test and restart:

sudo sshd -t
sudo systemctl restart sshd.service

10.4. Update Firewall

sudo ufw allow 51820/udp
sudo ufw delete limit 8496/tcp

⚠️ WARNING
After this change, SSH is ONLY reachable via WireGuard. Ensure your VPN connection works before closing your session.

10.5. Client Configuration

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:

# /etc/wireguard/wg0.conf on client
[Interface]
Address = 10.0.0.2/24
PrivateKey = <client_private_key>

[Peer]
PublicKey = <server_public_key>
Endpoint = your_server_ip:51820
AllowedIPs = 10.0.0.1/32

Conclusion

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.

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.

ℹ️ WHAT'S NEXT?
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.

📚OFFICIAL DEBIAN SECURITY MANUAL 🛡️DEBIAN WIKI: FAIL2BAN

Deploying Forgejo with Traefik and Docker Compose

Unknown — Wed, 01 Jul 2026 00:00:00 +0000

Forgejo is a lightweight self-hosted Git forge with repositories, issues, pull requests, releases, packages, and optional Actions-compatible CI. It is a good fit when GitLab is too heavy but a plain Git server is not enough.

This guide installs Forgejo in an existing Traefik v3 and CrowdSec Docker ecosystem. Forgejo runs as a rootless Docker container, PostgreSQL stores the application database, Traefik handles HTTPS, and Forgejo’s built-in SSH server exposes Git over a dedicated host port.

ℹ️ FRESH INSTALL FIRST
The main path below is a clean Forgejo installation. GitHub import, container registry usage, and Forgejo Runner are covered as optional sections after the base instance is working.

Changelog

Date	Change
2026-07-01	Initial Version: Fresh Forgejo install with PostgreSQL, rootless Docker, Traefik labels, SSH, registry, and backups.

1. Architecture

The target architecture looks like this:

Internet
  |
  | 443/tcp
  v
Traefik -> Forgejo web UI/API/registry on port 3000

Internet
  |
  | 2222/tcp
  v
Forgejo built-in SSH server for Git

Forgejo -> PostgreSQL on a private Docker network

This setup deliberately starts without a runner. CI jobs can execute arbitrary project code, so it is better to enable the runner only after the Git service itself is stable.

2. Prerequisites

You need:

A working Traefik v3 and CrowdSec stack.
Docker and Docker Compose.
An external Docker network named proxy.
A subdomain such as forgejo.your-domain.com.
DNS A/AAAA records pointing the subdomain to your server.
Open firewall ports 80/tcp, 443/tcp, and one Git SSH port, e.g. 2222/tcp.

This guide uses:

Forgejo 15.0.3-rootless
PostgreSQL 16-alpine
Traefik TLS resolver named tls_resolver

Check the Forgejo Docker installation docs before changing major versions. Upgrading from one major Forgejo version to the next should be done deliberately, not through latest.

3. Directory Structure

sudo mkdir -p /opt/containers/forgejo
cd /opt/containers/forgejo

sudo mkdir -p data config postgres
sudo chown -R 1000:1000 data config

The rootless Forgejo container runs as UID/GID 1000:1000. Adjust this if your Docker host uses a different unprivileged user.

4. Environment File

Create /opt/containers/forgejo/.env:

sudo install -m 0600 /dev/null .env
sudo nano .env

Example:

TZ=Europe/Berlin
FORGEJO_DOMAIN=forgejo.your-domain.com
FORGEJO_DB_PASSWORD=REPLACE_WITH_LONG_RANDOM_VALUE
FORGEJO_SECRET_KEY=REPLACE_WITH_LONG_RANDOM_VALUE
FORGEJO_INTERNAL_TOKEN=REPLACE_WITH_LONG_RANDOM_VALUE
FORGEJO_JWT_SECRET=REPLACE_WITH_LONG_RANDOM_VALUE

Generate secrets with:

openssl rand -hex 32
openssl rand -hex 64

5. Docker Compose

Create /opt/containers/forgejo/docker-compose.yml:

services:
  forgejo-db:
    image: docker.io/postgres:16-alpine
    container_name: forgejo-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: forgejo
      POSTGRES_USER: forgejo
      POSTGRES_PASSWORD: ${FORGEJO_DB_PASSWORD}
    volumes:
      - ./postgres:/var/lib/postgresql/data
    networks:
      - forgejo-internal
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U forgejo -d forgejo"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  forgejo:
    image: codeberg.org/forgejo/forgejo:15.0.3-rootless
    container_name: forgejo
    user: "1000:1000"
    restart: unless-stopped
    depends_on:
      forgejo-db:
        condition: service_healthy
    environment:
      USER_UID: 1000
      USER_GID: 1000
      FORGEJO____APP_NAME: "My Forgejo"
      FORGEJO__database__DB_TYPE: postgres
      FORGEJO__database__HOST: forgejo-db:5432
      FORGEJO__database__NAME: forgejo
      FORGEJO__database__USER: forgejo
      FORGEJO__database__PASSWD: ${FORGEJO_DB_PASSWORD}
      FORGEJO__database__SSL_MODE: disable
      FORGEJO__security__INSTALL_LOCK: "true"
      FORGEJO__security__SECRET_KEY: ${FORGEJO_SECRET_KEY}
      FORGEJO__security__INTERNAL_TOKEN: ${FORGEJO_INTERNAL_TOKEN}
      FORGEJO__oauth2__JWT_SECRET: ${FORGEJO_JWT_SECRET}
      FORGEJO__server__DOMAIN: ${FORGEJO_DOMAIN}
      FORGEJO__server__ROOT_URL: https://${FORGEJO_DOMAIN}/
      FORGEJO__server__HTTP_ADDR: 0.0.0.0
      FORGEJO__server__HTTP_PORT: 3000
      FORGEJO__server__PROTOCOL: http
      FORGEJO__server__START_SSH_SERVER: "true"
      FORGEJO__server__SSH_DOMAIN: ${FORGEJO_DOMAIN}
      FORGEJO__server__SSH_PORT: 2222
      FORGEJO__server__SSH_LISTEN_PORT: 2222
      FORGEJO__server__LFS_START_SERVER: "true"
      FORGEJO__repository__DEFAULT_PRIVATE: private
      FORGEJO__service__DISABLE_REGISTRATION: "true"
      FORGEJO__service__REQUIRE_SIGNIN_VIEW: "true"
      FORGEJO__openid__ENABLE_OPENID_SIGNIN: "false"
      FORGEJO__openid__ENABLE_OPENID_SIGNUP: "false"
      FORGEJO__packages__ENABLED: "true"
      FORGEJO__actions__ENABLED: "false"
      TZ: ${TZ}
    volumes:
      - ./data:/var/lib/gitea
      - ./config:/etc/gitea
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "2222:2222"
    networks:
      - proxy
      - forgejo-internal
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.forgejo.rule=Host(`forgejo.your-domain.com`)"
      - "traefik.http.routers.forgejo.entrypoints=websecure"
      - "traefik.http.routers.forgejo.tls.certresolver=tls_resolver"
      - "traefik.http.routers.forgejo.middlewares=security-headers@file,crowdsec-bouncer@docker"
      - "traefik.http.services.forgejo.loadbalancer.server.port=3000"

networks:
  proxy:
    external: true
  forgejo-internal:
    external: false

Open the Git SSH port on the host:

sudo ufw allow 2222/tcp comment 'Forgejo SSH'

Start Forgejo:

docker compose pull
docker compose up -d
docker compose logs -f forgejo

6. Create the Admin User

With the rootless container image, the generated app.ini usually lives at:

/var/lib/gitea/custom/conf/app.ini

Create the first admin user:

docker compose exec -T forgejo \
  forgejo --config /var/lib/gitea/custom/conf/app.ini \
  --work-path /var/lib/gitea \
  admin user create \
  --username youradmin \
  --password 'REPLACE_WITH_TEMPORARY_PASSWORD' \
  --email you@your-domain.com \
  --admin \
  --must-change-password=false

https://forgejo.your-domain.com/

Then add your SSH public key under:

Settings -> SSH / GPG Keys

Test SSH:

ssh -T -p 2222 git@forgejo.your-domain.com

7. Optional: Mail via Mox

Forgejo works without mail, but password resets and notifications require SMTP. If you run Mox, create a dedicated mailbox such as forgejo@your-domain.com, then add:

      FORGEJO__mailer__ENABLED: "true"
      FORGEJO__mailer__PROTOCOL: smtp+starttls
      FORGEJO__mailer__SMTP_ADDR: mail.your-domain.com
      FORGEJO__mailer__SMTP_PORT: 587
      FORGEJO__mailer__USER: forgejo@your-domain.com
      FORGEJO__mailer__PASSWD: "REPLACE_WITH_MAILBOX_PASSWORD"
      FORGEJO__mailer__FROM: "Forgejo <forgejo@your-domain.com>"

Restart Forgejo after changing mail settings:

docker compose up -d

8. Container Registry

Forgejo includes a Docker/OCI-compatible container registry. With the setup above, the registry uses the same hostname as the web UI:

docker login forgejo.your-domain.com
docker build -t forgejo.your-domain.com/youruser/myapp:v1.0.0 .
docker push forgejo.your-domain.com/youruser/myapp:v1.0.0

For production, prefer immutable tags:

v1.2.0
main-a1b2c3d
2026-07-01-a1b2c3d

Using only latest makes rollbacks and audits harder.

9. Optional: Import or Mirror GitHub Repositories

For a simple source-code backup, mirror the Git repository first. Do not start by copying thousands of old container images or CI artifacts.

git clone --mirror https://github.com/ORG/REPO.git
cd REPO.git
git push --mirror https://forgejo.your-domain.com/ORG/REPO.git

For private GitHub repositories, use the GitHub CLI locally:

gh auth login
gh auth refresh -h github.com -s repo -s read:org
git clone --mirror https://github.com/ORG/REPO.git

If you want to avoid importing GitHub-specific pull request refs as hundreds of Forgejo branches, push only normal branches and tags:

git push https://forgejo.your-domain.com/ORG/REPO.git '+refs/heads/*:refs/heads/*'
git push https://forgejo.your-domain.com/ORG/REPO.git '+refs/tags/*:refs/tags/*'

GitHub Actions caches are rebuildable. Old Playwright reports and expired artifacts are usually safe to delete once they are no longer needed for debugging. Container package versions should be reduced to release tags and a small number of recent main builds; stale untagged image versions should not be mirrored blindly into your new registry.

10. Optional: Forgejo Runner

Forgejo Actions can be enabled later. The conservative path is:

Keep Forgejo itself on the production VPS.
Add a runner only when you know which workflows you need.
Avoid running untrusted CI jobs on the same host as production data.
If you start on the same VPS, keep it as a temporary convenience and move the runner to a separate build host later.

The risky part is Docker access from CI jobs. Mounting /var/run/docker.sock gives jobs effective host-root power. If you need container builds, prefer a dedicated runner host or a rootless build tool such as BuildKit, Buildah, or Kaniko.

11. Backups

Back up at least:

/opt/containers/forgejo/docker-compose.yml
/opt/containers/forgejo/.env
/opt/containers/forgejo/data
/opt/containers/forgejo/config
/opt/containers/forgejo/postgres

A simple dump:

cd /opt/containers/forgejo

docker compose exec -T forgejo-db \
  pg_dump -U forgejo forgejo > forgejo-db.sql

tar -czf forgejo-data-backup.tar.gz data config forgejo-db.sql

Store backups off-server and test restores before relying on them.

12. Updates

For patch updates within the same major version:

cd /opt/containers/forgejo
docker compose pull
docker compose up -d
docker compose logs -f forgejo

For major upgrades, read the Forgejo release notes first. Do not jump major versions unattended, and do not use latest in production.

Deploying a Matrix Synapse Server with Docker and Traefik

Unknown — Wed, 01 Jul 2026 00:00:00 +0000

This guide will walk you through deploying a powerful, federated Matrix Synapse homeserver. We will use the popular matrix-docker-ansible-deploy playbook, which simplifies the setup of Synapse and its various components, including bridges for other chat platforms.

This setup is designed to integrate seamlessly with an existing Traefik v3 reverse proxy and a root-domain Nginx web server, making it a perfect addition to a modern, container-based infrastructure.

Changelog

Date	Change
2026-07-17	Authentication Guide: Linked the safe Authelia OIDC and 2FA migration for existing Synapse accounts.
2026-07-01	Migration Notes: Added homeserver identity, bridge-state, MatrixRTC discovery, and media-retention guidance.
2026-06-12	Playbook Compatibility: Refreshed the guide for current Ketesa, Telegram bridgev2, migration validation, Docker collection requirements, and a safer baseline without Matrix RTC.
2026-02-20	Configuration Update: Updated `matrix_coturn_enabled` to `coturn_enabled`, removed Sliding Sync, and added PostgreSQL upgrade instructions.
2025-09-17	Initial Version: Guide created, focusing on Traefik v3 integration, Ansible deployment, and enabling various bridges and features like Sliding Sync.

1. Prerequisites

Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack: This is the foundation for our reverse proxy and security.
Deploying a Secure Nginx Website with Traefik and Docker Compose: This step is crucial as it establishes a web server on your root domain and correctly configures the .well-known/matrix delegation required for federation.

⚠️ HARD REQUIREMENT
`The following steps will not work correctly without the Traefik and Nginx stacks running as described in the prerequisite guides.`

ℹ️ ROOT DOMAIN REMAINS FREE FOR YOUR WEBSITE
Synapse runs on a dedicated subdomain (e.g., `matrix.your-domain.com`). The root domain (e.g., `your-domain.com`) continues to serve your main website via Nginx. The `.well-known` files on the root domain merely delegate clients and federation to the subdomain, so your homepage remains unaffected.

Architecture (simplified)

  Users / Browsers / Homeservers
             │
             ▼
      your-domain.com  ──>  [Nginx](../nginx-webserver/) on root domain
             │                 │
             │                 ├─ Serves your website (/, /assets, ...)
             │                 └─ Serves .well-known/matrix/{server,client}
             │                                  │
             │                                  ▼
             └────────────────────────── delegates to ──> matrix.your-domain.com
                                                       (Synapse via Traefik)
                                                            │
                                                            ▼
                                               Traefik (websecure, synapse)
                                                            │
                                                            ▼
                                                        Synapse

You will also need:

git, jq, and pwgen for version control, JSON parsing, and password generation.
Python 3 and pip installed on your server.
sudo or root access.

Install the required tools:

sudo apt update && sudo apt -y install git jq pwgen python3-pip python3-venv make

2. Directory Structure

First, we’ll create a dedicated directory for the Matrix playbook configuration and files.

sudo mkdir -p /opt/containers/matrix

3. Download the Ansible Playbook

Next, clone the official matrix-docker-ansible-deploy repository from GitHub into the directory you just created.

sudo git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git /opt/containers/matrix

4. Initial Configuration

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 vars.yml file.

ℹ️ HOSTNAME CONVENTION
The playbook expects the server to be available at `matrix.your-domain.com`. The configuration directory must match this hostname.

cd /opt/containers/matrix

# Replace 'matrix.your-domain.com' with your actual server name
sudo mkdir -p inventory/host_vars/matrix.your-domain.com
sudo cp examples/vars.yml inventory/host_vars/matrix.your-domain.com/

4.1. Generate Secret Keys

The configuration requires two strong secret keys. You can generate these using pwgen or openssl.

# Generate two strong keys and save them for the next step
pwgen -s 64 1
pwgen -s 64 1

4.2. Customize `vars.yml`

Now, open the vars.yml file and customize it for your environment. This is the most critical step.

sudo nano inventory/host_vars/matrix.your-domain.com/vars.yml

Below is a complete configuration based on a feature-rich setup. Adjust the values to match your domain, secrets, and desired features.

# Acknowledge the playbook breaking changes reviewed for this guide.
matrix_playbook_migration_validated_version: v2026.05.18.0

# The bare domain name which represents your Matrix identity.
matrix_domain: your-domain.com
matrix_homeserver_implementation: synapse
matrix_homeserver_generic_secret_key: 'PASTE-YOUR-GENERIC-SECRET-KEY-HERE'

# Use our own Traefik (externally managed)
matrix_playbook_reverse_proxy_type: other-traefik-container
traefik_certs_dumper_enabled: false

postgres_connection_password: 'PASTE-YOUR-POSTGRES-PASSWORD-HERE'
devture_systemd_docker_base_docker_service_name: "docker"
matrix_playbook_docker_installation_enabled: false

# We delegate .well-known from the root domain via Nginx
matrix_static_files_enabled: false
matrix_static_files_container_labels_traefik_enabled: false

coturn_enabled: false

# Traefik integration
matrix_playbook_reverse_proxy_container_network: proxy
matrix_playbook_reverse_proxy_hostname: traefik
traefik_entrypoint_primary: websecure
traefik_certResolver_primary: tls_resolver
matrix_federation_traefik_entrypoint_name: synapse

# --- Core services ---
matrix_synapse_container_labels_traefik_docker_network: proxy

matrix_client_element_container_labels_traefik_docker_network: proxy
matrix_client_element_hostname: "{{ matrix_server_fqn_matrix }}"
matrix_client_element_path_prefix: /element

matrix_admin: '@your-username:your-domain.com'

matrix_ketesa_enabled: true
matrix_ketesa_container_http_host_bind_port: ""
matrix_ketesa_container_labels_traefik_docker_network: proxy

# E-Mail relay (optional)
exim_relay_sender_address: "matrix@your-domain.com"
exim_relay_relay_use: true
exim_relay_relay_host_name: "mail.your-domain.com"
exim_relay_relay_host_port: 587
exim_relay_relay_auth: true
exim_relay_relay_auth_username: "user@your-domain.com"
exim_relay_relay_auth_password: "YOUR-EMAIL-PASSWORD"

matrix_appservice_double_puppet_enabled: true

# --- Bridges ---
# The playbook can install and configure various bridges to connect your Matrix homeserver
# to other chat networks like Telegram, Discord, Signal, etc. When enabling a bridge,
# it is crucial to provide the `homeserver` configuration block to ensure it communicates
# correctly with Synapse via Traefik. For more details on available bridges and their
# specific configurations, refer to the official documentation.

# Telegram – Correct EntryPoints + specify Homeserver
matrix_mautrix_telegram_enabled: true
matrix_mautrix_telegram_api_id: 12345678
matrix_mautrix_telegram_api_hash: 'your_telegram_api_hash'
matrix_mautrix_telegram_configuration_extension_yaml: |
  homeserver:
    address: "https://matrix.your-domain.com"
    domain: "your-domain.com"
  bridge:
    permissions:
      '{{ matrix_admin }}': admin

# Meta Messenger
matrix_mautrix_meta_messenger_enabled: true
matrix_mautrix_meta_messenger_configuration_extension_yaml: |
  homeserver:
    address: "https://matrix.your-domain.com"
    domain: "your-domain.com"
  bridge:
    permissions:
      '*': relay
      'your-domain.com': admin
      '{{ matrix_admin }}': admin

# Discord – Correct Avatar-Proxy & general EntryPoints
matrix_mautrix_discord_enabled: true
matrix_mautrix_discord_configuration_extension_yaml: |
  homeserver:
    address: "https://matrix.your-domain.com"
    domain: "your-domain.com"

ℹ️ TRAEFIK MIDDLEWARES
The playbook generates Traefik router labels for each Matrix component. Do not add custom middleware variables such as `_container_labels_traefik_middlewares`; current roles do not use them. If you want to apply `security-headers@file` or `crowdsec-bouncer@docker` to Matrix routes, do it via the role-specific `_container_labels_additional_labels` variables after checking the generated router names, or enforce the middleware in your Traefik stack.

ℹ️ ELEMENT CALL / MATRIX RTC
Element Call and the Matrix RTC stack are deliberately not enabled in the baseline configuration above. They need additional firewall ports (`7881/tcp`, `7882/udp`, `3479/udp`, `5350/tcp`, and `30000-30020/udp`) and, when using an externally managed Traefik container, explicit TURN/TLS handling. Add them only after the core homeserver is working.

5. Install Ansible and Dependencies

This playbook uses Ansible to automate the setup. Choose the installation method that fits your distribution policy.

For Debian 12 (system pip with –break-system-packages)

# Ensure pip is available
sudo apt install -y python3-pip

# Install Ansible and required Python packages system-wide
sudo pip3 install --break-system-packages ansible docker passlib

For Other Linux Distributions (recommended: Python virtual environment)

# Create and activate a dedicated virtual environment
python3 -m venv ~/.venvs/matrix-ansible
source ~/.venvs/matrix-ansible/bin/activate

# Upgrade pip and install required packages in the venv
pip install --upgrade pip
pip install ansible docker passlib

ℹ️ VIRTUALENV REMINDER
If you use the virtual environment, remember to reactivate it in new shell sessions with: `source ~/.venvs/matrix-ansible/bin/activate`

ℹ️ USE ONE ANSIBLE ENVIRONMENT
Run `ansible-galaxy`, `ansible-doc`, and `ansible-playbook` with the same Ansible installation. The commands below use `sudo` because this guide creates `/opt/containers/matrix` as a root-owned checkout and runs the playbook with `sudo`. If you use a user-owned checkout or a virtual environment, omit `sudo` consistently for the Ansible commands.

Next, install the Ansible roles required by the playbook:

cd /opt/containers/matrix
sudo make roles

Install the Docker collection used by several playbook roles:

sudo ansible-galaxy collection install community.docker --upgrade

You can verify that Ansible can resolve the Docker image module:

sudo ansible-doc community.docker.docker_image_pull

6. Configure Ansible Hosts

Now, we need to tell Ansible which server to configure. Since we are running it locally, the setup is simple.

# Copy the example hosts file
sudo cp examples/hosts inventory/hosts

# Edit the file
sudo nano inventory/hosts

Modify the file to look like this. The ansible_connection=local 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, ansible_host=127.0.0.1 (localhost) is the correct value. Parameters like ansible_ssh_user=root are ignored in this mode, as the playbook runs with the permissions of the user executing it (in our case, root via sudo).

[matrix_servers]
matrix.your-domain.com ansible_host=127.0.0.1 ansible_connection=local

7. Adjust Traefik for Federation

For Matrix federation to work, other servers need to connect to yours on port 8448. We must expose this port in our main Traefik stack and create a dedicated entrypoint for it.

Go to your Traefik stack’s directory (e.g., /opt/containers/traefik-stack).

7.1. Expose Federation Port

Edit your main docker-compose.yml:

sudo nano docker-compose.yml

Add port 8448 to the ports section of the traefik service:

services:
  traefik:
    # ... other settings
    ports:
      - "80:80"
      - "443:443"
      - "8448:8448" # Add this line for Matrix federation
    # ... rest of the settings

7.2. Create Federation and Internal Entrypoints

Edit your static Traefik configuration (traefik/config/traefik.yml):

sudo nano traefik/config/traefik.yml

Add a new synapse entrypoint for federation and a matrix-internal-matrix-client-api entrypoint for internal communication.

For recent playbook versions, it is recommended to also define the internal matrix-internal-matrix-client-api entrypoint on port 8008. This port is not published to the host and serves as an internal C2S route for bridges and add-ons, preventing errors in the Traefik dashboard.

entryPoints:
  web:
    address: ":80"
    # ...
  websecure:
    address: ":443"
  synapse: # For federation
    address: ":8448"
  matrix-internal-matrix-client-api: # For internal C2S communication
    address: ":8008"

7.3. Restart Traefik

Apply the changes by restarting your Traefik stack:

cd /opt/containers/traefik-stack
docker compose up -d

8. Run the Matrix Installation

With all the configuration in place, we can now run the Ansible playbook to set up and install everything.

cd /opt/containers/matrix
sudo ansible-playbook -i inventory/hosts setup.yml --tags=install-all

This command will download all necessary Docker images, generate configuration files, and prepare the services. It may take several minutes. The install-all tag is the recommended path for a new server when you are not importing old Matrix data.

9. Start the Matrix Services

Once the setup is complete, start all the Matrix containers:

sudo ansible-playbook -i inventory/hosts setup.yml --tags=ensure-matrix-users-created,start

After a few moments, all the services you enabled should be running. The ensure-matrix-users-created tag creates the internal service users required by bots and bridges. You can verify the running containers with docker ps.

10. Verify the Installation

After starting the services, it’s crucial to verify that all components are running and communicating correctly.

10.1. Check Running Containers

First, ensure all enabled services are running. The exact names will vary based on your matrix_domain.

docker ps --format '{{.Names}}' | grep -E 'synapse|element|ketesa|mautrix'

10.2. Verify `.well-known` Delegation (CLI)

Check if your Nginx server is correctly serving the delegation files for your root domain.

# Replace 'your-domain.com' with your actual domain
curl -s https://your-domain.com/.well-known/matrix/server | jq
curl -s https://your-domain.com/.well-known/matrix/client | jq

For this guide, the expected federation delegation uses port 8448:

{
  "m.server": "matrix.your-domain.com:8448"
}

The client delegation should point clients to the Matrix HTTPS endpoint:

{
  "m.homeserver": {
    "base_url": "https://matrix.your-domain.com"
  }
}

10.3. Verify Federation Endpoint (CLI)

Test if the Synapse federation port (8448) is correctly exposed through Traefik.

# Replace 'matrix.your-domain.com' with your actual matrix subdomain
curl -sS https://matrix.your-domain.com:8448/_matrix/federation/v1/version | jq

This should return a JSON object with server information, confirming the federation endpoint is reachable.

10.4. Verify CrowdSec Bouncer Registration

Check if the CrowdSec bouncer for Traefik has successfully registered with the CrowdSec agent.

cd /opt/containers/traefik-stack
docker compose exec crowdsec cscli bouncers list

You should see the Traefik bouncer in the list with a valid status.

10.5. Web-based Federation Test

Finally, use the official Federation Tester for a comprehensive check.

Go to: https://federationtester.matrix.org/
Enter your server name (e.g., your-domain.com) and run the test.

If everything is configured correctly, you should see a success message.

11. Create Your First User

Use the playbook to register your administrator user.

⚠️ PASSWORD SECURITY
To avoid leaving your password in your shell’s history, omit the `-e 'password=...'` part. The playbook will then prompt you to enter the password securely. `... -e 'username=your-username' -e 'admin=yes'`

cd /opt/containers/matrix
sudo ansible-playbook -i inventory/hosts setup.yml --tags=register-user -e 'username=your-username' -e 'admin=yes'

You can re-run this command with admin=no to create non-admin users.

12. Log In with Element

Your homeserver is now ready! You can access the Element web client by navigating to https://matrix.your-domain.com/element.

Click “Sign In”.
Your homeserver should be pre-filled. If not, edit it to show your server’s address (matrix.your-domain.com).
Log in with the username and password you just created.

13. Accessing the Ketesa Admin UI

Because we set matrix_ketesa_enabled: true in our vars.yml configuration, a powerful web-based administration interface for Synapse is automatically deployed.

You can access it at: https://matrix.your-domain.com/synapse-admin

By default, the playbook exposes Ketesa at the /synapse-admin path. If you prefer a Ketesa-branded path, add matrix_ketesa_path_prefix: /ketesa to vars.yml and use https://matrix.your-domain.com/ketesa instead.

Manage users (deactivate, make admin, etc.).
View server statistics and metrics.
Explore rooms and manage their settings.

This interface is the primary tool for the day-to-day administration of your homeserver.

14. Maintenance

Routine Updates

To update your Matrix server and its components to the latest version:

cd /opt/containers/matrix

# Pull the latest changes from the git repository.
sudo git pull

# Update the playbook roles.
sudo make roles

# Keep Ansible collections current.
sudo ansible-galaxy collection install community.docker --upgrade

# It's a good practice to review the CHANGELOG.md for breaking changes.
# sudo nano CHANGELOG.md

# Re-run the install and start tags to apply updates.
sudo ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start

If you removed components from vars.yml, run a full setup instead so the playbook can uninstall disabled services:

sudo ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start

Migration: Preserve Homeserver Identity

For a fresh homeserver, the normal installation flow above is enough. For a server migration where existing users should keep the same Matrix ID, clients should remain logged in, and bridges should continue to work, copying only vars.yml is not enough.

Preserve at least:

The Synapse database.
The Synapse signing key.
Appservice registration files and tokens.
Bridge configuration and bridge databases/state.
The same matrix_domain and public .well-known delegation.
Media that you still care about, especially local profile and room avatars.

⚠️ DO NOT RUN BRIDGES TWICE
When migrating bridge-heavy setups, stop the old bridge services before starting the new ones. Running the same Signal, Telegram, Discord, Instagram, Messenger, or LinkedIn bridge state on two servers at the same time can cause external-service conflicts and duplicate sessions.

If historical Matrix media is not important, you can keep the migration lightweight by skipping most remote media. Do not forget that avatars are also media. A useful compromise is:

Keep local media required for account and room avatars.
Allow old remote cached media to be refetched when possible.
Enable remote media retention so cached remote media does not grow forever.

In Synapse’s media retention config, the intended policy looks like:

media_retention:
  local_media_lifetime: null
  remote_media_lifetime: 14d

This keeps local uploads while allowing Synapse to purge remote cached media that has not been accessed recently.

Upgrade Notes for Existing Installations

Fresh installations using the configuration above can skip this subsection. These notes are for servers that were originally deployed with older versions of the playbook.

Playbook migration validation

Older installations can be blocked by the playbook’s migration validation gate:

Your validated migration version (v2026.03.23.0) is behind the expected version (v2026.05.18.0).

This is an intentional safety check. Review the relevant playbook changelog entries first, then raise the validated version in your host-specific vars.yml:

matrix_playbook_migration_validated_version: "v2026.05.18.0"

The file usually lives at:

inventory/host_vars/matrix.your-domain.com/vars.yml

Ketesa configuration for older Synapse Admin setups

The bundled administration UI is now configured with matrix_ketesa_* variables. Existing configurations that still contain matrix_synapse_admin_* variables should be updated:

matrix_ketesa_enabled: true
matrix_ketesa_container_http_host_bind_port: ""
matrix_ketesa_container_labels_traefik_docker_network: proxy
matrix_ketesa_container_labels_traefik_entrypoints: websecure
matrix_ketesa_container_labels_traefik_tls_certResolver: tls_resolver

You can check your configuration with:

grep -nE 'matrix_synapse_admin_|matrix_ketesa_' \
inventory/host_vars/matrix.your-domain.com/vars.yml

If any matrix_synapse_admin_* variables still appear, rename them to their matrix_ketesa_* equivalents.

Keep the Docker collection current

The setup section already installs community.docker. On older installations, update it before running the playbook:

sudo ansible-galaxy collection install community.docker --upgrade

This avoids errors like:

ERROR! couldn't resolve module/action 'community.docker.docker_image_pull'.

Verify that Ansible can resolve the module:

sudo ansible-doc community.docker.docker_image_pull

make roles installs Ansible roles, but it does not necessarily install or upgrade collections. If you see a warning that community.docker does not support your Ansible version and later tasks fail, update Ansible itself, preferably in the dedicated Python virtual environment described above.

Remove the obsolete Telegram public endpoint variable

The Go/bridgev2-based mautrix-telegram bridge no longer has a public web-based login endpoint. Existing configurations must not keep this variable:

matrix_mautrix_telegram_container_labels_public_endpoint_traefik_entrypoints -> <removed (the bridge no longer has a public web-based login endpoint)>

Remove or comment out this line:

# matrix_mautrix_telegram_container_labels_public_endpoint_traefik_entrypoints: websecure

After applying the relevant upgrade notes, run the update again:

sudo ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start

Upgrading PostgreSQL

If the playbook notifies you about a new PostgreSQL version being available, you can perform the upgrade with a specific tag.

⚠️ BACKUP RECOMMENDED
Before upgrading the database, ensure you have a recent backup of your data.

cd /opt/containers/matrix
sudo ansible-playbook -i inventory/hosts setup.yml --tags=upgrade-postgres

Stopping and Uninstalling

To stop all Matrix services:

cd /opt/containers/matrix
sudo ansible-playbook -i inventory/hosts setup.yml --tags=stop

To completely uninstall and delete all data:

cd /opt/containers/matrix
sudo ansible-playbook -i inventory/hosts setup.yml --tags=uninstall

⚠️ DATA LOSS
The `uninstall` tag is destructive and will remove all user data, chat history, and media. Use with extreme caution.

15. Troubleshooting

Below are common issues and quick checks to resolve them.

⚠️ TIP: VERIFY ONE LAYER AT A TIME
When in doubt, verify DNS → Traefik → Nginx `.well-known` → Synapse federation endpoint step by step. Isolate the layer that fails.

15.1 Federation test fails

Ensure port 8448 is exposed by Traefik and the synapse entrypoint exists.

cd /opt/containers/traefik-stack
docker compose ps traefik
docker inspect traefik | jq '.[0].NetworkSettings.Ports["8448/tcp"]'

Test the federation version endpoint directly:

curl -sS https://matrix.your-domain.com:8448/_matrix/federation/v1/version | jq

15.2 .well-known is invalid or missing

Verify the .well-known delegation from your root domain (served by Nginx server):

curl -s https://your-domain.com/.well-known/matrix/server | jq
curl -s https://your-domain.com/.well-known/matrix/client | jq

For this Traefik setup, /.well-known/matrix/server must return "m.server": "matrix.your-domain.com:8448". A value ending in :443 only works if your federation router is intentionally exposed on port 443.
Re-check that the placeholders in conf/nginx.conf were replaced via sed and that CORS headers middleware uses camelCase keys in Traefik labels (e.g., accessControlAllowOriginList).

15.3 Traefik/CrowdSec middleware not applied

Ensure you reference providers correctly:
- Security headers: security-headers@file
- CrowdSec bouncer: crowdsec-bouncer@docker

15.4 ACME/TLS issues

Inspect Traefik logs for ACME errors and DNS problems:

docker compose logs -n 200 traefik | tail -n 200

Confirm A/AAAA records for traefik.your-domain.com and matrix.your-domain.com point to your server and that port 443 is reachable.
Disable CDN Proxy for Initial Certificate: 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.

15.5 Docker network not found

Make sure the external proxy network exists and is used by all services behind Traefik:

docker network ls | grep proxy || docker network create proxy

15.6 Permission problems in inventory/host_vars

If editing files is cumbersome, you can align ownership (optional):

sudo chown -R "$USER":"$USER" /opt/containers/matrix/inventory

15.7 Ansible/venv not active

If you installed Ansible in a virtualenv, reactivate it before running playbooks:

source ~/.venvs/matrix-ansible/bin/activate

15.8 CrowdSec bouncer not registered

Check the bouncer status inside the CrowdSec container (run in your Traefik stack directory):

docker compose exec crowdsec cscli bouncers list

15.9 Element Call: `MISSING_MATRIX_RTC_TRANSPORT`

If Element Web or another client says the server is not configured for Element Call and reports MISSING_MATRIX_RTC_TRANSPORT, the client did not discover your MatrixRTC/LiveKit transport.

When using Element Call with LiveKit, the root-domain /.well-known/matrix/client response must include the RTC focus information in addition to the homeserver delegation:

{
  "m.homeserver": {
    "base_url": "https://matrix.your-domain.com"
  },
  "org.matrix.msc4143.rtc_foci": [
    {
      "type": "livekit",
      "livekit_service_url": "https://matrix.your-domain.com/livekit-jwt-service"
    }
  ]
}

If the root domain serves .well-known from an Nginx container with a single-file bind mount, replacing the file on the host may leave the running container attached to the old inode. After editing the well-known response, recreate the Nginx container or edit the mounted file in place and reload Nginx.

Conclusion

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.

If you want to require TOTP or WebAuthn for compatible human SSO logins, continue with Adding Authelia 2FA to Matrix Synapse with OpenID Connect. Read its Element X compatibility gate and existing-account migration checks before disabling local passwords.

📚PLAYBOOK DOCUMENTATION 🛡️MATRIX DOCUMENTATION 🔐ADD AUTHELIA 2FA

Deploying the Nextcloud Talk High-Performance Backend with Docker

Unknown — Wed, 01 Jul 2026 00:00:00 +0000

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.

This setup is designed to integrate seamlessly with an existing Traefik v3 reverse proxy, making it a powerful addition to your self-hosted infrastructure.

Changelog

Date	Change
2026-07-01	Recording Update: Added migration notes, pinned helper versions, Janus IP checks, TURN cert refresh, and Talk recording guidance.
2025-09-21	Initial Version: Guide created, focusing on Docker Compose deployment and Traefik v3 integration.

1. Prerequisites

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.

⚠️ HARD REQUIREMENT
The following steps will not work correctly without the Traefik stack running as described in the prerequisite guide. Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack: This is the foundation for our reverse proxy and security.

You will also need:

Docker and Docker Compose installed on your server.
A dedicated subdomain for the signaling server (e.g., signaling.your-domain.com) pointed to your server’s IP address.
sudo or root access.
The git utility installed (sudo apt install git).
Firewall ports 80, 443, 3478/tcp, 3478/udp open. The ports 3478 are required by the Coturn (TURN) server.

1.1. Firewall Configuration (UFW Example)

If you are using ufw (Uncomplicated Firewall), you can open the required ports with the following commands:

sudo ufw allow 3478/tcp
sudo ufw allow 3478/udp
# Example with media range 20000–20100 (choose any suitable range)
sudo ufw allow 20000:20100/udp   # match your Janus media range
# Only if you enable TURNS (section 3.4):
sudo ufw allow 5349/tcp         # required for TURNS
# sudo ufw allow 5349/udp       # optional; enable only if you need UDP on 5349

Note: Choose a media port range that is allowed by your provider/network. The exact same range must be configured in both docker-compose.yml (Janus service ports) and janus/janus.jcfg (media min/max).

ℹ️ SECURITY NOTE & CROWDSEC INTEGRATION
The TURN ports (`3478`) are exposed directly and are not protected by the Traefik CrowdSec Bouncer. Securing them should be done at the host level. 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 `coturn` service and telling CrowdSec where to find these logs. Configure CrowdSec to read Docker logs: 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 `coturn`. File to edit: `/opt/containers/traefik-stack/crowdsec/config/acquis.yaml` `--- source: docker container_name_regexp: - ^coturn$ labels: type: coturn` Restart CrowdSec: For the new acquisition configuration to take effect, restart the CrowdSec container in your Traefik stack. `# Navigate to your Traefik stack directory and restart only CrowdSec cd /opt/containers/traefik-stack sudo docker compose restart crowdsec` CrowdSec will now automatically parse the logs for the `coturn` container. The `coturn` service in `docker-compose.yml` should also be configured with a logging driver to enable log rotation. If you use the CrowdSec Firewall Bouncer (iptables/nftables), ensure the Janus media UDP range (e.g., `20000–20100/udp`), Coturn relay range (`30000–30100/udp`), and TURN ports (`3478/tcp`, `3478/udp` and, if enabled, `5349/tcp` [required], `5349/udp` [optional]) are explicitly allowed and not blocked by bouncer rules.

1.2. Resource Planning

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 1-2 dedicated CPU cores and 2-4 GB of RAM 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 htop, docker stats, or a more comprehensive monitoring stack like Prometheus and Grafana.

2. Directory Structure and Download

First, we will clone the official repository, which contains all the necessary Docker configurations.

# Navigate to your main containers directory
cd /opt/containers/

# Clone the repository
sudo git clone https://github.com/strukturag/nextcloud-spreed-signaling.git nextcloud-hpbe

# Enter the new directory
cd nextcloud-hpbe

3. Configuration Files

This setup uses two main configuration files: docker-compose.yml for defining the services and server.conf for the signaling server itself. All configuration values will be hardcoded directly into these files for simplicity and clarity.

3.1. Docker Compose File (`docker-compose.yml`)

Create the docker-compose.yml file. This version uses a hardcoded configuration and is optimized for Traefik v3.

sudo tee docker-compose.yml > /dev/null << 'EOF'

services:
  spreedbackend:
    build:
      context: .
      dockerfile: docker/server/Dockerfile
      platforms:
        - "linux/amd64"
    container_name: spreedbackend
    depends_on:
      - nats
      - janus
      - coturn
    volumes:
      - ./server.conf:/config/server.conf:ro
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      # Router for certificate acquisition (Host-only rule)
      - "traefik.http.routers.hpbe-cert.rule=Host(`signaling.your-domain.com`)"
      - "traefik.http.routers.hpbe-cert.entrypoints=web,websecure"
      - "traefik.http.routers.hpbe-cert.tls.certresolver=tls_resolver"
      - "traefik.http.routers.hpbe-cert.priority=1"
      # Router for the actual service (Host + Path rule)
      - "traefik.http.routers.hpbe.rule=Host(`signaling.your-domain.com`) && PathPrefix(`/standalone-signaling`)"
      - "traefik.http.routers.hpbe.entrypoints=websecure"
      - "traefik.http.routers.hpbe.tls=true"
      - "traefik.http.routers.hpbe.priority=100"
      # Middlewares: Set X-Forwarded-Proto and strip the path prefix
      - "traefik.http.middlewares.hpbe-headers.headers.customRequestHeaders.X-Forwarded-Proto=https"
      - "traefik.http.middlewares.hpbe-strip.stripprefix.prefixes=/standalone-signaling"
      - "traefik.http.routers.hpbe.middlewares=hpbe-headers@docker,hpbe-strip@docker,crowdsec-bouncer@docker"
      # Internal service port
      - "traefik.http.services.hpbe.loadbalancer.server.port=8080"

  nats:
    image: nats:2.14.3
    container_name: nats
    command: ["-c", "/config/gnatsd.conf"]
    volumes:
      - type: bind
        source: ./gnatsd.conf
        target: /config/gnatsd.conf
        read_only: true
    restart: unless-stopped
    networks:
      - proxy

  janus:
    # Build Janus from source using the provided Dockerfile
    build: docker/janus
    container_name: janus
    command: ["janus", "--full-trickle"]
    restart: unless-stopped
    networks:
      - proxy
    ports:
      - "20000-20100:20000-20100/udp"
      # Optional only if you enabled ice_tcp=true (see section 3.3)
      # - "20000-20100:20000-20100/tcp"
    volumes:
      - ./janus/janus.jcfg:/usr/local/etc/janus/janus.jcfg:ro

  coturn:
    image: coturn/coturn:4.14.0-r0
    container_name: coturn
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    command:
      - "--realm"
      - "signaling.your-domain.com"
      - "--static-auth-secret"
      - "PASTE-A-STRONG-RANDOM-32-CHAR-HEX-SECRET-HERE"
      - "--no-stdout-log"
      - "--log-file"
      - "stdout"
      - "--stale-nonce=600"
      - "--use-auth-secret"
      # Using shared-secret auth only; lt-cred-mech omitted to avoid mixed-auth warning
      - "--fingerprint"
      - "--no-software-attribute"
      - "--no-multicast-peers"
      - "--min-port"
      - "30000"
      - "--max-port"
      - "30100"
      - "--cert"
      - "/certs/fullchain.pem"
      - "--pkey"
      - "/certs/privkey.pem"
      - "--tls-listening-port"
      - "5349"
    ports:
      - "3478:3478/tcp"
      - "3478:3478/udp"
      - "5349:5349/tcp"
      - "5349:5349/udp"
      - "30000-30100:30000-30100/udp"
    volumes:
      - ./certs:/certs:ro
    restart: unless-stopped

networks:
  proxy:
    external: true
EOF

Note: Before launching, create janus/janus.jcfg as described in section 3.3 (set nat_1_1_mapping and the min_port/max_port media port range).

Note: On hosts with a direct public IP, you typically do not need to set Coturn’s --listening-ip, --relay-ip, or --external-ip. Relying on defaults avoids common binding errors (e.g., “Cannot assign requested address”, errno=99). Only set --external-ip PUBLIC_IP/PRIVATE_HOST_IP (and optionally --listening-ip/--relay-ip to the private host IP) if your host is behind NAT.

⚠️ SERVER MIGRATION
When moving this stack to a new server, update Janus’ `nat_1_1_mapping` before testing calls. If it still advertises the old public IP address, signaling may work while media fails because clients receive unreachable ICE candidates.

3.2. Signaling Server Config (`server.conf`)

This file configures the core logic of the HPBE. Create server.conf, paste the template below, and replace the placeholder values with your own secrets and URLs.

sudo tee server.conf > /dev/null << 'EOF'
[http]
listen = 0.0.0.0:8080

[app]
debug = false

[sessions]
# Use 'openssl rand -base64 16' to generate these
hashkey = PASTE-A-RANDOM-BASE64-KEY-HERE
blockkey = PASTE-A-RANDOM-BASE64-KEY-HERE

[backend]
backends = backend-1 #, backend-2
allowall = false
timeout = 10
connectionsperhost = 8

[backend-1]
url = https://cloud.your-domain.com
# Use 'openssl rand -hex 16' to generate this
secret = PASTE-A-RANDOM-HEX-SECRET-HERE

# To add a second backend, add it to the 'backends' list and create a new section
# [backend-2]
# url = https://another-cloud.com
# secret = PASTE-ANOTHER-RANDOM-HEX-SECRET-HERE

[nats]
url = nats://nats:4222

[mcu]
type = janus
url = ws://janus:8188

[turn]
# Use 'openssl rand -base64 16' to generate this
apikey = PASTE-A-RANDOM-BASE64-KEY-HERE
# This secret MUST be identical to the '--static-auth-secret' in docker-compose.yml
secret = PASTE-THE-SAME-STRONG-SECRET-AS-IN-DOCKER-COMPOSE
servers = turn:signaling.your-domain.com:3478?transport=udp,turn:signaling.your-domain.com:3478?transport=tcp
EOF

⚠️ SYNCHRONIZE TURN SECRET
The `secret` in the `[turn]` section of this file must be identical to the `--static-auth-secret` value used in the `coturn` service in your `docker-compose.yml` file.

Ensure the file has the correct permissions: sudo chmod 644 server.conf.

3.2.1 Replace placeholders and generate secrets

Before launching, perform these steps so your setup works on your domain and with strong secrets.

Replace the domain placeholder

We use signaling.your-domain.com as a placeholder. Replace it with your real domain in both files:

cd /opt/containers/nextcloud-hpbe
sudo sed -i 's/signaling\.your-domain\.com/signaling.example.com/g' docker-compose.yml server.conf

Replace signaling.example.com with your actual TURN/signaling domain.

Generate the required secrets with openssl

Sessions keys (base64) for server.conf [sessions]:

openssl rand -base64 16  # paste as sessions.hashkey
openssl rand -base64 16  # paste as sessions.blockkey

Backend shared secret (hex) for each Nextcloud in server.conf [backend-*]:

openssl rand -hex 16     # paste as backend-1.secret (and for backend-2, backend-3, ...)

TURN API key (base64) for server.conf [turn] apikey:

openssl rand -base64 16  # paste as turn.apikey

TURN static secret (hex) used in BOTH places:
- server.conf [turn] secret
- docker-compose coturn command --static-auth-secret

openssl rand -hex 16     # paste into both places, values must be identical

Open firewall ports (host level)

sudo ufw allow 3478/tcp
sudo ufw allow 3478/udp
sudo ufw allow 20000:20100/udp   # Janus media range
sudo ufw allow 30000:30100/udp   # Coturn relay range
# The main docker-compose includes TURNS by default:
sudo ufw allow 5349/tcp         # required for TURNS
# sudo ufw allow 5349/udp       # optional; some clients might use it

3.2.2 Example: Multiple Nextcloud backends

If you operate more than one Nextcloud that should use the same signaling backend, model your [backend] section like this. Replace the example domains and secrets with your own.

[backend]
backends = backend-1, backend-2, backend-3
allowall = false
timeout = 10
connectionsperhost = 8

[backend-1]
url = https://cloud1.example.com
secret = PASTE-A-RANDOM-HEX-SECRET-HERE

[backend-2]
url = https://cloud2.example.com
secret = PASTE-A-RANDOM-HEX-SECRET-HERE

[backend-3]
url = https://cloud3.example.com
secret = PASTE-A-RANDOM-HEX-SECRET-HERE

Note: The secret for each backend must match the “Shared secret” you configure in that specific Nextcloud under Admin -> Talk.

3.2.3 Optional: Bind the HTTP listener to the service name

By default this guide uses listen = 0.0.0.0:8080 in [http], which is simple and works well behind Traefik. If you prefer to bind strictly to the Docker service name, you can set:

[http]
listen = spreedbackend:8080

Both are valid in a single Docker network; choose the variant that fits your operational preference.

3.3. Janus NAT and Media Ports (required for working audio/video)

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.

Do the following:

Create a minimal Janus config that sets public IP mapping and a fixed media port range

Create ./janus/janus.jcfg with the following content. Replace PUBLIC.IP.OR.DNS with your server’s public address or a DNS name that resolves to it (no CDN/Orange-Cloud in front):

# Minimal but complete Janus config for operation behind Docker
# with a fixed UDP port range and correct 1:1 NAT mapping.

general: {
  configs_folder = "/usr/local/etc/janus"
  # Keep logging at "info" (default), set "debug = true" if needed
}

at: {
  # Important: public IP or DNS of the host that clients should see
  nat_1_1_mapping = "signaling.your-domain.com"

  # SRFLX candidates (optional, but doesn't hurt)
  stun_server = "signaling.your-domain.com"
  stun_port   = 3478

  # ICE Lite is fine for SFU operation and reduces complexity
  ice_lite = true
}

media: {
  # Fixed, small port range: must match docker-compose (ports:)
  min_port = 20000
  max_port = 20100

  # Prefer UDP (TCP disabled as it's often problematic/unnecessary)
  ice_tcp = false

  # (Optional) Enforce RTCP-MUX – common default, can help
  rtcp_mux = true
}

# Websockets (HPBE communicates internally via ws://janus:8188)
# Defaults are fine, no extra port publishing needed as it's in the same Docker network.
websockets: {
  ws = true
  ws_port = 8188
  ws_interface = "0.0.0.0"
}

# REST & Admin disabled by default – not needed
admin: {
  admin_http = false
  admin_secret = "changeit"
}

Ensure your main docker-compose includes the Janus media ports and config mount

In section 3.1, the janus service already contains the required ports and volumes lines. Verify that your configuration matches:

ports: "20000-20100:20000-20100/udp" (optional TCP only if ice_tcp=true)
volumes: ./janus/janus.jcfg:/usr/local/etc/janus/janus.jcfg:ro

Open the firewall for the media range (host level)

sudo ufw allow 20000:20100/udp
# Adjust to the exact range you configured in janus.jcfg and docker-compose
# Only if you enabled ice_tcp=true
# sudo ufw allow 20000:20100/tcp

ℹ️ CAPACITY PLANNING FOR MEDIA PORTS
With RTCP-MUX/BUNDLE (Janus default), each active PeerConnection typically uses about one UDP port on the server. Plan roughly 1 port per active participant (conservatively 2 if features like separate screen-share/recording open additional PeerConnections). Examples (illustrative): Range 40000–40050 (51 ports) → about 25–50 concurrent PeerConnections (small groups). Range 40000–40199 (200 ports) → more headroom for spikes and larger meetings. Always match your firewall (UFW) and CrowdSec rules to the same UDP range you configured in `janus.jcfg` and in the `janus` service `ports`. The above examples use 40000-based ranges; choose the range you actually configured (e.g., 20000–20100).

Apply the changes

If you have not launched the stack yet, skip this step. The changes will take effect when you start the stack in section 4.
If Janus is already running, apply the updated config now:

sudo docker compose up -d --force-recreate janus

Verify during a call attempt

In Firefox about:webrtc or Chrome chrome://webrtc-internals check that the remote ICE candidates from Janus show your public IP with ports in 20000–20100 and that the ICE state becomes connected/completed.
On the server, you should see traffic on those ports while a call is setting up:

sudo tcpdump -ni any udp port 3478
sudo tcpdump -ni any udp portrange 20000-20100

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.

3.4. Enable TURN over TLS (5349)

Enabling turns: adds TLS encryption to TURN traffic on port 5349. This often helps in restrictive networks and hides credentials from passive observers.

Steps:

Create the certs directory and export PEMs from Traefik’s ACME store

Since this guide builds on the prerequisite Traefik v3 and CrowdSec tutorial, your certificates are stored in Traefik’s ACME database at /opt/containers/traefik-stack/traefik/certs/acme.json. Export the certificate and key for your TURN domain into ./certs.

cd /opt/containers/nextcloud-hpbe

# Domain used for TURN/TURNS (anonymized placeholder)
TURN_DOMAIN="signaling.your-domain.com"
ACME="/opt/containers/traefik-stack/traefik/certs/acme.json"

# Ensure tools are available
sudo apt-get update && sudo apt-get install -y jq

# Create output directory
mkdir -p ./certs
# (Directory permissions are set in step 1.1 below)

# Extract certificate and key for the TURN domain from acme.json
sudo jq -r --arg d "$TURN_DOMAIN" '
  .. | objects
  | select(has("domain") and (.domain.main==$d or ((.domain.sans // []) | index($d))))
  | .certificate
' "$ACME" | base64 -d | sudo tee ./certs/fullchain.pem > /dev/null

sudo jq -r --arg d "$TURN_DOMAIN" '
  .. | objects
  | select(has("domain") and (.domain.main==$d or ((.domain.sans // []) | index($d))))
  | .key
' "$ACME" | base64 -d | sudo tee ./certs/privkey.pem > /dev/null

Note: The certificate must match the TURN realm/domain you advertise (e.g., signaling.your-domain.com).

1.1 Set Certificate and Directory Permissions

Coturn does not run as root inside the container, but as the nobody:nogroup user. Without the correct permissions on both the directory and the files, Coturn cannot read the certificates and the turns: connection will fail (often shown as red in Nextcloud Talk).

# In your project directory (e.g., /opt/containers/nextcloud-hpbe)

# Detect the group ID used by Coturn inside the container (commonly 65534 for 'nogroup')
GID=$(docker compose exec -T coturn sh -c 'id -g' | tr -d '\r')

# Ensure the certs directory is accessible to that group
sudo chgrp "$GID" ./certs
sudo chmod 750 ./certs

# Set group ownership and restrictive permissions on the files
sudo chgrp "$GID" ./certs/privkey.pem ./certs/fullchain.pem
sudo chmod 640 ./certs/privkey.pem
sudo chmod 644 ./certs/fullchain.pem

# Restart Coturn to load the updated certificates
sudo docker compose up -d --force-recreate coturn

Note: If your image uses the default nobody:nogroup, you may alternatively use sudo chgrp nogroup ... instead of the detected GID.

TLS is already configured in the main docker-compose.yml in this guide. After creating/exporting the certificates in step 1, simply recreate Coturn so it picks up the TLS files.

Note: If you exclusively use shared-secret auth (--use-auth-secret with --static-auth-secret), you can omit --lt-cred-mech to avoid a warning.

Update your server.conf servers list to include the turns: endpoint:

[turn]
servers = turn:signaling.your-domain.com:3478?transport=udp,turn:signaling.your-domain.com:3478?transport=tcp,turns:signaling.your-domain.com:5349?transport=tcp

Open the firewall for port 5349:

sudo ufw allow 5349/tcp         # required for TURNS
# sudo ufw allow 5349/udp       # optional; enable only if you need UDP on 5349

4. Launch the Stack

With the configuration complete, you can now build and start the services.

# From within the /opt/containers/nextcloud-hpbe directory
sudo docker compose up --build -d

The --build flag is important because it builds the Janus and the spreedbackend images from their Dockerfiles. The Janus build, in particular, can take several minutes.

You can monitor the logs to ensure everything starts correctly:

sudo docker compose logs -f

4.1 Verify TURN/TURNS endpoints

If nc is not installed, install it first:

sudo apt-get update && sudo apt-get install -y netcat-openbsd

Run these quick checks from a client or your server to verify connectivity:

# 1) Check TCP reachability (expect "succeeded")
nc -vz signaling.your-domain.com 3478
nc -vz signaling.your-domain.com 5349  # only if TURNS enabled

# 2) Verify TLS on 5349 (should show certificate details; only if TURNS is enabled)
openssl s_client -connect signaling.your-domain.com:5349 -servername signaling.your-domain.com -brief < /dev/null

# 3) Check Coturn runtime logs
docker compose logs -f coturn

If you have turnutils_uclient available (from the coturn package), you can perform an end-to-end TURN allocation test as an advanced check.

5. Configure Nextcloud

The final step is to tell your Nextcloud instance to use the new High-Performance Backend.

Log in to Nextcloud as an administrator.
Navigate to Administration Settings -> Talk.
Scroll down to the “Signaling server” section.
Check “Enable custom signaling server”.
In the “Signaling server URL” field, enter the full path to your HPBE: https://signaling.your-domain.com/standalone-signaling.
In the “Shared secret” field, paste the corresponding shared secret for this specific Nextcloud instance (e.g., the value of NEXTCLOUD_1_SHARED_SECRET for your first instance).
Click “Save changes”.

Nextcloud will verify the connection. If everything is correct, you’re all set!

Clarifying Secret Mappings

To ensure all components communicate securely, it’s crucial to map the secrets correctly. Here is a quick reference:

`server.conf` Section & Key	Maps to…	Purpose
`[backend]` -> `secret`	Nextcloud Admin -> Talk -> Shared secret	Authenticates Nextcloud with the signaling server.
`[turn]` -> `apikey`	Used by the signaling server to generate time-limited TURN credentials for clients. Janus does not use this key in this setup.	Allows signaling server to get TURN credentials.
`[turn]` -> `secret`	`coturn` service -> `--static-auth-secret` command argument	Authenticates TURN users (generated by signaling).

6. Talk Recording

Nextcloud Talk recording is a separate service. It is not provided automatically just because HPB, Janus, and Coturn are running.

Create a separate stack, for example /opt/containers/nextcloud-talk-recording/docker-compose.yml:

services:
  nextcloud-talk-recording:
    image: nextcloud/aio-talk-recording:20260609_115915
    container_name: nextcloud-talk-recording
    restart: unless-stopped
    shm_size: "4gb"
    environment:
      - TZ=Europe/Berlin
      - NC_DOMAIN=cloud.your-domain.com
      - HPB_DOMAIN=signaling.your-domain.com
      - RECORDING_SECRET=PASTE-A-STRONG-RECORDING-SECRET-HERE
      - INTERNAL_SECRET=PASTE-A-STRONG-INTERNAL-SECRET-HERE
    volumes:
      - ./recording.conf:/conf/recording.conf
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.nextcloud-talk-recording.rule=Host(`recording.your-domain.com`)"
      - "traefik.http.routers.nextcloud-talk-recording.entrypoints=websecure"
      - "traefik.http.routers.nextcloud-talk-recording.tls.certresolver=tls_resolver"
      - "traefik.http.routers.nextcloud-talk-recording.middlewares=security-headers@file,crowdsec-bouncer@docker"
      - "traefik.http.services.nextcloud-talk-recording.loadbalancer.server.port=1234"
    networks:
      - proxy

networks:
  proxy:
    external: true

Do not mount recording.conf read-only. Current recording images generate or update /conf/recording.conf from environment variables at startup. A read-only bind mount can cause startup warnings or broken configuration.

If DNS still points signaling.your-domain.com to an old server during a migration, add a temporary extra_hosts entry so the recording container reaches the new HPB stack. Remove it after DNS cutover:

extra_hosts:
  - "signaling.your-domain.com:YOUR_NEW_SERVER_IP"

In Nextcloud’s Talk admin settings, configure the recording server URL and recording secret to match this stack.

ℹ️ RECORDING VALIDATION
A `404` on `https://recording.your-domain.com/` only proves that Traefik reaches the Flask service. The real validation is starting a recording from an actual Nextcloud Talk room and confirming that the recording is produced.

7. Troubleshooting & Monitoring

If you encounter issues, here are a few steps to diagnose the problem:

Verify the Signaling Server is Reachable

You should get a 200 OK response from the /welcome endpoint. This confirms that Traefik is routing requests correctly.
```
curl -i https://signaling.your-domain.com/standalone-signaling/api/v1/welcome
```
Check the Container Logs

The logs are the best source for identifying errors. Pay close attention to messages about secrets, WebSocket connections, or backend timeouts.
```
# From within the /opt/containers/nextcloud-hpbe directory
sudo docker compose logs -f
```
Common Errors & Fixes
- ERROR: the sessions block key must be... or hash key should be...: This error occurs when the keys in server.conf are missing or have the wrong format. Use openssl rand -base64 16 to generate new keys and paste them into the [sessions] section.
- TURN Secret Mismatch: If calls fail to connect, verify that the secret in the [turn] section of server.conf is exactly the same as the --static-auth-secret in the coturn command in docker-compose.yml.
- “failed to establish signaling connection”: This is a classic error.
  - Check that the URL in Nextcloud is exactly https://.../standalone-signaling.
  - Ensure your Traefik labels are correct (especially the PathPrefix and stripPrefix rules).
  - Verify that the Shared secret in Nextcloud matches the one in server.conf.
  - 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 docker-compose.yml (Janus ports) and janus/janus.jcfg.
- Calls work for 2 people but fail with 3+: This often points to a problem with Janus (the MCU) or Coturn (the TURN server). Check their logs specifically.
- No video/audio from external networks: This is a typical TURN server issue. Ensure ports 3478 (TCP/UDP) are open on your firewall and correctly forwarded to the Coturn container.
- turn: works, but turns: fails (is red in Nextcloud): This is almost always a certificate permission issue. Coturn cannot read the TLS certificate or key. Verify that Coturn can access the files with docker compose exec coturn ls -l /certs. If you see permission errors, re-run the permission-setting steps in section 3.4. You can also test externally with: openssl s_client -connect signal.example.com:5349 -servername signal.example.com.

7.1 Diagnose ICE/RTP issues quickly

Check remote candidates in the browser: Use about:webrtc (Firefox) or chrome://webrtc-internals (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.
Look for ICE state: iceConnectionState should reach connected/completed. If it stays in checking/failed, open ports or NAT/public IP mapping are missing.
Server-side packet capture: While attempting a call, run sudo tcpdump -ni any udp portrange 20000-20100 to confirm media packets hit the host.
TURN sanity: Use the Trickle ICE demo with your TURN URIs to confirm you get relay candidates; verify your Coturn realm and static secret match the values in server.conf and docker-compose.yml.

8. Maintenance and Updates

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 git pull.

Step 1: Stop and Back Up the Current Installation

First, stop the running services and create a backup of your entire nextcloud-hpbe directory.

# Navigate to the parent directory of your HPBE installation
cd /opt/containers/

# Stop the services using the existing docker-compose file
sudo docker compose -f nextcloud-hpbe/docker-compose.yml down

# Create a backup by renaming the directory
sudo mv nextcloud-hpbe nextcloud-hpbe_BACKUP

Step 2: Clone the New Version

Clone the latest version of the repository into a clean directory with the original name.

# Stay in /opt/containers/
sudo git clone https://github.com/strukturag/nextcloud-spreed-signaling.git nextcloud-hpbe

Step 3: Restore Your Configuration

Copy your essential configuration files from the backup into the new directory. This ensures your secrets, domains, and other settings are preserved.

# Copy your docker-compose.yml and server.conf
sudo cp nextcloud-hpbe_BACKUP/docker-compose.yml nextcloud-hpbe/docker-compose.yml
sudo cp nextcloud-hpbe_BACKUP/server.conf nextcloud-hpbe/server.conf

Step 4: Launch the Updated Stack

Finally, navigate into the new directory and start the services. The --build flag will create new images if required, and --remove-orphans cleans up any old, unused containers.

# Navigate into the new HPBE directory
cd nextcloud-hpbe

# Build and start the updated services
sudo docker compose up --build -d --remove-orphans

After a few moments, your updated High-Performance Backend will be running. You can optionally remove the backup directory (sudo rm -rf /opt/containers/nextcloud-hpbe_BACKUP) once you have confirmed everything is working correctly.

Migration Checklist

When moving an existing HPB stack to a new server:

Keep the public signaling hostname stable if possible.
Open the TURN, TURNS, Janus media, and Coturn relay ports before DNS cutover.
Update janus/janus.jcfg so nat_1_1_mapping points to the new public IP or DNS name.
Reissue or export fresh certificates for the TURN/TURNS hostname after DNS points to the new server.
Restart coturn after replacing certificate files.
If recording is used, make sure the recording container resolves the HPB hostname to the new server.
Test with a real Talk room, including a recording test.

If your TURN certificate is exported from Traefik’s acme.json, repeat that export after the new server has successfully obtained the certificate:

cd /opt/containers/nextcloud-hpbe
sudo docker compose up -d --force-recreate coturn

Conclusion

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.

📚OFFICIAL HPBE REPOSITORY

Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack

Unknown — Wed, 01 Jul 2026 00:00:00 +0000

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.

Changelog

Date	Change
2026-07-17	Related Guide: Linked the reusable Authelia SSO and 2FA deployment for Traefik-protected services.
2026-07-01	Migration Hardening: Pinned production versions, clarified Docker socket and CrowdSec scope, and added ACME migration guidance.
2026-03-03	Security Fix: Added `forwardedHeaders.trustedIPs` to both entrypoints to prevent X-Forwarded-For spoofing.
2026-03-03	Component Updates & Syntax Fixes: Updated Traefik to v3.6, CrowdSec plugin to v1.4.7, and pinned CrowdSec to v1.6. Fixed Traefik v3 `HostRegexp` syntax and improved healthchecks.
2026-01-26	Robustness Update: Added AccessLog filtering to prevent disk exhaustion and improved logrotate instructions with path discovery.
2026-01-15	Docs Update: Removed redundant `router.tls=true` label from the bypass example and added a new section explaining how to route multiple (sub)domains to one service.
2025-12-10	Production Hardening: Added comprehensive log rotation configuration and disk troubleshooting section based on real-world feedback.
2025-09-18	Final Review: Switched to robust httpChallenge, corrected provider in example, added raw API key generation.
2025-09-17	Major Refactor: Switched from legacy bouncer container to modern Traefik Plugin. Moved all variable configs to Docker Labels.
2025-07-10	Added Special Use-Case: Included a clear example of how to deploy a service without CrowdSec protection for specific needs.
2025-07-09	Initial Version: Article created based on best practices for a modern Traefik v3 and CrowdSec deployment with Docker Compose.

1. Prerequisites

Before you begin, ensure you have the following installed on your server (e.g., Ubuntu 22.04 or Debian 12):

Docker and Docker Compose
curl, openssl, and apache2-utils (for password generation)
A domain name pointed to your server’s IP address
Open firewall ports 80 and 443
sudo or root access

You can install the required utilities with:

sudo apt update
sudo apt install -y curl openssl apache2-utils

2. Directory Structure

A well-organized directory structure is key. We will create a central location for our stack’s configuration and data.

# Create the main directory
sudo mkdir -p /opt/containers/traefik-stack
cd /opt/containers/traefik-stack

# Create directories for each service
sudo mkdir -p traefik/{dynamic,logs,certs}
sudo mkdir -p crowdsec/{config,data}

# Prepare Let's Encrypt certificates file
sudo touch traefik/certs/acme.json
sudo chmod 600 traefik/certs/acme.json

This structure keeps everything tidy and separated.

3. Configuration Files

Now, let’s create the configuration files for our stack.

3.1. Main Configuration (`.env`)

This file holds all your environment-specific variables.

sudo tee .env > /dev/null << 'EOF'
# --- General Settings ---
TZ=Europe/Berlin
DOMAIN_NAME=your-domain.com

# --- Traefik Settings ---
TRAEFIK_DASHBOARD_HOST=traefik.${DOMAIN_NAME}
LETSENCRYPT_EMAIL=your-email@example.com

# --- CrowdSec Settings ---
CROWDSEC_COLLECTIONS="crowdsecurity/traefik crowdsecurity/linux"

# --- Credentials ---
CROWDSEC_BOUNCER_API_KEY=PASTE-YOUR-GENERATED-KEY-HERE
EOF

⚠️ IMPORTANT
Replace `your-domain.com`, `your-email@example.com`. The API key will be generated and pasted in a later step.

3.2. Traefik Static Configuration (`traefik.yml`)

This file contains the core Traefik settings that rarely change.

sudo tee traefik.yml > /dev/null << 'EOF'
global:
  checkNewVersion: false
  sendAnonymousUsage: false

api:
  dashboard: true

ping: {}

entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
    forwardedHeaders:
      insecure: false
      trustedIPs:
        - "127.0.0.1/32"
        - "10.0.0.0/8"
        - "172.16.0.0/12"
        - "192.168.0.0/16"
  websecure:
    address: ":443"
    forwardedHeaders:
      insecure: false
      trustedIPs:
        - "127.0.0.1/32"
        - "10.0.0.0/8"
        - "172.16.0.0/12"
        - "192.168.0.0/16"

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false
    network: proxy
  file:
    directory: /etc/traefik/dynamic
    watch: true

experimental:
  plugins:
    crowdsec-bouncer:
      moduleName: github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin
      version: v1.6.0

certificatesResolvers:
  tls_resolver:
    acme:
      storage: /certs/acme.json
      httpChallenge:
        entryPoint: web

log:
  level: INFO
  filePath: /var/log/traefik/traefik.log
accessLog:
  filePath: /var/log/traefik/access.log
  format: json
  filters:
    statusCodes:
      - "400-599"
  fields:
    headers:
      defaultMode: keep
EOF

3.2.1. Forwarded Headers (Trusted IPs)

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 X-Forwarded-For header.

Without this configuration, any visitor can spoof the X-Forwarded-For header, bypassing IP-based rate limiting, abuse protection, or geo-blocking.

What do these entries in traefik.yml mean?

insecure: false — Traefik does not automatically trust all incoming X-Forwarded-For headers. This is the default, but we set it explicitly for clarity.
trustedIPs — Traefik only accepts the forwarded header from these source IPs. For all other requests, Traefik overwrites the header with the actual sender IP.
The four ranges cover the loopback interface (127.0.0.1) and all private network ranges (used for internal Docker communication).

ℹ️ UPSTREAM PROXIES
If you run a load balancer or CDN in front of Traefik, you must add its IP ranges as well. Examples: Hetzner Load Balancer: The private IPs of the LB within the same network (e.g., `10.0.0.0/8` already covers this if the LB is in the same private network). Alternatively, explicitly add the public LB IP. Cloudflare: Add the official Cloudflare IP ranges. See https://www.cloudflare.com/ips/. Traefik also offers the shorthand `cloudflare` as a provider for this (undocumented, better to set the ranges explicitly). AWS ALB / NLB: The VPC subnet ranges of the load balancer. Without the correct IPs, your application will see the load balancer’s IP instead of the client’s IP.

⚠️ NEVER USE INSECURE: TRUE
The setting `insecure: true` causes Traefik to accept the `X-Forwarded-For` header from any source — even directly from the internet. This opens the door for IP spoofing and should never be used in production.

ℹ️ PLUGIN NAMING CONVENTION
The plugin is defined here under the name `crowdsec-bouncer`. You will often see the official CrowdSec documentation refer to it simply as `bouncer`. Both work perfectly, as long as you are consistent when referencing it in your Docker labels later on.

3.3. Traefik Dynamic Configuration (`dynamic/middlewares.yml`)

This file defines reusable middleware components.

sudo tee traefik/dynamic/middlewares.yml > /dev/null << 'EOF'
http:
  middlewares:
    # 1. General security headers
    security-headers:
      headers:
        browserXssFilter: true
        contentTypeNosniff: true
        frameDeny: true
        forceSTSHeader: true
        stsIncludeSubdomains: true
        stsPreload: true
        stsSeconds: 31536000

    # 2. Basic Auth for the dashboard
    traefik-dashboard-auth:
      basicAuth:
        usersFile: "/etc/traefik/dynamic/.htpasswd"
EOF

3.4. Docker Compose (`docker-compose.yml`)

This is the main file defining our services.

sudo tee docker-compose.yml > /dev/null << 'EOF'
services:
  traefik:
    image: traefik:v3.7.5
    container_name: traefik
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    command:
      - --certificatesresolvers.tls_resolver.acme.email=${LETSENCRYPT_EMAIL}
    networks:
      - proxy
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik.yml:/etc/traefik/traefik.yml:ro
      - ./traefik/dynamic:/etc/traefik/dynamic:ro
      - ./traefik/certs:/certs
      - ./traefik/logs:/var/log/traefik
    environment:
      - TZ=${TZ}
    labels:
      - "traefik.enable=true"
      - "traefik.http.middlewares.crowdsec-bouncer.plugin.crowdsec-bouncer.enabled=true"
      - "traefik.http.middlewares.crowdsec-bouncer.plugin.crowdsec-bouncer.crowdsecMode=stream"
      - "traefik.http.middlewares.crowdsec-bouncer.plugin.crowdsec-bouncer.crowdsecLapiHost=crowdsec:8080"
      - "traefik.http.middlewares.crowdsec-bouncer.plugin.crowdsec-bouncer.crowdsecLapiKey=${CROWDSEC_BOUNCER_API_KEY}"
      - "traefik.http.routers.dashboard.rule=Host(`${TRAEFIK_DASHBOARD_HOST}`)"
      - "traefik.http.routers.dashboard.entrypoints=websecure"
      - "traefik.http.routers.dashboard.tls.certresolver=tls_resolver"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.middlewares=traefik-dashboard-auth@file,crowdsec-bouncer@docker"
    healthcheck:
      test: ["CMD", "traefik", "healthcheck", "--ping"]
      interval: 30s
      timeout: 10s
      retries: 3

  crowdsec:
    image: crowdsecurity/crowdsec:v1.7.8
    container_name: crowdsec
    restart: unless-stopped
    networks:
      - proxy
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./crowdsec/config:/etc/crowdsec:z
      - ./crowdsec/data:/var/lib/crowdsec/data:z
      - ./traefik/logs:/var/log/traefik:ro
      - /var/log:/var/log/host/:ro
    environment:
      - TZ=${TZ}
      - COLLECTIONS=${CROWDSEC_COLLECTIONS}
    healthcheck:
      test: ["CMD", "cscli", "version"]
      interval: 60s
      timeout: 15s
      retries: 3

networks:
  proxy:
    name: proxy
    external: true
EOF

⚠️ DOCKER SOCKET SECURITY
Mounting `/var/run/docker.sock` directly gives the container root-equivalent access to the Docker daemon. For a production-hardened setup, consider using a Docker Socket Proxy (like `tecnativa/docker-socket-proxy`) to restrict Traefik to read-only access for essential API endpoints.

ℹ️ CROWDSEC SCOPE
The Traefik bouncer protects HTTP(S) traffic that actually passes through Traefik. It does not protect SSH, SMTP, IMAP, TURN, Matrix federation, or other ports exposed directly on the host. For those, use service-specific hardening, firewall rules, Fail2Ban, or the CrowdSec firewall bouncer.

3.5. Create Dashboard Password

sudo htpasswd -c traefik/dynamic/.htpasswd admin

3.6. CrowdSec Acquisition Configuration (`crowdsec/config/acquis.yaml`)

sudo tee crowdsec/config/acquis.yaml > /dev/null << 'EOF'
filenames:
  - /var/log/traefik/access.log
labels:
  type: traefik
---
filenames:
  - /var/log/host/auth.log
  - /var/log/host/syslog
labels:
  type: syslog
EOF

4. Launch and Verify the Stack

Create the external network:
```
docker network create proxy
```
Start the services:
```
docker compose up -d
```
Upon first launch, Traefik will request a certificate from Let’s Encrypt. This may take a minute.

Generate the Bouncer API Key:

docker compose exec crowdsec cscli bouncers add traefik -o raw

ℹ️ LAPI STARTUP TIME
`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.`

Copy the long, alphanumeric string that is output.

Update your .env file: Paste the copied key as the value for CROWDSEC_BOUNCER_API_KEY.

Restart Traefik to apply the key:

docker compose up -d --force-recreate traefik

Verify the bouncer connection:
```
docker compose exec crowdsec cscli bouncers list
```
You should see the traefik bouncer listed. You can now access your dashboard at https://traefik.your-domain.com.

5. Adding Services to Traefik

Here is how to expose other Docker services through Traefik, with and without CrowdSec protection.

5.1. Scenario 1: Service Protected by CrowdSec (Standard)

This is the recommended setup for most public-facing services. We’ll use WordPress as an example. Create a docker-compose.yml in a separate directory (e.g., /opt/containers/wordpress):

services:
  wordpress:
    image: wordpress:latest
    restart: unless-stopped
    networks:
      - default
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.wordpress.rule=Host(`blog.your-domain.com`)"
      - "traefik.http.routers.wordpress.entrypoints=websecure"
      - "traefik.http.routers.wordpress.tls.certresolver=tls_resolver"
      - "traefik.http.routers.wordpress.middlewares=security-headers@file,crowdsec-bouncer@docker"
      - "traefik.http.services.wordpress.loadbalancer.server.port=80"
  
  db:
    image: mariadb:11
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: change-me
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: supersecret
    volumes:
      - db_data:/var/lib/mysql
    networks:
      - default

networks:
  proxy:
    external: true
  default:

volumes:
  db_data:

The key label is traefik.http.routers.wordpress.middlewares=security-headers@file,crowdsec-bouncer@docker, which applies our security headers (from the file provider) and the CrowdSec bouncer (defined on the Traefik service via Docker labels).

5.2. Scenario 2: Service Bypassing CrowdSec (Special Case)

Sometimes you need to expose a service without CrowdSec’s interference. Common reasons include:

A public API that must not be blocked.
A site heavily reliant on ad network traffic, where false positives could impact revenue.
Internal tools that are already secured by other means.

To bypass CrowdSec, simply omit the crowdsec-bouncer@docker middleware.

# In the labels for your service (e.g., an API)
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.my-api.rule=Host(`api.your-domain.com`)"
  - "traefik.http.routers.my-api.entrypoints=websecure"
  - "traefik.http.routers.my-api.tls.certresolver=tls_resolver"
  # --- Middlewares (Security ONLY) ---
  - "traefik.http.routers.my-api.middlewares=security-headers@file"
  - "traefik.http.services.my-api.loadbalancer.server.port=3000"

ℹ️ MAXIMUM FLEXIBILITY
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.

5.3. Routing Multiple (Sub)Domains to One Service

Sometimes one container should respond to more than one hostname (e.g., example.com and www.example.com, or multiple subdomains pointing to the same app). You have a few common options.

Option A: Multiple Explicit Hosts in One Router

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.app.rule=Host(`example.com`) || Host(`www.example.com`)"
  - "traefik.http.routers.app.entrypoints=websecure"
  - "traefik.http.routers.app.tls.certresolver=tls_resolver"
  - "traefik.http.routers.app.middlewares=security-headers@file,crowdsec-bouncer@docker"
  - "traefik.http.services.app.loadbalancer.server.port=80"

Option B: Wildcard / Pattern Matching (Many Subdomains)

Use this if you want to match many subdomains dynamically.

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.app.rule=HostRegexp(`[a-z0-9-]+\.example\.com`)"
  - "traefik.http.routers.app.entrypoints=websecure"
  - "traefik.http.routers.app.tls.certresolver=tls_resolver"
  - "traefik.http.routers.app.middlewares=security-headers@file,crowdsec-bouncer@docker"
  - "traefik.http.services.app.loadbalancer.server.port=80"

⚠️ WILDCARD CERTIFICATES & LET'S ENCRYPT
While `HostRegexp` routes the traffic dynamically, the `httpChallenge` configured earlier cannot issue a wildcard certificate (e.g., `.example.com`). Let’s Encrypt requires a DNS challenge* for wildcards. With `httpChallenge`, Traefik will attempt to request individual certificates for every matched subdomain, which can quickly exhaust Let’s Encrypt rate limits.

Option C: Multiple Routers, One Service (Different Middleware per Host)

This is useful if one hostname should bypass CrowdSec while another one stays protected.

labels:
  - "traefik.enable=true"

  - "traefik.http.routers.app-main.rule=Host(`app.example.com`)"
  - "traefik.http.routers.app-main.entrypoints=websecure"
  - "traefik.http.routers.app-main.tls.certresolver=tls_resolver"
  - "traefik.http.routers.app-main.middlewares=security-headers@file,crowdsec-bouncer@docker"

  - "traefik.http.routers.app-api.rule=Host(`api.example.com`)"
  - "traefik.http.routers.app-api.entrypoints=websecure"
  - "traefik.http.routers.app-api.tls.certresolver=tls_resolver"
  - "traefik.http.routers.app-api.middlewares=security-headers@file"

  - "traefik.http.services.app.loadbalancer.server.port=80"
  - "traefik.http.routers.app-main.service=app"
  - "traefik.http.routers.app-api.service=app"

6. Maintenance

6.1. Updating Pinned Versions

This guide pins production image and plugin versions. To update, change the tags in docker-compose.yml and traefik.yml, read the relevant release notes, then pull and recreate:

cd /opt/containers/traefik-stack
docker compose pull
docker compose up -d --remove-orphans

Do not rely on latest for a reverse proxy that terminates TLS for all services.

6.2. Migrating `acme.json`

When moving this stack to a new server, decide deliberately whether to migrate the existing ACME store:

Copying traefik/certs/acme.json preserves existing certificates and avoids unnecessary Let’s Encrypt reissuance during cutover.
Starting with an empty acme.json is clean, but can hit rate limits if many domains are reissued repeatedly.

If you copy it, preserve permissions:

sudo chown root:root traefik/certs/acme.json
sudo chmod 600 traefik/certs/acme.json

6.3. Log Rotation (Critical for Production)

⚠️ DON'T SKIP THIS
This setup generates detailed JSON access logs for CrowdSec analysis. Without proper log rotation, Traefik logs alone can consume 70+ GB within weeks on a busy server. Docker container logs can add another 40+ GB. Configure rotation before going to production.

Docker Global Log Rotation

Configure Docker to automatically rotate all container logs by editing /etc/docker/daemon.json:

sudo tee /etc/docker/daemon.json > /dev/null << 'EOF'
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
EOF

Apply the changes:

sudo systemctl restart docker
docker info | grep -A3 "Logging Driver"

ℹ️ EXISTING CONTAINERS
This setting only applies to newly created containers. Existing containers keep their old logging configuration. Recreate them with `docker compose up -d --force-recreate` to apply the new limits.

Traefik Host Log Rotation

Since Traefik writes logs directly to the host filesystem, use logrotate.

⚠️ PATH VERIFICATION
Ensure the path in the config below matches your host path where the logs are stored. You can find it by running: `docker inspect traefik --format '{{range .Mounts}}{{.Source}}{{"\n"}}{{end}}' \| grep logs`

sudo tee /etc/logrotate.d/traefik > /dev/null << 'EOF'
/opt/containers/traefik-stack/traefik/logs/*.log {
  daily
  rotate 7
  compress
  delaycompress
  missingok
  notifempty
  copytruncate
  maxsize 50M
}
EOF

Verify Log Rotation

To ensure your rotation is working correctly and to troubleshoot issues, use these commands:

# Debug: show which rules would apply without actually rotating
sudo logrotate -d /etc/logrotate.d/traefik

# Force rotation: execute immediately
sudo logrotate -f /etc/logrotate.d/traefik

# Check rotation status: see when logs were last rotated
sudo cat /var/lib/logrotate/status | grep "traefik"

7. Troubleshooting: Disk Full

If your server runs out of disk space, logs are usually the culprit. Here’s how to diagnose and fix it.

7.1. Identify the Problem

# Quick overview
df -h

# Find large directories
du -h -d1 / 2>/dev/null | sort -h
du -h -d1 /var | sort -h
du -h -d1 /opt | sort -h

# Docker-specific
du -h -d1 /var/lib/docker | sort -h
du -h -d1 /var/lib/docker/containers | sort -h

# Find large container logs
find /var/lib/docker/containers -name '*-json.log' -exec du -h {} \; | sort -h

# Check journald (usually not the problem)
journalctl --disk-usage

7.2. Emergency Cleanup

⚠️ CAUTION
These commands delete log data permanently. Only proceed if you don’t need the logs for debugging.

Truncate Docker container logs:

sudo find /var/lib/docker/containers -name '*-json.log' -exec truncate -s 0 {} \;

Clear Traefik logs:

cd /opt/containers/traefik-stack
docker compose down
rm -rf traefik/logs/*
docker compose up -d

After cleanup, immediately configure log rotation as described in section 6.1 to prevent recurrence.

Conclusion

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.

As a next step, you might want to explore the AppSec (WAF) 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.

To add a central login with TOTP or WebAuthn to browser-based services, continue with Authelia with Docker Compose and Traefik: Lightweight SSO and 2FA. It reuses the proxy network, TLS resolver, security headers, and CrowdSec middleware from this stack.

📚TRAEFIK DOCUMENTATION 🛡️CROWDSEC DOCUMENTATION 🔐ADD AUTHELIA SSO + 2FA

Dark/Light-Mode Switcher for Arch Linux + i3wm

Unknown — Tue, 09 Jun 2026 00:00:00 +0000

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.

We will integrate GTK, Qt, terminal, and even CLI applications into our theme switcher, all controlled by a single keypress.

Changelog

Date	Change
2026-06-10	Design and Robustness Pass: WCAG-checked contrast fixes for NeoMutt and ikhal: neutral selection/status/search pairs, mail-state rows with adaptive backgrounds via a `reverse` trick, per-calendar ANSI accents and a clearer color hierarchy in ikhal — accent slots in a shared semantic palette are foreground-only. Unified the Dracula ANSI palette across OSC, Xresources, and Alacritty. i3 focus switched to a signal-red border with `default_border pixel 3`, urgent moved to orange. Polybar restart hardened (`enable-ipc` plus verified fallback), fixing intermittently vanishing bars after a toggle. Claude Code’s truecolor theme is switched per mode; nheko stays on `theme=system` (its built-in light theme hardcodes a dark Element-style sidebar, `#233649` — only `system` derives it from the Qt palette) and is stopped/restarted automatically per toggle because it persists settings on exit and mixes on live palette switches — the fresh window reappears in place on its old workspace via i3 layout-restore swallow placeholders (`restart_app_in_place`); tray applets are restarted toggle-proof, the light mode uses an icon-theme variant with dark panel icons (Papirus ships white panel icons by design), and the Nextcloud and KeePassXC tray icons switched to mode-independent colorful variants. NeoMutt’s cursor row moved to its own background pair (markers must never share one), and sonicradio settled on one constant theme whose built-in dark/light profiles are both high-contrast and survive its config write-back. Root-caused a class of “GUI relaunch crashes silently”: `darkman.service` starts before the display manager exports `DISPLAY`/`XAUTHORITY` — the X-environment import in Step 9 is now documented as required, plus a fallback in the hooks.
2026-06-09	TUI Live-Reload Strategies: NeoMutt and ikhal converted to semantic 16-color palettes with `SIGWINCH` redraw, so running sessions repaint live when the hooks change the terminal palette via OSC; `jellyfin-tui` keeps a stable `Mode Switcher` theme rewritten in the live-watched `config.yaml`, plus an after-exit preference rewrite and high-contrast palettes. Fixes from testing real sessions: NeoMutt DirectColor and regex pitfalls, Dunst live reload, Rofi theme switching, Xresources `-load` instead of `-merge`, targeted urxvt/Alacritty OSC recoloring, Polybar tray preservation, and stronger Light-mode contrast.
2026-06-04	Technical Review: Hardened portal, Alacritty, Qt, Polybar, Chromium, and hook-script guidance after implementation review.
2026-05-04	Initial Version: Comprehensive guide for Dark/Light-Mode switching on Arch Linux and i3wm.

Architectural Overview

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 orchestrator architecture that uses darkman as the central control unit.

darkman performs two main tasks:

It executes your customized hook scripts, which adapt specific applications and environments.
It propagates the dark mode status via the XDG-Desktop-Portal to modern applications (e.g., Firefox, Thunderbird). The portal signal is live; whether the visible app chrome also repaints live depends on the application.

$mod+Shift+d  →  darkman toggle  →  Hook Scripts  →  Individual Apps
                       │
                       └──► XDG-Portal (Firefox, Thunderbird, etc. via Signal)

Quickstart (Copy & Paste)

If you want the shortest path to the core setup — GTK config + XDG portal + i3 + Alacritty controlled by $mod+Shift+d — use this Quickstart as the bootstrap. It prepares the required packages, portal configuration, theme directories, terminal theme files, and i3 binding. The visible switching behavior still depends on the i3 theme files, the Alacritty import line, and the hook scripts from the later steps.

# 1. Install prerequisites
sudo pacman -S darkman xdg-desktop-portal xdg-desktop-portal-gtk \
               jq ruby libnotify dunst alacritty xorg-xrdb
yay -S dracula-gtk-theme   # or fall back to Adwaita-dark (handled by hook)

# 2. Create directory layout
mkdir -p ~/.local/share/dark-mode.d \
         ~/.local/share/light-mode.d \
         ~/.config/themes/{dracula,solarized-light} \
         ~/.config/alacritty \
         ~/.config/xdg-desktop-portal

# 3. Tell xdg-desktop-portal to use darkman as the Settings backend.
#    REQUIRED since xdg-desktop-portal 1.17.0 — without this, Firefox &
#    other portal-aware apps will not see darkman's color-scheme.
#    default=gtk keeps the GTK portal as fallback for file choosers and
#    other portal interfaces that darkman does not implement.
cat > ~/.config/xdg-desktop-portal/portals.conf <<'EOF'
[preferred]
default=gtk
org.freedesktop.impl.portal.Settings=darkman
EOF

# 4. Pull terminal theme files
curl -fsSL https://raw.githubusercontent.com/dracula/alacritty/master/dracula.toml \
     -o ~/.config/themes/dracula/alacritty.toml
curl -fsSL https://raw.githubusercontent.com/alacritty/alacritty-theme/master/themes/solarized_light.toml \
     -o ~/.config/themes/solarized-light/alacritty.toml

# 5. Wire up i3 (idempotent — safe to run twice)
grep -q "bindsym \$mod+Shift+d exec --no-startup-id darkman toggle" ~/.config/i3/config \
    || echo 'bindsym $mod+Shift+d exec --no-startup-id darkman toggle' >> ~/.config/i3/config
grep -q "include ~/.config/i3/theme.conf" ~/.config/i3/config \
    || echo 'include ~/.config/i3/theme.conf' >> ~/.config/i3/config
i3-msg reload >/dev/null 2>&1 || true

# 6. Enable the service
systemctl --user enable --now darkman.service
systemctl --user restart xdg-desktop-portal.service 2>/dev/null || true

# 7. Quick smoke test
#    Note: these only have a *visible* effect after you create the
#    hook scripts in Steps 7 & 8. Until then darkman just flips an
#    internal flag — nothing recolors yet.
darkman get      # current mode
darkman toggle   # switch without using the keybinding

Then create the i3 theme stubs from Step 4, import the generated Alacritty theme file as shown in Step 10, and create the hook scripts from Step 7 and Step 8. After that, $mod+Shift+d should give you a working basic switch.

Expected result after Quickstart + Step 4 + Step 7/8 + Alacritty import: Pressing $mod+Shift+d (or running darkman toggle) should recolor i3 borders, switch the Alacritty theme without restarting the terminal, and update the XDG portal color-scheme for Firefox/Thunderbird. Firefox normally uses widget.use-xdg-desktop-portal.settings = 2 (“auto”); set it to 1 only if auto-detection does not pick up the portal on your system. Full Firefox chrome repainting can still require an app restart. If any of the core checks fail, see the Reality Check section.

Recommended Approach: Set up Step-by-Step

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.

Phase 1 — Basic: darkman + GTK config + XDG portal + i3 + Alacritty. These components are reliable and cover the majority of the switcher architecture.
Phase 2 — Extension: Polybar + VSCodium + neomutt. This requires a bit more configuration, but the functionality is stable.
Phase 3 — Problem Children: Qt apps such as nheko, KeePassXC when not set to Automatic, Chromium, generic GTK apps such as Thunar, Firefox chrome repainting, and urxvt live-reload. These applications can present app-specific challenges and should be tested separately.

Follow this tutorial linearly and test the functionality after each phase before moving on to the next.

Theme Choice: Dracula ↔ Solarized Light

For dark mode, we will use Dracula, a popular and well-supported theme. For the light mode counterpart, several options are available:

Solarized Light: A classic with well-documented color palettes for many tools, known for its good readability.
Catppuccin Latte: A modern alternative that aesthetically complements Catppuccin Mocha (if you decide to replace Dracula later).
GitHub Light: A pragmatic choice, as many editor themes and browser extensions are available for it.

This guide will use the Dracula ↔ Solarized Light pair.

Migrating from a hand-themed setup

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 with darkman in mind — applied to an existing setup, they will overwrite or symlink-replace several files without asking.

What the hooks will update in place

These files are changed on every toggle, but the hook examples below update only the relevant keys and preserve unrelated local settings:

~/.config/gtk-3.0/settings.ini and ~/.config/gtk-4.0/settings.ini — gtk-theme-name, gtk-icon-theme-name, and gtk-application-prefer-dark-theme are created or updated. Existing font, cursor, Xft, and other keys are preserved.
~/.config/qt5ct/qt5ct.conf, ~/.config/qt6ct/qt6ct.conf — color_scheme_path, custom_palette, and optionally icon_theme are created or updated. The rest of the file is preserved.
~/.config/VSCodium/User/settings.json — only the workbench.colorTheme key is updated via jq. Caveat: jq requires strict JSON. If your settings file contains JSONC-style comments or trailing commas, the hook will skip the change rather than rewrite the file.
~/.config/khal/config — [view] theme, [highlight_days], and semantic ANSI [palette] keys are updated. The section-aware helper is important here; a global string replacement can accidentally overwrite unrelated keys with the same name.
~/.config/dunst/dunstrc — only theme color keys such as frame_color, format, background, and foreground are updated, then Dunst is reloaded with dunstctl reload. Existing notification rules and sound scripts are preserved.
~/.config/jellyfin-tui/config.yaml, ~/.local/share/jellyfin-tui/preferences/*.json, and ~/.config/sonicRadio/config.json — only theme-related values are changed. jellyfin-tui can repaint live when it is already using the stable Mode Switcher theme; NeoMutt and ikhal can repaint live after they have loaded the semantic ANSI palette once. Other running TUI instances may still keep their current in-memory theme until restart or in-app theme selection.

What the hooks will replace via symlink (non-destructive but pathing changes)

These paths become symlinks pointing into ~/.config/themes/<theme>/. 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):

~/.Xresources
~/.config/i3/theme.conf
~/.config/polybar/colors.ini
~/.config/neomutt/colors or, in mutt-wizard style setups, ~/.config/mutt/theme.muttrc
~/.config/nvim/colorscheme.vim

~/.config/alacritty/theme.toml is handled differently: the hooks rewrite it as a regular file. In practice this is more reliable for Alacritty live reload than switching the target of a symlink.

What is changed system-wide via gsettings

org.gnome.desktop.interface gtk-theme and color-scheme — affects every GTK app on your system that reads gsettings, regardless of whether you intended to theme it through darkman.

What is NOT touched

Your main configuration files (~/.config/i3/config, ~/.config/alacritty/alacritty.toml, your Polybar bar layout, your .muttrc, your Neovim init, your shell rc files, Firefox profiles) are only referenced via include/import/source lines. They stay where they are. Chromium is intentionally treated as restart-only and is not changed by the default hooks.

One important exception to watch for in existing setups: remove hardcoded theme environment variables such as export GTK_THEME=Adwaita:dark from .profile, .xprofile, .zprofile, or display-manager startup scripts. They can override the hook result for newly started GTK applications and make Light mode appear broken.

Recommended: snapshot before the first toggle

mkdir -p ~/theme-switcher-backup
for path in \
    ~/.config/gtk-3.0 \
    ~/.config/gtk-4.0 \
    ~/.config/qt5ct \
    ~/.config/qt6ct \
    ~/.Xresources \
    ~/.config/VSCodium/User/settings.json
do
    [[ -e "$path" ]] && cp -a "$path" ~/theme-switcher-backup/
done

After the first toggle, diff what changed:

diff -r ~/theme-switcher-backup/gtk-3.0 ~/.config/gtk-3.0 || true

If you find that a setting still needs to switch with the theme, teach the hooks about that key explicitly — open the hook scripts in Step 7 and Step 8 and add another set_ini_key call for GTK/Qt-style INI files or another focused jq update for JSON files. Extend the hook deliberately instead of replacing whole application configs.

Step 1: Install Prerequisites

`darkman` and Portal Infrastructure

sudo pacman -S darkman xdg-desktop-portal xdg-desktop-portal-gtk jq ruby libnotify dunst
sudo pacman -S xorg-xrdb
systemctl --user enable --now darkman.service

jq is needed for patching JSON settings; ruby is used for YAML-aware jellyfin-tui theme updates.
libnotify enables notifications via notify-send; dunst is the notification daemon reloaded by the hooks.
xorg-xrdb provides xrdb for applying Xresources.

Configure xdg-desktop-portal to use darkman (REQUIRED)

This is the single most overlooked step in dark-mode setups. Since xdg-desktop-portal 1.17.0, the portal must be told which 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.

Create ~/.config/xdg-desktop-portal/portals.conf:

mkdir -p ~/.config/xdg-desktop-portal
cat > ~/.config/xdg-desktop-portal/portals.conf <<'EOF'
[preferred]
default=gtk
org.freedesktop.impl.portal.Settings=darkman
EOF

The default=gtk line matters: darkman only implements the Settings portal. Without a default backend, a user-level portals.conf can accidentally disable other portal interfaces such as file choosers.

You can verify the portal really hands darkman’s value to clients with:

gdbus call --session \
  --dest org.freedesktop.portal.Desktop \
  --object-path /org/freedesktop/portal/desktop \
  --method org.freedesktop.portal.Settings.ReadOne \
  org.freedesktop.appearance color-scheme

This should return a GVariant containing 1 (dark) or 2 (light), for example (<uint32 1>,). If it returns 0 (“no preference”) or fails, restart xdg-desktop-portal.service and verify that your user-level portals.conf is being read.

systemctl --user restart xdg-desktop-portal.service

Firefox-side counterpart: Current Firefox builds use widget.use-xdg-desktop-portal.settings = 2 as “auto”. That usually works for the Settings portal. If Firefox does not pick up the portal even though the gdbus check is correct, set this preference to 1 to force portal usage. This can still require restarting Firefox and does not guarantee that every browser chrome element repaints live.

For dotfile-managed systems, the forced setting can be made persistent in the active Firefox profile:

// ~/.mozilla/firefox/<profile>/user.js
user_pref("widget.use-xdg-desktop-portal.settings", 1);

GTK Theme

Dracula is not in the official Arch repository. You will need an AUR helper like yay or paru:

yay -S dracula-gtk-theme
# or: paru -S dracula-gtk-theme

If you prefer not to use an AUR helper, the setup will automatically fall back to Adwaita-dark and Adwaita respectively (see hook script).

Qt Control (for Phase 3)

sudo pacman -S qt5ct qt6ct kvantum

i3 Keybinding

Add the following keybinding to your i3 configuration file ~/.config/i3/config:

bindsym $mod+Shift+d exec --no-startup-id darkman toggle

Step 2: Create Directory Structure

A clean directory structure is crucial for maintainability:

mkdir -p ~/.local/share/dark-mode.d
mkdir -p ~/.local/share/light-mode.d
mkdir -p ~/.config/themes/{dracula,solarized-light}
mkdir -p ~/.config/qt5ct/colors ~/.config/qt6ct/colors

In the ~/.config/themes/ directory, theme-specific files for each application will be stored. The hook scripts will then create symlinks to most currently desired theme files. Alacritty is the exception: its imported theme file is rewritten as a regular file to make live reload more reliable.

Step 3: Prepare Qt Apps (KeePassXC, nheko)

Qt applications do not automatically follow GTK configuration or the XDG-Portal. You usually need to set the QT_QPA_PLATFORMTHEME environment variable before Qt applications are started.

Where to put the variable depends on how you start X:

Display managers such as LightDM, LXDM, SDDM, and GDM usually source ~/.xprofile.
startx/xinit setups only get ~/.xprofile if your ~/.xinitrc sources it before exec i3.
~/.config/environment.d/ is read by systemd --user, but it does not automatically update the environment of an already-started X session.

For an i3 + X11 setup, use one global baseline first:

# ~/.xprofile
export QT_QPA_PLATFORMTHEME=qt5ct:qt6ct

If you use startx, make sure ~/.xinitrc contains this before exec i3:

[ -f ~/.xprofile ] && . ~/.xprofile

Qt6 caveat: If Qt6 apps ignore theming (e.g., KeePassXC remains unstyled), test the app with qt6ct explicitly:
QT_QPA_PLATFORMTHEME=qt6ct keepassxc
On current Arch Qt packages, the combined qt5ct:qt6ct value lets Qt5 and Qt6 applications pick their matching platform theme plugin. If an individual app still ignores it, use a per-app wrapper or desktop file for that application.

For KeePassXC specifically, set View → Theme → Automatic once inside the application. On a portal-aware setup this allows KeePassXC to follow the dark/light switch live; a hardcoded ApplicationTheme=dark in ~/.config/keepassxc/keepassxc.ini will override the system value and make Light mode look broken.

The tray icon is a separate setting with the same trap: the monochrome variants (TrayIconAppearance=monochrome-dark/monochrome-light) are fixed to one color and disappear on one of the two bar backgrounds. The hooks set TrayIconAppearance=colorful, which is readable in both modes — it takes effect on the next KeePassXC start (the hooks never restart KeePassXC automatically, since that would lock your database).

Last-resort fallback: per-app wrapper

If neither global setup gets a stubborn Qt6 app to pick up the theme, set the variable just for that one app:

QT_QPA_PLATFORMTHEME=qt6ct keepassxc

You can wrap this in a small shell script and place it in ~/.local/bin/, or make a desktop file with the env-var prepended in Exec=. Inelegant, but reliable when the global escalation chain fails.

Obtain Qt Color Schemes

Qt color schemes are stored as .conf files under ~/.config/qt5ct/colors/ and ~/.config/qt6ct/colors/. Do not store them under /usr/share/qt5ct/colors/, as these directories are reserved for system defaults and can be overwritten by Pacman updates.

For Dracula, an official Qt5ct color scheme exists in the Dracula project:

curl -fsSL https://raw.githubusercontent.com/dracula/qt5/master/Dracula.conf \
     -o ~/.config/qt5ct/colors/Dracula.conf
cp ~/.config/qt5ct/colors/Dracula.conf ~/.config/qt6ct/colors/Dracula.conf

For Solarized Light, no official Qt5ct color scheme exists. The most reliable approach is to create one once via the GUI:

Run qt5ct from a terminal.
Tab “Style” → next to “Color scheme” click “Edit color scheme” → “Create”.
Set Window Background #fdf6e3, Window Text #586e75, Base #fdf6e3, Highlight #268bd2, etc. – the eight Solarized base values are documented at ethanschoonover.com/solarized.
Save as SolarizedLight.conf under ~/.config/qt5ct/colors/.
Copy the file to ~/.config/qt6ct/colors/SolarizedLight.conf.

Why not use a third-party Solarized Qt scheme? Various community ports exist, but their quality and maintenance vary, and the qt5ct .conf format is fairly strict. A one-time GUI creation gives you a result that exactly matches your other Solarized apps, without surprises.

Step 4: Split i3 Config

The i3 configuration cannot be recolored at runtime. You must switch it and reload.

Option A: include file (recommended, from i3 4.20)

Add the following line to ~/.config/i3/config:

include ~/.config/i3/theme.conf

Then create two theme-specific configuration files. Minimal working examples:

# Dracula i3 theme
cat > ~/.config/themes/dracula/i3-theme.conf <<'EOF'
# class                 border  bground text    indicator child_border
client.focused          #ff5555 #44475a #f8f8f2 #f1fa8c   #ff5555
client.focused_inactive #44475a #44475a #f8f8f2 #44475a   #44475a
client.unfocused        #282a36 #282a36 #bfbfbf #282a36   #282a36
client.urgent           #ffb86c #ffb86c #282a36 #ffb86c   #ffb86c
client.placeholder      #282a36 #282a36 #f8f8f2 #282a36   #282a36
client.background       #282a36
EOF

# Solarized Light i3 theme
cat > ~/.config/themes/solarized-light/i3-theme.conf <<'EOF'
# class                 border  bground text    indicator child_border
client.focused          #dc322f #eee8d5 #073642 #875f00   #dc322f
client.focused_inactive #93a1a1 #eee8d5 #586e75 #93a1a1   #93a1a1
client.unfocused        #fdf6e3 #fdf6e3 #93a1a1 #fdf6e3   #fdf6e3
client.urgent           #cb4b16 #cb4b16 #fdf6e3 #cb4b16   #cb4b16
client.placeholder      #fdf6e3 #fdf6e3 #586e75 #fdf6e3   #fdf6e3
client.background       #fdf6e3
EOF

The hook script will then symlink the correct file to ~/.config/i3/theme.conf and execute i3-msg reload.

The focused border is deliberately a strong signal red (#ff5555 / #dc322f): with muted slate or blue tones it is genuinely hard to tell which window has focus, in both modes. Urgent windows move to orange so the two states stay distinguishable. Pair this with a visible border width in your main config — with default_border pixel 1 even a red border is easy to miss:

default_border pixel 3

Option B: Symlink the entire config

If you prefer not to use the include directive, you can symlink the entire i3 configuration file. This is less flexible but also works.

Step 5: Integrate Polybar

Polybar loads its configuration at startup. There are two ways to restart Polybar:

Option 1: `polybar-msg cmd restart` (clean, from Polybar 3.6)

polybar-msg cmd restart

This requires enable-ipc = true in every [bar/...] section. Without it, polybar-msg fails and the hooks silently fall back to the kill-and-relaunch path on every toggle — which is exactly the path with intermittent failure modes (see below).

[bar/mybar]
enable-ipc = true

Option 2: `pkill` + Launch Script (universal)

pkill polybar
sleep 0.3
~/.config/polybar/launch.sh

Minimal theme files

You’ll already have a working Polybar configuration from your existing setup. Depending on the age of the setup, it may be ~/.config/polybar/config, ~/.config/polybar/config.ini, or started with an explicit -c path. The safest approach is to keep that bar layout intact, extract only the colors into theme-specific files, and include the active palette.

# Dracula Polybar palette
cat > ~/.config/themes/dracula/polybar.ini <<'EOF'
[colors]
background = #282a36
background-alt = #44475a
foreground = #f8f8f2
foreground-alt = #6272a4
primary = #bd93f9
secondary = #8be9fd
alert = #ff5555
disabled = #6272a4
EOF

# Solarized Light Polybar palette
cat > ~/.config/themes/solarized-light/polybar.ini <<'EOF'
[colors]
background = #fdf6e3
background-alt = #eee8d5
foreground = #586e75
foreground-alt = #93a1a1
primary = #268bd2
secondary = #2aa198
alert = #dc322f
disabled = #93a1a1
EOF

In your main Polybar config, reference the colors via:

include-file = ~/.config/polybar/colors.ini

Then remove or replace your old [colors] section, so the included file becomes the single source of color values. The hook script below will symlink ~/.config/polybar/colors.ini to one of the two palette files. If your setup deliberately keeps colors and bar layout in one file, you can instead maintain two full Polybar config files — but then adjust the hook paths accordingly. Do not blindly symlink config.ini on systems where Polybar actually reads ~/.config/polybar/config.

Also review your launch.sh: it should only start bars that are actually defined and whose monitors are connected. If you use the legacy Polybar systray, keep tray-position = right on exactly one active bar and leave secondary bars at tray-position = none. Do not accidentally replace an existing tray-enabled bar with none, or the small app/status icons will disappear after the next Polybar restart. When a hook starts Polybar from a service context, a detached launch such as setsid -f polybar mybar1 ... is more reliable than relying on interactive-shell disown.

One more tray pitfall: the icons inside the tray are drawn by the applets themselves (XEmbed), not by Polybar, and GTK applets load their icon theme once at startup. After a mode switch they keep the previous light/dark icon set — white icons from a dark icon theme become nearly invisible on a light bar. Plain i3 setups usually run no XSettings daemon that could propagate the change, so the hooks below simply restart the relevant applets (nm-applet, pasystray, flameshot); adjust the list to whatever actually sits in your tray.

Restarting alone is not enough if the icon theme itself has no light-bar variant. Panel/tray icons inside an icon theme have fixed colors: Papirus, for example, ships near-white (#dfdfdf) panel icons by design in both Papirus and Papirus-Dark — readable only on dark bars. For a light bar you must switch to the Papirus-Light variant (dark #444444 panel icons), so the hook’s icon-theme variable has to differ per mode (for example Papirus-Dark in the dark hook, Papirus-Light in the light hook). And apps with bundled monochrome tray icons ignore the icon theme entirely: the Nextcloud client’s mono icon assumes a dark bar, so the hooks set monoIcons=false in nextcloud.cfg — the colorful brand icon is readable in both modes and needs no per-mode restart.

Step 6: Chromium Flags

Chromium does not react to theme changes at runtime. It’s important to clearly separate two things:

UI-Dark-Mode: Affects the browser interface (toolbar, tabs, menus).
Webpage-Force-Dark: Forces a dark mode for every webpage. However, this can distort images, diagrams, and carefully designed pages.

Optional: fixed dark UI on next start

Chromium’s launcher reads ~/.config/chromium-flags.conf, but these flags apply only when Chromium starts. A permanently configured --force-dark-mode is therefore not a true light/dark toggle: it keeps Chromium dark even after the rest of the desktop switches back to light mode.

If you want a fixed dark Chromium UI, create the file ~/.config/chromium-flags.conf:

--force-dark-mode
--gtk-version=4

--gtk-version=4 asks Chromium to use its GTK4 integration path on builds that support it. Test it on your version; Chromium command-line flags change over time.

Optional: Additionally force dark content for webpages

If you want to force dark mode for webpage content as well, add:

--enable-features=WebContentsForceDark

Warning: This flag name has changed multiple times across Chromium versions (WebContentsForceDark, ForceWebContentsDarkMode, or only via chrome://flags). If it doesn’t work, check chrome://flags for “Force Dark Mode for Web Contents” and enable it there. The recommendation remains: only enable if you’re comfortable with potential content distortion.

A true live toggle is not practical here without a browser restart. For that reason, the hook scripts below leave Chromium alone by default.

Step 7: The Dark-Mode Hook Script

This script will be executed when darkman switches to dark mode. Create the file ~/.local/share/dark-mode.d/apply-theme:

A note on hook directory layout: This guide uses ~/.local/share/dark-mode.d/ and ~/.local/share/light-mode.d/, which the darkman(1) manpage describes as the legacy format (kept for backwards compatibility). The current format is a single ~/.local/share/darkman/ directory with one script that receives the mode as $1. 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 case "$1" in dark|light) ... esac.

#!/usr/bin/env bash
# Robustness: undefined vars are errors, but individual app errors
# should not abort the entire hook.
set -u
trap 'echo "Hook error in: $BASH_COMMAND" >&2' ERR

# darkman.service can start before the display manager has imported the X
# environment into the systemd user scope; without DISPLAY/XAUTHORITY every
# GUI applet relaunched by this hook crashes on startup and xrdb fails.
# (See Step 9 for the permanent session-side fix.)
[[ -n "${DISPLAY:-}" ]] || export DISPLAY=:0
if [[ -z "${XAUTHORITY:-}" ]]; then
    for xauth_candidate in "${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/lyxauth" "$HOME/.Xauthority"; do
        [[ -f "$xauth_candidate" ]] && export XAUTHORITY="$xauth_candidate" && break
    done
fi
# Session variables from ~/.xprofile are not visible inside the service
# either; without the platform theme, relaunched Qt apps (nheko) skip
# qt5ct/qt6ct entirely and fall back to unthemed Qt defaults.
export QT_QPA_PLATFORMTHEME="${QT_QPA_PLATFORMTHEME:-qt5ct:qt6ct}"

THEME_DIR="$HOME/.config/themes/dracula"
GTK_THEME="Dracula"
# Official Dracula ANSI values — keep these identical to the Xresources and
# Alacritty theme files, or live-recolored and freshly started terminals will
# show two different palettes side by side.
DRACULA_ANSI_OSC=$'\033]4;0;#21222c\007\033]4;1;#ff5555\007\033]4;2;#50fa7b\007\033]4;3;#f1fa8c\007\033]4;4;#bd93f9\007\033]4;5;#ff79c6\007\033]4;6;#8be9fd\007\033]4;7;#f8f8f2\007\033]4;8;#6272a4\007\033]4;9;#ff6e6e\007\033]4;10;#69ff94\007\033]4;11;#ffffa5\007\033]4;12;#d6acff\007\033]4;13;#ff92df\007\033]4;14;#a4ffff\007\033]4;15;#ffffff\007'

set_ini_key() {
    local config_file="$1"
    local section="$2"
    local key="$3"
    local value="$4"
    local tmp

    mkdir -p "$(dirname "$config_file")"
    [[ -f "$config_file" ]] || printf '[%s]\n' "$section" > "$config_file"

    tmp=$(mktemp)
    awk -v section="$section" -v key="$key" -v value="$value" '
        BEGIN { in_section=0; section_found=0; key_done=0 }
        $0 == "[" section "]" {
            in_section=1; section_found=1; print; next
        }
        /^[[:space:]]*\[/ {
            if (in_section && !key_done) {
                print key "=" value
                key_done=1
            }
            in_section=0
        }
        in_section && $0 ~ "^[[:space:]]*" key "[[:space:]]*=" {
            if (!key_done) {
                print key "=" value
                key_done=1
            }
            next
        }
        { print }
        END {
            if (!section_found) {
                print ""
                print "[" section "]"
                print key "=" value
            } else if (in_section && !key_done) {
                print key "=" value
            }
        }
    ' "$config_file" > "$tmp" && mv "$tmp" "$config_file" || rm -f "$tmp"
}

write_alacritty_theme() {
    local tmp

    mkdir -p "$HOME/.config/alacritty"
    tmp=$(mktemp "$HOME/.config/alacritty/theme.toml.XXXXXX")
    install -m 0644 "$THEME_DIR/alacritty.toml" "$tmp"
    mv -f "$tmp" "$HOME/.config/alacritty/theme.toml"
    touch "$HOME/.config/alacritty/alacritty.toml"
}

set_dunst_theme() {
    local config="$HOME/.config/dunst/dunstrc"

    [[ -f "$config" ]] || return 0

    set_ini_key "$config" global frame_color '"#bd93f9"'
    set_ini_key "$config" global separator_color '"#44475a"'
    set_ini_key "$config" global format "\"<span foreground='#f8f8f2'><b>%s %p</b></span>\\\\n%b\""
    sed -i '/^%b"$/d' "$config"
    set_ini_key "$config" urgency_low background '"#282a36"'
    set_ini_key "$config" urgency_low foreground '"#f8f8f2"'
    set_ini_key "$config" urgency_normal background '"#282a36"'
    set_ini_key "$config" urgency_normal foreground '"#f8f8f2"'
    set_ini_key "$config" urgency_critical background '"#ff5555"'
    set_ini_key "$config" urgency_critical foreground '"#f8f8f2"'
    set_ini_key "$config" urgency_critical frame_color '"#ff5555"'

    command -v dunstctl >/dev/null 2>&1 && dunstctl reload "$config" >/dev/null 2>&1 || true
}

recolor_child_ttys() {
    local terminal_comm="$1"
    local bg="$2"
    local fg="$3"
    local cursor="$4"
    local palette="${5:-}"
    local tty

    while IFS= read -r tty; do
        [[ -n "$tty" && -w "/dev/$tty" ]] || continue
        {
            printf '\033]708;%s\007\033]11;%s\007\033]10;%s\007\033]12;%s\007' \
                "$bg" "$bg" "$fg" "$cursor"
            [[ -n "$palette" ]] && printf '%s' "$palette"
        } > "/dev/$tty" 2>/dev/null || true
    done < <(
        ps -eo pid=,ppid=,tty=,comm= | awk -v terminal_comm="$terminal_comm" '
            {
                pid[NR]=$1; ppid[NR]=$2; tty[NR]=$3; comm[NR]=$4;
                parent[$1]=$2;
                if ($4 == terminal_comm) terminal[$1]=1;
            }
            END {
                for (i=1; i<=NR; i++) {
                    p=ppid[i];
                    while (p && p != "1") {
                        if (p in terminal) {
                            if (tty[i] ~ /^pts\//) print tty[i];
                            break;
                        }
                        p=parent[p];
                    }
                }
            }
        ' | sort -u
    )
}

redraw_tui_apps() {
    local pid

    command -v pgrep >/dev/null 2>&1 || return 0

    while IFS= read -r pid; do
        [[ -n "$pid" ]] && kill -WINCH "$pid" 2>/dev/null || true
    done < <(pgrep -x neomutt 2>/dev/null || true)

    while IFS= read -r pid; do
        [[ -n "$pid" ]] && kill -WINCH "$pid" 2>/dev/null || true
    done < <(pgrep -f '(^|[[:space:]])(/usr/bin/)?ikhal([[:space:]]|$)|(^|[[:space:]])khal[[:space:]]+interactive([[:space:]]|$)' 2>/dev/null || true)
}

# Restart a GUI app so its new window reappears exactly where the old one
# lived, on any workspace. Uses i3's native layout-restore mechanism: a
# placeholder container with swallow criteria is appended to the app's old
# workspace, and i3 materializes the next matching window directly inside
# it — no focus-dependent placement, no post-hoc moving. Apps that were
# not running are left closed.
restart_app_in_place() {
    local proc="$1" class="$2"
    local ws focused layout mark
    pgrep -x "$proc" >/dev/null 2>&1 || return 0
    mark="restore_${proc}"
    ws=""
    if command -v jq >/dev/null 2>&1 && command -v i3-msg >/dev/null 2>&1; then
        ws=$(i3-msg -t get_tree 2>/dev/null | jq -r --arg c "$class" '
            recurse(.nodes[]?, .floating_nodes[]?)
            | select(.type? == "workspace") | . as $ws
            | recurse(.nodes[]?, .floating_nodes[]?)
            | select((.window_properties.class? // "") == $c)
            | $ws.name' 2>/dev/null | head -n1)
    fi
    pkill -x "$proc" 2>/dev/null || true
    for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do
        pgrep -x "$proc" >/dev/null 2>&1 || break
        sleep 0.5
    done
    pkill -9 -x "$proc" 2>/dev/null || true
    if [[ -n "$ws" ]]; then
        layout=$(mktemp --suffix=.json)
        printf '{"marks":["%s"],"swallows":[{"class":"^%s$"}]}\n' "$mark" "$class" > "$layout"
        focused=$(i3-msg -t get_workspaces 2>/dev/null | jq -r '.[] | select(.focused) | .name')
        i3-msg "unmark \"$mark\"" >/dev/null 2>&1
        if [[ "$ws" == "$focused" ]]; then
            i3-msg "append_layout $layout" >/dev/null 2>&1
        else
            i3-msg "workspace --no-auto-back-and-forth \"$ws\"; append_layout $layout; workspace --no-auto-back-and-forth \"$focused\"" >/dev/null 2>&1
        fi
        rm -f "$layout"
        # Remove the empty placeholder if the app fails to come back.
        (
            sleep 25
            pgrep -x "$proc" >/dev/null 2>&1 \
                || i3-msg "[con_mark=\"$mark\"] kill" >/dev/null 2>&1
        ) >/dev/null 2>&1 &
    fi
    command -v "$proc" >/dev/null 2>&1 && setsid -f "$proc" >/dev/null 2>&1
}

# Fallback if dracula-gtk-theme is not installed
if ! [[ -d /usr/share/themes/Dracula || -d ~/.themes/Dracula ]]; then
    GTK_THEME="Adwaita-dark"
fi

# ─── GTK 3 / GTK 4 ──────────────────────────────────────────────
# Update only theme-related keys; preserve font, cursor, Xft and other local settings.
for gtk_file in ~/.config/gtk-3.0/settings.ini ~/.config/gtk-4.0/settings.ini; do
    set_ini_key "$gtk_file" Settings gtk-theme-name "$GTK_THEME"
    set_ini_key "$gtk_file" Settings gtk-icon-theme-name Adwaita
    set_ini_key "$gtk_file" Settings gtk-application-prefer-dark-theme 1
done

# Also via gsettings (for apps that read this)
gsettings set org.gnome.desktop.interface gtk-theme "$GTK_THEME" 2>/dev/null || true
gsettings set org.gnome.desktop.interface color-scheme 'prefer-dark' 2>/dev/null || true

# ─── Qt5 / Qt6 ──────────────────────────────────────────────────
# Redirect color scheme paths in user config, not /usr/share.
set_ini_key "$HOME/.config/qt5ct/qt5ct.conf" Appearance color_scheme_path "$HOME/.config/qt5ct/colors/Dracula.conf"
set_ini_key "$HOME/.config/qt5ct/qt5ct.conf" Appearance custom_palette true
set_ini_key "$HOME/.config/qt6ct/qt6ct.conf" Appearance color_scheme_path "$HOME/.config/qt6ct/colors/Dracula.conf"
set_ini_key "$HOME/.config/qt6ct/qt6ct.conf" Appearance custom_palette true

# Nextcloud client: the monochrome tray icon guesses light-on-dark and is
# unreadable on a light bar; the colorful brand icon works in both modes.
if [[ -f ~/.config/Nextcloud/nextcloud.cfg ]]; then
    set_ini_key ~/.config/Nextcloud/nextcloud.cfg General monoIcons false
fi

# KeePassXC follows the portal/system switch live when its in-app theme is "Automatic".
if [[ -f ~/.config/keepassxc/keepassxc.ini ]]; then
    set_ini_key ~/.config/keepassxc/keepassxc.ini GUI ApplicationTheme auto
    # The monochrome tray variants are FIXED light or dark and vanish on
    # one of the two bars; the colorful icon is readable in both modes.
    # Applied on the next KeePassXC start (no auto-restart: open database).
    set_ini_key ~/.config/keepassxc/keepassxc.ini GUI TrayIconAppearance colorful
fi

# nheko: keep theme=system. Its built-in light theme hardcodes a DARK
# sidebar (#233649, Element-style) — only theme=system derives the sidebar
# and scrollbars from the Qt palette, which qt6ct supplies per mode. A live
# palette switch leaves a running instance mixed, so restart it in place.
# theme=system is also what nheko writes back on exit, so the value
# survives its settings persistence without ordering tricks.
if [[ -f ~/.config/nheko/nheko.conf ]]; then
    set_ini_key ~/.config/nheko/nheko.conf user theme system
    restart_app_in_place nheko nheko
fi

# ─── khal / ikhal ───────────────────────────────────────────────
if [[ -f ~/.config/khal/config ]]; then
    set_ini_key ~/.config/khal/config view theme dark
    set_ini_key ~/.config/khal/config view frame width
    set_ini_key ~/.config/khal/config highlight_days method fg
    set_ini_key ~/.config/khal/config highlight_days multiple brown
    # Days with events from exactly two calendars show both colors as
    # half-and-half; three or more fall back to the "multiple" color.
    set_ini_key ~/.config/khal/config highlight_days multiple_on_overflow True
    # Empty color keeps per-calendar day colors in the month view; the
    # [palette] overrides below remap them to adaptive ANSI accents.
    set_ini_key ~/.config/khal/config highlight_days color ""
    set_ini_key ~/.config/khal/config palette header "'', '', ''"
    set_ini_key ~/.config/khal/config palette footer "'', '', ''"
    set_ini_key ~/.config/khal/config palette "line header" "dark blue, '', bold"
    set_ini_key ~/.config/khal/config palette "alt header" "dark blue, '', bold"
    set_ini_key ~/.config/khal/config palette bright "dark blue, '', bold"
    set_ini_key ~/.config/khal/config palette list "'', '', ''"
    set_ini_key ~/.config/khal/config palette "list focused" "white, black, bold"
    set_ini_key ~/.config/khal/config palette edit "'', '', ''"
    set_ini_key ~/.config/khal/config palette "edit focus" "white, black, bold"
    set_ini_key ~/.config/khal/config palette button "black, light gray, ''"
    set_ini_key ~/.config/khal/config palette "button focused" "white, black, bold"
    set_ini_key ~/.config/khal/config palette "reveal focus" "white, black, standout"
    set_ini_key ~/.config/khal/config palette "today focus" "white, black, standout"
    set_ini_key ~/.config/khal/config palette today "black, light gray, ''"
    set_ini_key ~/.config/khal/config palette "date header" "light red, '', ''"
    set_ini_key ~/.config/khal/config palette "date header focused" "white, black, bold"
    set_ini_key ~/.config/khal/config palette "date header selected" "white, black, ''"
    set_ini_key ~/.config/khal/config palette dayname "dark cyan, '', ''"
    set_ini_key ~/.config/khal/config palette monthname "dark magenta, '', ''"
    set_ini_key ~/.config/khal/config palette weeknumber_right "dark gray, '', ''"
    set_ini_key ~/.config/khal/config palette alert "white, dark red, bold"
    set_ini_key ~/.config/khal/config palette mark "white, dark gray, bold"
    set_ini_key ~/.config/khal/config palette frame "dark gray, '', ''"
    set_ini_key ~/.config/khal/config palette "frame focus" "dark blue, '', ''"
    set_ini_key ~/.config/khal/config palette "frame focus color" "dark blue, '', ''"
    set_ini_key ~/.config/khal/config palette "frame focus top" "dark magenta, '', ''"
    set_ini_key ~/.config/khal/config palette eventcolumn "'', '', ''"
    set_ini_key ~/.config/khal/config palette "eventcolumn focus" "'', '', ''"
    set_ini_key ~/.config/khal/config palette calendar "'', '', ''"
    # Default like khal's built-in themes: a color here washes over every
    # plain day whenever the calendar column holds focus.
    set_ini_key ~/.config/khal/config palette "calendar focus" "'', '', ''"
    set_ini_key ~/.config/khal/config palette editbx "white, black, ''"
    set_ini_key ~/.config/khal/config palette editcp "black, light gray, standout"
    set_ini_key ~/.config/khal/config palette popupbg "'', '', ''"
    set_ini_key ~/.config/khal/config palette popupper "white, black, bold"
    set_ini_key ~/.config/khal/config palette caption "dark blue, '', bold"
    # Per-calendar accents for month-view day numbers and event-list rows
    # (both share the "calendar <name>" attributes, ikhal merges the config
    # palette last): ANSI names track the terminal palette live, unlike
    # static RGB values from vdir `color` files. The attribute names must
    # match the discovered calendar names from `khal printcalendars`.
    set_ini_key ~/.config/khal/config palette "calendar personal" "dark blue, '', ''"
    set_ini_key ~/.config/khal/config palette "calendar work" "dark magenta, '', ''"
fi

# ─── Xresources / urxvt ─────────────────────────────────────────
ln -sf "$THEME_DIR/Xresources" ~/.Xresources
command -v xrdb >/dev/null 2>&1 && xrdb -load ~/.Xresources

# Recolor only PTSes whose process ancestry belongs to the terminal.
# This changes Background/Foreground/Cursor and the 16-color ANSI palette
# where the terminal supports OSC 4.
if [[ "${RECOLOR_URXVT_PTS:-1}" == "1" ]]; then
    recolor_child_ttys "urxvt" "#282a36" "#f8f8f2" "#f8f8f2" "$DRACULA_ANSI_OSC"
fi
if [[ "${RECOLOR_ALACRITTY_PTS:-1}" == "1" ]]; then
    recolor_child_ttys "alacritty" "#282a36" "#f8f8f2" "#f8f8f2" "$DRACULA_ANSI_OSC"
fi
redraw_tui_apps

# ─── Alacritty ──────────────────────────────────────────────────
write_alacritty_theme
# Alacritty reloads automatically with live_config_reload=true

# ─── i3 Theme ───────────────────────────────────────────────────
mkdir -p ~/.config/i3
ln -sf "$THEME_DIR/i3-theme.conf" ~/.config/i3/theme.conf
command -v i3-msg >/dev/null 2>&1 && i3-msg reload >/dev/null 2>&1 || true

# ─── Polybar ────────────────────────────────────────────────────
mkdir -p ~/.config/polybar
ln -sf "$THEME_DIR/polybar.ini" ~/.config/polybar/colors.ini
# IPC restart first (needs enable-ipc=true per bar); fall back to a kill
# that waits until the old instances are really gone, then verify the bars
# came up — polybar's monitor detection can fail transiently right after
# an i3 reload, which can otherwise leave the desktop without any bar.
restart_polybar() {
    local i
    if command -v polybar-msg >/dev/null 2>&1 && polybar-msg cmd restart >/dev/null 2>&1; then
        sleep 1
        pgrep -x polybar >/dev/null 2>&1 && return 0
    fi
    pkill -x polybar 2>/dev/null || true
    for i in 1 2 3 4 5 6 7 8 9 10; do
        pgrep -x polybar >/dev/null 2>&1 || break
        sleep 0.2
    done
    if [[ -x ~/.config/polybar/launch.sh ]]; then
        setsid -f ~/.config/polybar/launch.sh >/dev/null 2>&1
        sleep 1
        pgrep -x polybar >/dev/null 2>&1 \
            || setsid -f ~/.config/polybar/launch.sh >/dev/null 2>&1
    fi
}
restart_polybar

# Fixed list of the applets that belong in this machine's tray. Tray icons
# are drawn by the applets (XEmbed) with the GTK icon theme they loaded at
# startup, so they must be restarted to match the new mode. Two pitfalls
# shape this function: XEmbed applets exit immediately when they dock into
# a tray that is still re-initializing after the Polybar restart (hence
# the delay and the safety net), and rapid consecutive toggles can kill
# applets a previous hook run just started (hence "ensure running" with a
# fixed list instead of "only restart what was running").
TRAY_APPS="nm-applet pasystray flameshot"
restart_tray_apps() {
    local app
    for app in $TRAY_APPS; do
        pkill -x "$app" 2>/dev/null || true
    done
    sleep 2
    for app in $TRAY_APPS; do
        command -v "$app" >/dev/null 2>&1 || continue
        pgrep -x "$app" >/dev/null 2>&1 || setsid -f "$app" >/dev/null 2>&1
    done
    # Safety net: relaunch anything that died docking too early.
    (
        sleep 5
        for app in $TRAY_APPS; do
            command -v "$app" >/dev/null 2>&1 || continue
            pgrep -x "$app" >/dev/null 2>&1 || setsid -f "$app" >/dev/null 2>&1
        done
    ) >/dev/null 2>&1 &
}
restart_tray_apps

# ─── Rofi ───────────────────────────────────────────────────────
# Rofi reads its theme on startup; existing menus are transient.
mkdir -p ~/.config/rofi
ln -sf "$THEME_DIR/rofi.rasi" ~/.config/rofi/theme.rasi

# ─── neomutt ────────────────────────────────────────────────────
mkdir -p ~/.config/neomutt
ln -sf "$THEME_DIR/mutt-colors" ~/.config/neomutt/colors
# Existing sessions repaint live after they have loaded this ANSI palette once.

# mutt-wizard style setups often use ~/.config/mutt/muttrc instead.
# Add `source ~/.config/mutt/theme.muttrc` there, then let the hook manage:
if [[ -d ~/.config/mutt ]]; then
    ln -sf "$THEME_DIR/mutt-colors" ~/.config/mutt/theme.muttrc
fi

# ─── jellyfin-tui ───────────────────────────────────────────────
set_jellyfin_tui_preference() {
    local theme="$1"

    [[ -d "$HOME/.local/share/jellyfin-tui/preferences" ]] || return 0
    command -v jq >/dev/null 2>&1 || return 0

    for pref in "$HOME"/.local/share/jellyfin-tui/preferences/*.json; do
        [[ -f "$pref" ]] || continue
        tmp=$(mktemp)
        jq --arg theme "$theme" '.theme = $theme' "$pref" > "$tmp" && mv "$tmp" "$pref" || rm -f "$tmp"
    done
}

set_jellyfin_tui_config_theme() {
    local mode="$1"
    local config="$HOME/.config/jellyfin-tui/config.yaml"

    [[ -f "$config" ]] || return 0
    command -v ruby >/dev/null 2>&1 || return 0

    ruby - "$config" "$mode" <<'RUBY'
require "yaml"

path, mode = ARGV
cfg = YAML.load_file(path) || {}

dark = {
  "base" => "Dark",
  "background" => "#282a36",
  "foreground" => "#f8f8f2",
  "foreground_secondary" => "#d7d8e8",
  "foreground_dim" => "#a7abc4",
  "foreground_disabled" => "#6f758f",
  "section_title" => "#bd93f9",
  "accent" => "#8be9fd",
  "border" => "#4f5268",
  "border_focused" => "#bd93f9",
  "selected_active_background" => "#44475a",
  "selected_active_foreground" => "#f8f8f2",
  "selected_inactive_background" => "#343746",
  "selected_inactive_foreground" => "#f8f8f2",
  "scrollbar_thumb" => "#c6c8d6",
  "scrollbar_track" => "#44475a",
  "progress_fill" => "#ffb86c",
  "progress_track" => "#44475a",
  "tab_active_foreground" => "#bd93f9",
  "tab_inactive_foreground" => "#7b819d",
  "album_header_background" => "#343746",
  "album_header_foreground" => "#8be9fd"
}

light = {
  "base" => "Light",
  "background" => "#fdf6e3",
  "foreground" => "#073642",
  "foreground_secondary" => "#25464d",
  "foreground_dim" => "#405f66",
  "foreground_disabled" => "#586e75",
  "section_title" => "#005f87",
  "accent" => "#005f87",
  "border" => "#586e75",
  "border_focused" => "#005f87",
  "selected_active_background" => "#005f87",
  "selected_active_foreground" => "#fdf6e3",
  "selected_inactive_background" => "#d7ebe8",
  "selected_inactive_foreground" => "#073642",
  "scrollbar_thumb" => "#586e75",
  "scrollbar_track" => "#eee8d5",
  "progress_fill" => "#875f00",
  "progress_track" => "#d6cab0",
  "tab_active_foreground" => "#005f87",
  "tab_inactive_foreground" => "#586e75",
  "album_header_background" => "#eee8d5",
  "album_header_foreground" => "#073642"
}

palette = mode == "light" ? light : dark
managed_names = ["Mode Switcher", "Dracula High Contrast", "Solarized Light High Contrast"]
themes = cfg["themes"].is_a?(Array) ? cfg["themes"] : []
unmanaged = themes.reject { |theme| theme.is_a?(Hash) && managed_names.include?(theme["name"]) }

cfg["auto_color"] = false
cfg["themes"] = managed_names.map { |name| { "name" => name }.merge(palette) } + unmanaged

content = YAML.dump(cfg)
if !File.exist?(path) || File.read(path) != content
  mode_bits = File.exist?(path) ? File.stat(path).mode & 0o777 : 0o600
  tmp = "#{path}.tmp.#{$$}"
  File.write(tmp, content)
  File.chmod(mode_bits, tmp)
  File.rename(tmp, path)
end
RUBY
}

# jellyfin-tui live-reloads config.yaml, but not its preferences file.
# Keep one stable selected theme and rewrite that theme's colors per mode.
set_jellyfin_tui_preference "Mode Switcher"
set_jellyfin_tui_config_theme "dark"
if pgrep -x jellyfin-tui >/dev/null 2>&1; then
    (
        while pgrep -x jellyfin-tui >/dev/null 2>&1; do
            sleep 0.5
        done
        set_jellyfin_tui_preference "Mode Switcher"
    ) >/dev/null 2>&1 &
fi

# ─── sonicradio ─────────────────────────────────────────────────
# Every built-in theme ships separate dark and light profiles, picked from
# the terminal background at startup. A constant high-contrast theme works
# for both modes and survives sonicradio's config write-back on exit.
if [[ -f ~/.config/sonicRadio/config.json ]] && command -v jq >/dev/null 2>&1; then
    tmp=$(mktemp)
    jq '.theme = 4' ~/.config/sonicRadio/config.json > "$tmp" \
        && mv "$tmp" ~/.config/sonicRadio/config.json \
        || rm -f "$tmp"
fi

# ─── VSCodium ───────────────────────────────────────────────────
# Patch settings.json. VSCodium usually reacts live via file watcher,
# in rare cases a "Reload Window" (Ctrl+Shift+P) is needed.
SETTINGS="$HOME/.config/VSCodium/User/settings.json"
if [[ -f "$SETTINGS" ]] && command -v jq >/dev/null 2>&1; then
    tmp=$(mktemp)
    jq '."workbench.colorTheme" = "Dracula"' "$SETTINGS" > "$tmp" \
        && mv "$tmp" "$SETTINGS" \
        || rm -f "$tmp"
fi

# ─── Claude Code ────────────────────────────────────────────────
# Claude Code paints its UI with truecolor values from its own theme and
# ignores the terminal palette. Running sessions keep their theme until
# restarted (or changed in-session via /config).
CLAUDE_SETTINGS="$HOME/.claude/settings.json"
if [[ -f "$CLAUDE_SETTINGS" ]] && command -v jq >/dev/null 2>&1; then
    tmp=$(mktemp)
    jq '.theme = "dark"' "$CLAUDE_SETTINGS" > "$tmp" && mv "$tmp" "$CLAUDE_SETTINGS" || rm -f "$tmp"
fi

# ─── Vim/Neovim (if used) ───────────────────────────────────────
mkdir -p ~/.config/nvim
ln -sf "$THEME_DIR/nvim-colorscheme.vim" ~/.config/nvim/colorscheme.vim 2>/dev/null || true

# ─── Firefox / Thunderbird ──────────────────────────────────────
# Nothing to do in the hook: the portal value is updated by darkman.
# Firefox default "auto" is usually enough; force
# widget.use-xdg-desktop-portal.settings = 1 only if auto does not work.
# Full browser UI repainting may still require a Firefox restart.

# ─── Chromium ───────────────────────────────────────────────────
# Does not react live; flags in ~/.config/chromium-flags.conf take effect
# on next start. See Step 6.

# ─── User Notification ──────────────────────────────────────────
set_dunst_theme
notify-send -i weather-clear-night "Theme" "Dark Mode activated (Dracula)" 2>/dev/null || true
echo "Dark mode activated (Dracula)"

Make the script executable:

chmod +x ~/.local/share/dark-mode.d/apply-theme

Step 8: The Light-Mode Hook Script

This script will be executed when darkman switches to light mode. Create the file ~/.local/share/light-mode.d/apply-theme:

#!/usr/bin/env bash
set -u
trap 'echo "Hook error in: $BASH_COMMAND" >&2' ERR

# darkman.service can start before the display manager has imported the X
# environment into the systemd user scope; without DISPLAY/XAUTHORITY every
# GUI applet relaunched by this hook crashes on startup and xrdb fails.
# (See Step 9 for the permanent session-side fix.)
[[ -n "${DISPLAY:-}" ]] || export DISPLAY=:0
if [[ -z "${XAUTHORITY:-}" ]]; then
    for xauth_candidate in "${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/lyxauth" "$HOME/.Xauthority"; do
        [[ -f "$xauth_candidate" ]] && export XAUTHORITY="$xauth_candidate" && break
    done
fi
# Session variables from ~/.xprofile are not visible inside the service
# either; without the platform theme, relaunched Qt apps (nheko) skip
# qt5ct/qt6ct entirely and fall back to unthemed Qt defaults.
export QT_QPA_PLATFORMTHEME="${QT_QPA_PLATFORMTHEME:-qt5ct:qt6ct}"

THEME_DIR="$HOME/.config/themes/solarized-light"
GTK_THEME="Adwaita"
SOLARIZED_LIGHT_ANSI_OSC=$'\033]4;0;#073642\007\033]4;1;#dc322f\007\033]4;2;#5f8700\007\033]4;3;#875f00\007\033]4;4;#005f87\007\033]4;5;#af005f\007\033]4;6;#006c6b\007\033]4;7;#eee8d5\007\033]4;8;#002b36\007\033]4;9;#cb4b16\007\033]4;10;#586e00\007\033]4;11;#6c5a00\007\033]4;12;#00629d\007\033]4;13;#6c71c4\007\033]4;14;#00736f\007\033]4;15;#fdf6e3\007'

set_ini_key() {
    local config_file="$1"
    local section="$2"
    local key="$3"
    local value="$4"
    local tmp

    mkdir -p "$(dirname "$config_file")"
    [[ -f "$config_file" ]] || printf '[%s]\n' "$section" > "$config_file"

    tmp=$(mktemp)
    awk -v section="$section" -v key="$key" -v value="$value" '
        BEGIN { in_section=0; section_found=0; key_done=0 }
        $0 == "[" section "]" {
            in_section=1; section_found=1; print; next
        }
        /^[[:space:]]*\[/ {
            if (in_section && !key_done) {
                print key "=" value
                key_done=1
            }
            in_section=0
        }
        in_section && $0 ~ "^[[:space:]]*" key "[[:space:]]*=" {
            if (!key_done) {
                print key "=" value
                key_done=1
            }
            next
        }
        { print }
        END {
            if (!section_found) {
                print ""
                print "[" section "]"
                print key "=" value
            } else if (in_section && !key_done) {
                print key "=" value
            }
        }
    ' "$config_file" > "$tmp" && mv "$tmp" "$config_file" || rm -f "$tmp"
}

write_alacritty_theme() {
    local tmp

    mkdir -p "$HOME/.config/alacritty"
    tmp=$(mktemp "$HOME/.config/alacritty/theme.toml.XXXXXX")
    install -m 0644 "$THEME_DIR/alacritty.toml" "$tmp"
    mv -f "$tmp" "$HOME/.config/alacritty/theme.toml"
    touch "$HOME/.config/alacritty/alacritty.toml"
}

recolor_child_ttys() {
    local terminal_comm="$1"
    local bg="$2"
    local fg="$3"
    local cursor="$4"
    local palette="${5:-}"
    local tty

    while IFS= read -r tty; do
        [[ -n "$tty" && -w "/dev/$tty" ]] || continue
        {
            printf '\033]708;%s\007\033]11;%s\007\033]10;%s\007\033]12;%s\007' \
                "$bg" "$bg" "$fg" "$cursor"
            [[ -n "$palette" ]] && printf '%s' "$palette"
        } > "/dev/$tty" 2>/dev/null || true
    done < <(
        ps -eo pid=,ppid=,tty=,comm= | awk -v terminal_comm="$terminal_comm" '
            {
                pid[NR]=$1; ppid[NR]=$2; tty[NR]=$3; comm[NR]=$4;
                parent[$1]=$2;
                if ($4 == terminal_comm) terminal[$1]=1;
            }
            END {
                for (i=1; i<=NR; i++) {
                    p=ppid[i];
                    while (p && p != "1") {
                        if (p in terminal) {
                            if (tty[i] ~ /^pts\//) print tty[i];
                            break;
                        }
                        p=parent[p];
                    }
                }
            }
        ' | sort -u
    )
}

redraw_tui_apps() {
    local pid

    command -v pgrep >/dev/null 2>&1 || return 0

    while IFS= read -r pid; do
        [[ -n "$pid" ]] && kill -WINCH "$pid" 2>/dev/null || true
    done < <(pgrep -x neomutt 2>/dev/null || true)

    while IFS= read -r pid; do
        [[ -n "$pid" ]] && kill -WINCH "$pid" 2>/dev/null || true
    done < <(pgrep -f '(^|[[:space:]])(/usr/bin/)?ikhal([[:space:]]|$)|(^|[[:space:]])khal[[:space:]]+interactive([[:space:]]|$)' 2>/dev/null || true)
}

# Restart a GUI app so its new window reappears exactly where the old one
# lived, on any workspace. Uses i3's native layout-restore mechanism: a
# placeholder container with swallow criteria is appended to the app's old
# workspace, and i3 materializes the next matching window directly inside
# it — no focus-dependent placement, no post-hoc moving. Apps that were
# not running are left closed.
restart_app_in_place() {
    local proc="$1" class="$2"
    local ws focused layout mark
    pgrep -x "$proc" >/dev/null 2>&1 || return 0
    mark="restore_${proc}"
    ws=""
    if command -v jq >/dev/null 2>&1 && command -v i3-msg >/dev/null 2>&1; then
        ws=$(i3-msg -t get_tree 2>/dev/null | jq -r --arg c "$class" '
            recurse(.nodes[]?, .floating_nodes[]?)
            | select(.type? == "workspace") | . as $ws
            | recurse(.nodes[]?, .floating_nodes[]?)
            | select((.window_properties.class? // "") == $c)
            | $ws.name' 2>/dev/null | head -n1)
    fi
    pkill -x "$proc" 2>/dev/null || true
    for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do
        pgrep -x "$proc" >/dev/null 2>&1 || break
        sleep 0.5
    done
    pkill -9 -x "$proc" 2>/dev/null || true
    if [[ -n "$ws" ]]; then
        layout=$(mktemp --suffix=.json)
        printf '{"marks":["%s"],"swallows":[{"class":"^%s$"}]}\n' "$mark" "$class" > "$layout"
        focused=$(i3-msg -t get_workspaces 2>/dev/null | jq -r '.[] | select(.focused) | .name')
        i3-msg "unmark \"$mark\"" >/dev/null 2>&1
        if [[ "$ws" == "$focused" ]]; then
            i3-msg "append_layout $layout" >/dev/null 2>&1
        else
            i3-msg "workspace --no-auto-back-and-forth \"$ws\"; append_layout $layout; workspace --no-auto-back-and-forth \"$focused\"" >/dev/null 2>&1
        fi
        rm -f "$layout"
        # Remove the empty placeholder if the app fails to come back.
        (
            sleep 25
            pgrep -x "$proc" >/dev/null 2>&1 \
                || i3-msg "[con_mark=\"$mark\"] kill" >/dev/null 2>&1
        ) >/dev/null 2>&1 &
    fi
    command -v "$proc" >/dev/null 2>&1 && setsid -f "$proc" >/dev/null 2>&1
}

set_dunst_theme() {
    local config="$HOME/.config/dunst/dunstrc"

    [[ -f "$config" ]] || return 0

    set_ini_key "$config" global frame_color '"#005f87"'
    set_ini_key "$config" global separator_color '"#93a1a1"'
    set_ini_key "$config" global format "\"<span foreground='#073642'><b>%s %p</b></span>\\\\n%b\""
    sed -i '/^%b"$/d' "$config"
    set_ini_key "$config" urgency_low background '"#fdf6e3"'
    set_ini_key "$config" urgency_low foreground '"#073642"'
    set_ini_key "$config" urgency_normal background '"#fdf6e3"'
    set_ini_key "$config" urgency_normal foreground '"#073642"'
    set_ini_key "$config" urgency_critical background '"#dc322f"'
    set_ini_key "$config" urgency_critical foreground '"#fdf6e3"'
    set_ini_key "$config" urgency_critical frame_color '"#dc322f"'

    command -v dunstctl >/dev/null 2>&1 && dunstctl reload "$config" >/dev/null 2>&1 || true
}

# ─── GTK 3 / GTK 4 ──────────────────────────────────────────────
# Update only theme-related keys; preserve font, cursor, Xft and other local settings.
for gtk_file in ~/.config/gtk-3.0/settings.ini ~/.config/gtk-4.0/settings.ini; do
    set_ini_key "$gtk_file" Settings gtk-theme-name "$GTK_THEME"
    set_ini_key "$gtk_file" Settings gtk-icon-theme-name Adwaita
    set_ini_key "$gtk_file" Settings gtk-application-prefer-dark-theme 0
done

gsettings set org.gnome.desktop.interface gtk-theme "$GTK_THEME" 2>/dev/null || true
gsettings set org.gnome.desktop.interface color-scheme 'prefer-light' 2>/dev/null || true

# ─── Qt5 / Qt6 ──────────────────────────────────────────────────
set_ini_key "$HOME/.config/qt5ct/qt5ct.conf" Appearance color_scheme_path "$HOME/.config/qt5ct/colors/SolarizedLight.conf"
set_ini_key "$HOME/.config/qt5ct/qt5ct.conf" Appearance custom_palette true
set_ini_key "$HOME/.config/qt6ct/qt6ct.conf" Appearance color_scheme_path "$HOME/.config/qt6ct/colors/SolarizedLight.conf"
set_ini_key "$HOME/.config/qt6ct/qt6ct.conf" Appearance custom_palette true

# Nextcloud client: the monochrome tray icon guesses light-on-dark and is
# unreadable on a light bar; the colorful brand icon works in both modes.
if [[ -f ~/.config/Nextcloud/nextcloud.cfg ]]; then
    set_ini_key ~/.config/Nextcloud/nextcloud.cfg General monoIcons false
fi

# KeePassXC follows the portal/system switch live when its in-app theme is "Automatic".
if [[ -f ~/.config/keepassxc/keepassxc.ini ]]; then
    set_ini_key ~/.config/keepassxc/keepassxc.ini GUI ApplicationTheme auto
    # The monochrome tray variants are FIXED light or dark and vanish on
    # one of the two bars; the colorful icon is readable in both modes.
    # Applied on the next KeePassXC start (no auto-restart: open database).
    set_ini_key ~/.config/keepassxc/keepassxc.ini GUI TrayIconAppearance colorful
fi

# nheko: keep theme=system. Its built-in light theme hardcodes a DARK
# sidebar (#233649, Element-style) — only theme=system derives the sidebar
# and scrollbars from the Qt palette, which qt6ct supplies per mode. A live
# palette switch leaves a running instance mixed, so restart it in place.
# theme=system is also what nheko writes back on exit, so the value
# survives its settings persistence without ordering tricks.
if [[ -f ~/.config/nheko/nheko.conf ]]; then
    set_ini_key ~/.config/nheko/nheko.conf user theme system
    restart_app_in_place nheko nheko
fi

# ─── khal / ikhal ───────────────────────────────────────────────
if [[ -f ~/.config/khal/config ]]; then
    set_ini_key ~/.config/khal/config view theme light
    set_ini_key ~/.config/khal/config view frame width
    set_ini_key ~/.config/khal/config highlight_days method fg
    set_ini_key ~/.config/khal/config highlight_days multiple brown
    # Days with events from exactly two calendars show both colors as
    # half-and-half; three or more fall back to the "multiple" color.
    set_ini_key ~/.config/khal/config highlight_days multiple_on_overflow True
    # Empty color keeps per-calendar day colors in the month view; the
    # [palette] overrides below remap them to adaptive ANSI accents.
    set_ini_key ~/.config/khal/config highlight_days color ""
    set_ini_key ~/.config/khal/config palette header "'', '', ''"
    set_ini_key ~/.config/khal/config palette footer "'', '', ''"
    set_ini_key ~/.config/khal/config palette "line header" "dark blue, '', bold"
    set_ini_key ~/.config/khal/config palette "alt header" "dark blue, '', bold"
    set_ini_key ~/.config/khal/config palette bright "dark blue, '', bold"
    set_ini_key ~/.config/khal/config palette list "'', '', ''"
    set_ini_key ~/.config/khal/config palette "list focused" "white, black, bold"
    set_ini_key ~/.config/khal/config palette edit "'', '', ''"
    set_ini_key ~/.config/khal/config palette "edit focus" "white, black, bold"
    set_ini_key ~/.config/khal/config palette button "black, light gray, ''"
    set_ini_key ~/.config/khal/config palette "button focused" "white, black, bold"
    set_ini_key ~/.config/khal/config palette "reveal focus" "white, black, standout"
    set_ini_key ~/.config/khal/config palette "today focus" "white, black, standout"
    set_ini_key ~/.config/khal/config palette today "black, light gray, ''"
    set_ini_key ~/.config/khal/config palette "date header" "light red, '', ''"
    set_ini_key ~/.config/khal/config palette "date header focused" "white, black, bold"
    set_ini_key ~/.config/khal/config palette "date header selected" "white, black, ''"
    set_ini_key ~/.config/khal/config palette dayname "dark cyan, '', ''"
    set_ini_key ~/.config/khal/config palette monthname "dark magenta, '', ''"
    set_ini_key ~/.config/khal/config palette weeknumber_right "dark gray, '', ''"
    set_ini_key ~/.config/khal/config palette alert "white, dark red, bold"
    set_ini_key ~/.config/khal/config palette mark "white, dark gray, bold"
    set_ini_key ~/.config/khal/config palette frame "dark gray, '', ''"
    set_ini_key ~/.config/khal/config palette "frame focus" "dark blue, '', ''"
    set_ini_key ~/.config/khal/config palette "frame focus color" "dark blue, '', ''"
    set_ini_key ~/.config/khal/config palette "frame focus top" "dark magenta, '', ''"
    set_ini_key ~/.config/khal/config palette eventcolumn "'', '', ''"
    set_ini_key ~/.config/khal/config palette "eventcolumn focus" "'', '', ''"
    set_ini_key ~/.config/khal/config palette calendar "'', '', ''"
    # Default like khal's built-in themes: a color here washes over every
    # plain day whenever the calendar column holds focus.
    set_ini_key ~/.config/khal/config palette "calendar focus" "'', '', ''"
    set_ini_key ~/.config/khal/config palette editbx "white, black, ''"
    set_ini_key ~/.config/khal/config palette editcp "black, light gray, standout"
    set_ini_key ~/.config/khal/config palette popupbg "'', '', ''"
    set_ini_key ~/.config/khal/config palette popupper "white, black, bold"
    set_ini_key ~/.config/khal/config palette caption "dark blue, '', bold"
    # Per-calendar accents for month-view day numbers and event-list rows
    # (both share the "calendar <name>" attributes, ikhal merges the config
    # palette last): ANSI names track the terminal palette live, unlike
    # static RGB values from vdir `color` files. The attribute names must
    # match the discovered calendar names from `khal printcalendars`.
    set_ini_key ~/.config/khal/config palette "calendar personal" "dark blue, '', ''"
    set_ini_key ~/.config/khal/config palette "calendar work" "dark magenta, '', ''"
fi

# ─── Xresources / urxvt ─────────────────────────────────────────
ln -sf "$THEME_DIR/Xresources" ~/.Xresources
command -v xrdb >/dev/null 2>&1 && xrdb -load ~/.Xresources

# Recolor only PTSes whose process ancestry belongs to the terminal.
# This changes Background/Foreground/Cursor and the 16-color ANSI palette
# where the terminal supports OSC 4.
if [[ "${RECOLOR_URXVT_PTS:-1}" == "1" ]]; then
    recolor_child_ttys "urxvt" "#fdf6e3" "#073642" "#586e75" "$SOLARIZED_LIGHT_ANSI_OSC"
fi
if [[ "${RECOLOR_ALACRITTY_PTS:-1}" == "1" ]]; then
    recolor_child_ttys "alacritty" "#fdf6e3" "#073642" "#586e75" "$SOLARIZED_LIGHT_ANSI_OSC"
fi
redraw_tui_apps

# ─── Alacritty ──────────────────────────────────────────────────
write_alacritty_theme

# ─── i3 ─────────────────────────────────────────────────────────
mkdir -p ~/.config/i3
ln -sf "$THEME_DIR/i3-theme.conf" ~/.config/i3/theme.conf
command -v i3-msg >/dev/null 2>&1 && i3-msg reload >/dev/null 2>&1 || true

# ─── Polybar ────────────────────────────────────────────────────
mkdir -p ~/.config/polybar
ln -sf "$THEME_DIR/polybar.ini" ~/.config/polybar/colors.ini
# IPC restart first (needs enable-ipc=true per bar); fall back to a kill
# that waits until the old instances are really gone, then verify the bars
# came up — polybar's monitor detection can fail transiently right after
# an i3 reload, which can otherwise leave the desktop without any bar.
restart_polybar() {
    local i
    if command -v polybar-msg >/dev/null 2>&1 && polybar-msg cmd restart >/dev/null 2>&1; then
        sleep 1
        pgrep -x polybar >/dev/null 2>&1 && return 0
    fi
    pkill -x polybar 2>/dev/null || true
    for i in 1 2 3 4 5 6 7 8 9 10; do
        pgrep -x polybar >/dev/null 2>&1 || break
        sleep 0.2
    done
    if [[ -x ~/.config/polybar/launch.sh ]]; then
        setsid -f ~/.config/polybar/launch.sh >/dev/null 2>&1
        sleep 1
        pgrep -x polybar >/dev/null 2>&1 \
            || setsid -f ~/.config/polybar/launch.sh >/dev/null 2>&1
    fi
}
restart_polybar

# Fixed list of the applets that belong in this machine's tray. Tray icons
# are drawn by the applets (XEmbed) with the GTK icon theme they loaded at
# startup, so they must be restarted to match the new mode. Two pitfalls
# shape this function: XEmbed applets exit immediately when they dock into
# a tray that is still re-initializing after the Polybar restart (hence
# the delay and the safety net), and rapid consecutive toggles can kill
# applets a previous hook run just started (hence "ensure running" with a
# fixed list instead of "only restart what was running").
TRAY_APPS="nm-applet pasystray flameshot"
restart_tray_apps() {
    local app
    for app in $TRAY_APPS; do
        pkill -x "$app" 2>/dev/null || true
    done
    sleep 2
    for app in $TRAY_APPS; do
        command -v "$app" >/dev/null 2>&1 || continue
        pgrep -x "$app" >/dev/null 2>&1 || setsid -f "$app" >/dev/null 2>&1
    done
    # Safety net: relaunch anything that died docking too early.
    (
        sleep 5
        for app in $TRAY_APPS; do
            command -v "$app" >/dev/null 2>&1 || continue
            pgrep -x "$app" >/dev/null 2>&1 || setsid -f "$app" >/dev/null 2>&1
        done
    ) >/dev/null 2>&1 &
}
restart_tray_apps

# ─── Rofi ───────────────────────────────────────────────────────
# Rofi reads its theme on startup; existing menus are transient.
mkdir -p ~/.config/rofi
ln -sf "$THEME_DIR/rofi.rasi" ~/.config/rofi/theme.rasi

# ─── neomutt ────────────────────────────────────────────────────
mkdir -p ~/.config/neomutt
ln -sf "$THEME_DIR/mutt-colors" ~/.config/neomutt/colors

if [[ -d ~/.config/mutt ]]; then
    ln -sf "$THEME_DIR/mutt-colors" ~/.config/mutt/theme.muttrc
fi

# ─── jellyfin-tui ───────────────────────────────────────────────
set_jellyfin_tui_preference() {
    local theme="$1"

    [[ -d "$HOME/.local/share/jellyfin-tui/preferences" ]] || return 0
    command -v jq >/dev/null 2>&1 || return 0

    for pref in "$HOME"/.local/share/jellyfin-tui/preferences/*.json; do
        [[ -f "$pref" ]] || continue
        tmp=$(mktemp)
        jq --arg theme "$theme" '.theme = $theme' "$pref" > "$tmp" && mv "$tmp" "$pref" || rm -f "$tmp"
    done
}

set_jellyfin_tui_config_theme() {
    local mode="$1"
    local config="$HOME/.config/jellyfin-tui/config.yaml"

    [[ -f "$config" ]] || return 0
    command -v ruby >/dev/null 2>&1 || return 0

    ruby - "$config" "$mode" <<'RUBY'
require "yaml"

path, mode = ARGV
cfg = YAML.load_file(path) || {}

dark = {
  "base" => "Dark",
  "background" => "#282a36",
  "foreground" => "#f8f8f2",
  "foreground_secondary" => "#d7d8e8",
  "foreground_dim" => "#a7abc4",
  "foreground_disabled" => "#6f758f",
  "section_title" => "#bd93f9",
  "accent" => "#8be9fd",
  "border" => "#4f5268",
  "border_focused" => "#bd93f9",
  "selected_active_background" => "#44475a",
  "selected_active_foreground" => "#f8f8f2",
  "selected_inactive_background" => "#343746",
  "selected_inactive_foreground" => "#f8f8f2",
  "scrollbar_thumb" => "#c6c8d6",
  "scrollbar_track" => "#44475a",
  "progress_fill" => "#ffb86c",
  "progress_track" => "#44475a",
  "tab_active_foreground" => "#bd93f9",
  "tab_inactive_foreground" => "#7b819d",
  "album_header_background" => "#343746",
  "album_header_foreground" => "#8be9fd"
}

light = {
  "base" => "Light",
  "background" => "#fdf6e3",
  "foreground" => "#073642",
  "foreground_secondary" => "#25464d",
  "foreground_dim" => "#405f66",
  "foreground_disabled" => "#586e75",
  "section_title" => "#005f87",
  "accent" => "#005f87",
  "border" => "#586e75",
  "border_focused" => "#005f87",
  "selected_active_background" => "#005f87",
  "selected_active_foreground" => "#fdf6e3",
  "selected_inactive_background" => "#d7ebe8",
  "selected_inactive_foreground" => "#073642",
  "scrollbar_thumb" => "#586e75",
  "scrollbar_track" => "#eee8d5",
  "progress_fill" => "#875f00",
  "progress_track" => "#d6cab0",
  "tab_active_foreground" => "#005f87",
  "tab_inactive_foreground" => "#586e75",
  "album_header_background" => "#eee8d5",
  "album_header_foreground" => "#073642"
}

palette = mode == "light" ? light : dark
managed_names = ["Mode Switcher", "Dracula High Contrast", "Solarized Light High Contrast"]
themes = cfg["themes"].is_a?(Array) ? cfg["themes"] : []
unmanaged = themes.reject { |theme| theme.is_a?(Hash) && managed_names.include?(theme["name"]) }

cfg["auto_color"] = false
cfg["themes"] = managed_names.map { |name| { "name" => name }.merge(palette) } + unmanaged

content = YAML.dump(cfg)
if !File.exist?(path) || File.read(path) != content
  mode_bits = File.exist?(path) ? File.stat(path).mode & 0o777 : 0o600
  tmp = "#{path}.tmp.#{$$}"
  File.write(tmp, content)
  File.chmod(mode_bits, tmp)
  File.rename(tmp, path)
end
RUBY
}

# jellyfin-tui live-reloads config.yaml, but not its preferences file.
# Keep one stable selected theme and rewrite that theme's colors per mode.
set_jellyfin_tui_preference "Mode Switcher"
set_jellyfin_tui_config_theme "light"
if pgrep -x jellyfin-tui >/dev/null 2>&1; then
    (
        while pgrep -x jellyfin-tui >/dev/null 2>&1; do
            sleep 0.5
        done
        set_jellyfin_tui_preference "Mode Switcher"
    ) >/dev/null 2>&1 &
fi

# ─── sonicradio ─────────────────────────────────────────────────
# Every built-in theme ships separate dark and light profiles, picked from
# the terminal background at startup. A constant high-contrast theme works
# for both modes and survives sonicradio's config write-back on exit.
if [[ -f ~/.config/sonicRadio/config.json ]] && command -v jq >/dev/null 2>&1; then
    tmp=$(mktemp)
    jq '.theme = 4' ~/.config/sonicRadio/config.json > "$tmp" \
        && mv "$tmp" ~/.config/sonicRadio/config.json \
        || rm -f "$tmp"
fi

# ─── VSCodium ───────────────────────────────────────────────────
SETTINGS="$HOME/.config/VSCodium/User/settings.json"
if [[ -f "$SETTINGS" ]] && command -v jq >/dev/null 2>&1; then
    tmp=$(mktemp)
    jq '."workbench.colorTheme" = "Solarized Light"' "$SETTINGS" > "$tmp" \
        && mv "$tmp" "$SETTINGS" \
        || rm -f "$tmp"
fi

# ─── Claude Code ────────────────────────────────────────────────
CLAUDE_SETTINGS="$HOME/.claude/settings.json"
if [[ -f "$CLAUDE_SETTINGS" ]] && command -v jq >/dev/null 2>&1; then
    tmp=$(mktemp)
    jq '.theme = "light"' "$CLAUDE_SETTINGS" > "$tmp" && mv "$tmp" "$CLAUDE_SETTINGS" || rm -f "$tmp"
fi

# ─── Neovim ─────────────────────────────────────────────────────
mkdir -p ~/.config/nvim
ln -sf "$THEME_DIR/nvim-colorscheme.vim" ~/.config/nvim/colorscheme.vim 2>/dev/null || true

# ─── User Notification ──────────────────────────────────────────
set_dunst_theme
notify-send -i weather-clear "Theme" "Light Mode activated (Solarized Light)" 2>/dev/null || true
echo "Light mode activated (Solarized Light)"

Make the script executable:

chmod +x ~/.local/share/light-mode.d/apply-theme

darkman is designed as a user service that persists its own state. The service typically remembers the last mode after a restart and executes the corresponding hooks at startup.

Important — no hardcoded darkman set calls in .xprofile! It might be tempting to write darkman set dark in .xprofile to “always start with Dark mode.” However, this is counterproductive:

It overwrites the last manual toggle on every login.

It completely disables auto-switching based on sunrise/sunset, if you enable it later.

Just let the service run.

Reality Check: Verify Persistence

In practice, reliable persistence depends on the interplay between the user service, login manager, and XDG state directory. Do not blindly trust it – check it after the first login cycle:

# What does darkman currently think?
darkman get

# Was the service started cleanly at login and did it trigger hooks?
journalctl --user -u darkman.service -b

If darkman get returns a different mode than expected, or if the hook scripts were not executed at login, you have a persistence problem (see next section).

If Persistence is Unreliable

Some possible countermeasures:

Ensure darkman.service is truly enabled: systemctl --user is-enabled darkman.service
In TTY login + startx setups, source ~/.xprofile from ~/.xinitrc before exec i3.
Import X session variables into the user service manager — treat this as required, not optional. darkman.service usually starts before the display manager has exported DISPLAY/XAUTHORITY, and a long-running service keeps the environment it started with forever. The symptoms are sneaky: OSC recoloring, Polybar IPC, and config rewrites all work without X, so the switcher looks fine — but xrdb fails and every GUI process the hooks relaunch (tray applets, nheko) crashes instantly with “could not connect to display”. Put this in ~/.xinitrc (or your session startup) before exec i3:
```
dbus-update-activation-environment --systemd DISPLAY XAUTHORITY XDG_CURRENT_DESKTOP
systemctl --user import-environment DISPLAY XAUTHORITY XDG_CURRENT_DESKTOP
systemctl --user try-restart darkman.service
```
The try-restart makes darkman re-run the current mode’s hook with the freshly imported environment, which also repairs the failed X calls from its too-early boot start. The hook scripts above additionally carry a DISPLAY/XAUTHORITY fallback as a second line of defense.
If hooks run too early and cannot reach X/i3, do not add darkman set ... to .xprofile. Fix the environment import above and restart the user service once:
```
systemctl --user restart darkman.service
```

Optional: Auto-Switching Based on Sunrise/Sunset

If darkman should automatically switch based on time of day, create the file ~/.config/darkman/config.yaml:

lat: 48.2082
lng: 16.3738
usegeoclue: false

(The coordinates provided here are for Vienna – adjust them to your location.)

The service calculates sunrise and sunset times from this and automatically triggers the hooks.

If you really need a default value on the very first start

If you’ve just installed darkman and want a defined initial state for the very first toggle, perform this manually once in the shell:

darkman set dark

— not in .xprofile. From the next login onwards, the service will remember.

Step 10: Obtain Theme Files

For each application, place a dark and a light variant in ~/.config/themes/<theme>/. The following commands cover most cases. You can paste these directly:

Alacritty

curl -fsSL https://raw.githubusercontent.com/dracula/alacritty/master/dracula.toml \
     -o ~/.config/themes/dracula/alacritty.toml
curl -fsSL https://raw.githubusercontent.com/alacritty/alacritty-theme/master/themes/solarized_light.toml \
     -o ~/.config/themes/solarized-light/alacritty.toml

The upstream Solarized Light terminal palette is faithful to the original scheme, but several TUI applications render blue/cyan/yellow text too lightly on #fdf6e3. For a terminal-focused setup, use this high-contrast variant instead of the raw upstream light file:

cat > ~/.config/themes/solarized-light/alacritty.toml <<'EOF'
# Colors (Solarized Light High Contrast)
[colors.primary]
background = '#fdf6e3'
foreground = '#073642'

[colors.normal]
black   = '#073642'
red     = '#dc322f'
green   = '#5f8700'
yellow  = '#875f00'
blue    = '#005f87'
magenta = '#af005f'
cyan    = '#006c6b'
white   = '#eee8d5'

[colors.bright]
black   = '#002b36'
red     = '#cb4b16'
green   = '#586e00'
yellow  = '#6c5a00'
blue    = '#00629d'
magenta = '#6c71c4'
cyan    = '#00736f'
white   = '#fdf6e3'
EOF

In your main ~/.config/alacritty/alacritty.toml, import the generated theme file the hook rewrites 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:

[general]
import = ["~/.config/alacritty/theme.toml"]
live_config_reload = true   # default; explicit for clarity

TOML note: Since Alacritty 0.14, import, working_directory, live_config_reload, and ipc_socket live under [general]. If you run an older Alacritty, check man 5 alacritty for your version before copying this block.

Xresources / urxvt

The upstream dracula/xresources file uses a slightly different ANSI variant (pure black #000000, muted whites #bfbfbf/#e6e6e6) than the official Dracula Alacritty theme. If the OSC nudge, the Xresources, and the Alacritty file disagree, a live-recolored terminal and a freshly started one will show two different palettes side by side. Write a flat file with the official values instead:

cat > ~/.config/themes/dracula/Xresources <<'EOF'
! Dracula — flat, aligned with the official Alacritty palette
*.foreground: #f8f8f2
*.background: #282a36
*cursorColor: #f8f8f2

*.color0:  #21222c
*.color8:  #6272a4
*.color1:  #ff5555
*.color9:  #ff6e6e
*.color2:  #50fa7b
*.color10: #69ff94
*.color3:  #f1fa8c
*.color11: #ffffa5
*.color4:  #bd93f9
*.color12: #d6acff
*.color5:  #ff79c6
*.color13: #ff92df
*.color6:  #8be9fd
*.color14: #a4ffff
*.color7:  #f8f8f2
*.color15: #ffffff
EOF

For Solarized Light, the upstream solarized/xresources file uses C preprocessor #define statements. Many display managers and login flows invoke xrdb with -nocpp, which means those defines are not expanded and color entries that depend on them can fail to load as intended. To avoid this entirely, write a flat (preprocessor-free) version directly:

cat > ~/.config/themes/solarized-light/Xresources <<'EOF'
! Solarized Light — flat, no #define preprocessing required
*background:            #fdf6e3
*foreground:            #073642
URxvt.foreground:       #073642
URxvt*foreground:       #073642
*fadeColor:             #fdf6e3
*cursorColor:           #586e75
*pointerColorBackground:#93a1a1
*pointerColorForeground:#586e75

! black
*color0:  #073642
*color8:  #002b36
! red
*color1:  #dc322f
*color9:  #cb4b16
! green
*color2:  #5f8700
*color10: #586e00
! yellow
*color3:  #875f00
*color11: #6c5a00
! blue
*color4:  #005f87
*color12: #00629d
! magenta
*color5:  #af005f
*color13: #6c71c4
! cyan
*color6:  #006c6b
*color14: #00736f
! white
*color7:  #eee8d5
*color15: #fdf6e3
EOF

The values above keep the Solarized Light background and base colors but deliberately darken several accent colors. This is less purist than the canonical palette, but it is much more readable for TUIs such as neomutt, ikhal, sonicradio, and other apps that rely heavily on ANSI blue/cyan/yellow.

The hook uses xrdb -load, not xrdb -merge, because this setup manages .Xresources as a complete theme file. -merge keeps old keys that are absent in the new file; in practice that can leave stale urxvt values from the previous mode in the live Xresources database.

Polybar

See Step 5 — minimal Dracula and Solarized Light palettes are inlined there. Copy them into ~/.config/themes/<theme>/polybar.ini if you haven’t already, then include ~/.config/polybar/colors.ini from your real Polybar config.

Rofi

Rofi reads its theme file when the menu starts. Point your main config at a stable user theme path once:

@theme "~/.config/rofi/theme.rasi"

Then create ~/.config/themes/dracula/rofi.rasi and ~/.config/themes/solarized-light/rofi.rasi; the hooks above switch ~/.config/rofi/theme.rasi to the active file. This affects the next Rofi invocation. A menu that is already open will not repaint live.

neomutt

Use terminal-palette colors for NeoMutt unless you have deliberately configured a DirectColor terminfo entry. The official NeoMutt configuration guide allows hexadecimal #RRGGBB colors only when $color_directcolor is set, and that option must be active before any color commands are read. On many i3/Alacritty systems COLORTERM=truecolor is not enough for NeoMutt: infocmp "$TERM" may show 256 colors but no Tc/RGB DirectColor capability, which makes HEX colors fail with “color not supported by terminal”.

For live repainting, use the same semantic ANSI color file in both theme directories. NeoMutt keeps the same color0-color15 attributes in memory; the hooks change what those terminal color slots mean:

mkdir -p ~/.config/themes/dracula ~/.config/themes/solarized-light
cat > ~/.config/themes/dracula/mutt-colors <<'EOF'
# Semantic ANSI NeoMutt palette for the mode switcher.
uncolor index *
uncolor index_author *
uncolor index_collapsed *
uncolor index_date *
uncolor index_flags *
uncolor index_label *
uncolor index_number *
uncolor index_size *
uncolor index_subject *
uncolor index_tag *
uncolor index_tags *
uncolor body *
uncolor header *
uncolor status *

color normal              default default
# Never reuse one background pair for two different row markers: the
# cursor must stay visible on top of unread rows (color15/color8).
color indicator           color0  color7
color status              color15 color8
color tree                color4  default
color error               color15 color1
color message             color2  default
color prompt              color2  default
color options             color4  default
color progress            color0  color7
color signature           color8  default
color attachment          color2  default
color search              reverse color5 default
color markers             color1  default
color tilde               color8  default
color hdrdefault          color6  default

color sidebar_background  default default
color sidebar_divider     color8  default
color sidebar_flagged     color3  default
color sidebar_highlight   color15 color8
color sidebar_indicator   color15 color8
color sidebar_new         color4  default
color sidebar_ordinary    default default
color sidebar_spool_file  default default
color sidebar_unread      color2  default

color header              color4 default "^Subject:.*"
color body                color4 default "[[:alnum:]_.+%-]+@[[:alnum:].-]+"
color body                color3 default "(https?|ftp)://[[:alnum:].,/%~_:?&=#,+-]+"
color body                color6 default "(^|[[:space:]])\\*[^[:space:]]+\\*([[:space:]]|$)"
color body                color6 default "(^|[[:space:]])_[^[:space:]]+_([[:space:]]|$)"
color body                color6 default "(^|[[:space:]])/[^[:space:]]+/([[:space:]]|$)"

color quoted              color4 default
color quoted1             color6 default
color quoted2             color2 default
color quoted3             color5 default
color quoted4             color1 default

# State rows with visible backgrounds that work on both terminal palettes.
# "reverse colorN default" renders an accent background whose text takes the
# terminal's default background color — the contrast is identical to using
# the accent as a foreground, so it stays readable in both modes.
color index               color5  default "~Q"
color index               color8  default "~v"
color index               color15 color8  "~U"
color index               reverse color6 default "~T"
color index               reverse color3 default "~F"
color index               reverse color1 default "~D"
# Column accents only on rows without a state background, so state rows
# stay uniform blocks instead of getting default-background holes.
color index_author        color5 default "!(~U|~T|~F|~D)"
color index_date          color2 default "!(~U|~T|~F|~D)"
color index_flags         color4 default "!(~U|~T|~F|~D)"
color index_number        color4 default "!(~U|~T|~F|~D)"
color index_size          color3 default "!(~U|~T|~F|~D)"
EOF
cp ~/.config/themes/dracula/mutt-colors ~/.config/themes/solarized-light/mutt-colors

The indicator, status, and sidebar_highlight rules deliberately stay on the neutral slots (color0, color7, color8, color15). Accent slots are bright pastels in Dracula but dark tones in the Solarized Light High Contrast palette, so an accent background fails in one of the two modes: color15 on a color4 background reads as near-white on light purple in Dracula (about 1.9:1 contrast), and color0 on color3 as dark slate on dark yellow in Solarized Light (about 2.3:1). The neutral pairs stay above 4.5:1 in both palettes.

A second design rule matters as soon as rows get background highlighting: never reuse one background pair for two different marker types. If the cursor (indicator) and unread rows shared color15/color8, the cursor would become invisible while sitting on unread mail. That is why the palette above splits them: cursor = bright color0/color7 bar, unread = calm color15/color8 block, search = magenta via reverse color5 — each marker owns its background.

The mail-state rows still get colored backgrounds, just through a different mechanism: reverse colorN default makes NeoMutt render the row in reverse video, which displays the accent as the background and the terminal’s default background color as the text. The resulting contrast is mathematically identical to the accent used as a foreground on the default background — and that combination is readable in both modes by definition, otherwise the accent would be useless as a text color. This yields tagged = cyan/teal block, flagged = gold block, deleted = red block, while unread mail uses the explicit neutral color15/color8 pair as a calmer highlight. The per-column accents are restricted to !(~U|~T|~F|~D) because an index_author rule with a default background would otherwise punch holes into the state rows.

If your setup comes from mutt-wizard, your main config is often ~/.config/mutt/muttrc, not ~/.config/neomutt/. In that case add this once:

source ~/.config/mutt/theme.muttrc

and let the hooks switch ~/.config/mutt/theme.muttrc instead of ~/.config/neomutt/colors.

If a NeoMutt instance is already running with an older 256-color or HEX theme loaded, it needs one manual reload once. Press : to open NeoMutt’s command prompt, then run:

source ~/.config/mutt/theme.muttrc

After that, further Dark/Light switches can repaint via the terminal OSC palette and the hook’s SIGWINCH redraw nudge. If you maintain your own color files, start them with uncolor index *, uncolor body *, uncolor header *, and any other list-style color objects you use. Otherwise old dark rules and new light rules can stack together after a manual :source. Also keep body regexes POSIX-safe: use classes such as [[:alnum:]_.+%-], and place - at the end of a character class. Ambiguous ranges can make NeoMutt abort with errors such as “invalid endpoint in range expression”.

khal / ikhal

ikhal loads its Urwid palette once at startup. It does not watch ~/.config/khal/config for theme changes, so rewriting [palette] alone does not repaint an already running instance. The live strategy is the same as NeoMutt: use only ANSI color names and let the terminal palette change underneath.

Do not use dark blue as a large focused background. In the Dracula terminal palette it intentionally maps to purple, which looks good as an accent but turns the focused mini-calendar into a purple block. Keep dark blue for foreground accents and use neutral black or empty backgrounds for broad focus surfaces.

The same rule applies to every accent slot. dark cyan and dark green map to dark teal/olive in the Solarized Light High Contrast palette but to bright pastels in Dracula, so as backgrounds they fail in exactly one of the two modes: button = black, dark cyan drops to about 2.1:1 contrast in Light mode, and mark = white, dark green to about 1.1:1 in Dracula. Treat ANSI slots 1–6 and 9–14 as foreground-only and build backgrounds from black, dark gray, light gray, and white — that is why the palette below uses button = black, light gray and mark = white, dark gray.

The hooks above still set [view] theme for next starts, but the visible custom palette stays semantic and identical in both modes:

[view]
theme = light
frame = width

[highlight_days]
method = fg
multiple = brown
# two-calendar days show both colors half-and-half; three or more
# fall back to the "multiple" color
multiple_on_overflow = True
# empty: per-calendar day colors via the palette overrides below
color =

[palette]
header = '', '', ''
footer = '', '', ''
line header = dark blue, '', bold
alt header = dark blue, '', bold
bright = dark blue, '', bold
list = '', '', ''
list focused = white, black, bold
edit = '', '', ''
edit focus = white, black, bold
button = black, light gray, ''
button focused = white, black, bold
reveal focus = white, black, standout
today focus = white, black, standout
today = black, light gray, ''
date header = light red, '', ''
date header focused = white, black, bold
date header selected = white, black, ''
dayname = dark cyan, '', ''
monthname = dark magenta, '', ''
weeknumber_right = dark gray, '', ''
alert = white, dark red, bold
mark = white, dark gray, bold
frame = dark gray, '', ''
frame focus = dark blue, '', ''
frame focus color = dark blue, '', ''
frame focus top = dark magenta, '', ''
eventcolumn = '', '', ''
eventcolumn focus = '', '', ''
calendar = '', '', ''
calendar focus = '', '', ''
editbx = white, black, ''
editcp = black, light gray, standout
popupbg = '', '', ''
popupper = white, black, bold
caption = dark blue, '', bold
calendar personal = dark blue, '', ''
calendar work = dark magenta, '', ''

Event days and calendar colors

If your calendars come from a CalDAV server and vdirsyncer syncs metadata = ["color"], each vdir carries an RGB color file (for example #1c57ec). Those static RGB values cannot adapt to a mode switch: a dark blue that reads fine on a light background drops below 3:1 contrast on a dark one. Worse, in type = discover setups the vdir color takes precedence over any color value in the khal config, so you cannot neutralize it there — and editing the vdir files is not an option either, because metasync would push the change back to your server.

The escape hatch is the palette merge order: ikhal builds its palette from the theme, then appends the generated per-calendar and highlight attributes, and merges the config [palette] section last — config entries win. So define one calendar <name> = dark blue, '', '' entry per calendar to remap its color to an ANSI name that tracks the terminal palette live. Month-view day numbers and event-list rows share these calendar <name> attributes, which means both stay color-coded per calendar and readable in both modes. The attribute names must match the discovered calendar names — check khal printcalendars, since type = discover setups often append suffixes (personal becomes personal1).

Two refinements round off the month view: multiple_on_overflow = True renders days with events from exactly two calendars as half-and-half two-color cells, and the de-emphasized weeknumber_right/frame (dark gray) plus the dark magenta month column give the calendar a color hierarchy instead of uniform cyan.

If you wonder whether there are ready-made color tables for exactly this: khal ships two built-in themes (dark and light in khal/ui/colors.py), which [view] theme selects and our [palette] section refines. They are worth reading as a reference for which attribute does what, but they assume a terminal with pure black/white defaults rather than a theme-switched palette — that is why this setup overrides them with semantic ANSI values. Two lessons from the built-ins are baked into the palette above: calendar focus stays at '', '', '' (khal’s own default — any color there washes over every plain day whenever the calendar column holds focus), and structural accents like date header follow the built-ins’ use of light red, which stays distinct from all per-calendar accent colors.

Alternative: uniform background blocks. If you prefer one clearly visible block over per-calendar colors, set [highlight_days] color to any non-empty value (for example dark gray) and override the generated attribute with highlight_days_color = white, dark gray, '' in [palette]. Every event day then renders as white on slate (#6272a4) in Dracula and cream on dark slate (#002b36) in Solarized Light — distinct from the today block in both modes. Note that this drops the per-calendar distinction in the month view; the shared-attribute coupling means truly per-calendar background blocks would also turn every event-list row into a colored block.

All overrides use only ANSI color names, so they repaint live with the OSC palette switch — no ikhal restart needed beyond the usual one-time migration.

Use '' for empty/default foreground, background, or mono fields. default is not a valid khal palette color name and will make khal reject the config. Existing ikhal sessions that loaded an older HEX palette need one restart; after that the hook’s OSC palette update plus SIGWINCH redraw is enough for normal mode switches.

jellyfin-tui

jellyfin-tui has two separate pieces of theme state:

~/.config/jellyfin-tui/config.yaml contains the custom theme definitions and is watched by the running app.
~/.local/share/jellyfin-tui/preferences/*.json stores the selected theme name and is best treated as a next-start setting.

That means the reliable live strategy is not to switch between two selected theme names. Keep the selected theme stable, for example Mode Switcher, and let the hooks rewrite that theme’s colors in config.yaml. The running app will then repaint from its config watcher, while the preferences file only needs to stay pointed at the stable theme name.

Create a starting theme in ~/.config/jellyfin-tui/config.yaml:

auto_color: false
themes:
- name: Mode Switcher
  base: Dark
  background: "#282a36"
  foreground: "#f8f8f2"
  foreground_secondary: "#d7d8e8"
  foreground_dim: "#a7abc4"
  foreground_disabled: "#6f758f"
  section_title: "#bd93f9"
  accent: "#8be9fd"
  border: "#4f5268"
  border_focused: "#bd93f9"
  selected_active_background: "#44475a"
  selected_active_foreground: "#f8f8f2"
  selected_inactive_background: "#343746"
  selected_inactive_foreground: "#f8f8f2"
  scrollbar_thumb: "#c6c8d6"
  scrollbar_track: "#44475a"
  progress_fill: "#ffb86c"
  progress_track: "#44475a"
  tab_active_foreground: "#bd93f9"
  tab_inactive_foreground: "#7b819d"
  album_header_background: "#343746"
  album_header_foreground: "#8be9fd"

Select that theme once in every existing preference file:

for pref in ~/.local/share/jellyfin-tui/preferences/*.json; do
    jq '.theme = "Mode Switcher"' "$pref" > /tmp/jellyfin-tui-pref.json \
      && mv /tmp/jellyfin-tui-pref.json "$pref"
done

The hook examples above use ruby to update YAML without string surgery. They also update the legacy names Dracula High Contrast and Solarized Light High Contrast to the same current palette, which helps during migration if a running instance still has one of those names loaded in memory. If the app is currently on a built-in theme, select Mode Switcher once in the app or restart it once; after that, mode changes can be picked up from config.yaml.

sonicradio

sonicradio is a Bubble Tea/Lipgloss application with built-in themes stored as numeric IDs in ~/.config/sonicRadio/config.json. A look at its ui/theme.go reveals the right strategy: every theme ships a separate dark and light color profile, and the app picks the profile from the terminal background at startup. So instead of switching theme IDs per mode, set one constant theme whose two profiles are both high-contrast — in the tested setup ID 4 (“Mono Yellow”: near-black text and an amber selection bar on light terminals, amber-on-dark in dark mode):

jq '.theme = 4' ~/.config/sonicRadio/config.json > /tmp/sonicradio.json \
  && mv /tmp/sonicradio.json ~/.config/sonicRadio/config.json

The constant value has a second benefit: sonicradio persists its config on exit, which would overwrite a per-mode value — a constant one survives. The duo-tone themes (IDs 0–3) are poor choices here: their pale selection backgrounds (for example lavender #D4DAF7) almost disappear on a light terminal. A live terminal switch still leaves a running instance on the old profile (pale dark-profile text on a now-light background); restart it once after toggling.

Dunst

Dunst is not affected by GTK, Qt, or the XDG color-scheme portal. It reads ~/.config/dunst/dunstrc, so the hook should update only the color keys you actually want to switch and then reload the running daemon:

set_ini_key ~/.config/dunst/dunstrc global frame_color '"#005f87"'
set_ini_key ~/.config/dunst/dunstrc global separator_color '"#93a1a1"'
set_ini_key ~/.config/dunst/dunstrc global format "\"<span foreground='#073642'><b>%s %p</b></span>\\\\n%b\""
set_ini_key ~/.config/dunst/dunstrc urgency_normal background '"#fdf6e3"'
set_ini_key ~/.config/dunst/dunstrc urgency_normal foreground '"#073642"'
dunstctl reload ~/.config/dunst/dunstrc

The double escaping before n is intentional: the file should contain a literal \n inside the quoted Dunst format string, not a physical newline that breaks the next config line.

VSCodium

VSCodium (like VS Code) ships with Solarized Light and Solarized Dark as built-in themes — no extension required. Dracula, however, must be installed separately:

codium --install-extension dracula-theme.theme-dracula

The hook scripts already set the correct theme name via jq. If your VSCodium uses a different binary name (e.g., vscodium), adjust the command accordingly.

Claude Code

Claude Code renders its terminal UI with truecolor values from its own theme setting and ignores the terminal’s ANSI palette entirely — on a light terminal with the app still on "theme": "dark", dim text and diff views become nearly invisible. The hooks patch ~/.claude/settings.json (.theme = "dark" / "light") via jq. New sessions pick the matching theme up automatically; already running sessions keep their theme until restarted or changed in-session via /config.

nheko

nheko needs three insights at once, all confirmed against src/ui/Theme.cpp:

Do not use theme=light if you expect a fully light window. nheko’s built-in light theme hardcodes a dark Element-style sidebar (sidebarBackground = #233649) — the dark rail and scrollbar tones you might mistake for dark-mode leftovers are upstream design. Only theme=system derives sidebarBackground and the scrollbars from the Qt palette (p.window().color()), which qt6ct supplies correctly per mode. So the hooks keep theme=system and rely on a complete qt5ct/qt6ct color scheme.
A live palette switch always leaves a running instance mixed — parts of the QML UI cache their colors. A restart is unavoidable, so the hooks do it automatically.
nheko persists its in-memory settings on exit, just like jellyfin-tui: quitting it right after a config write restores the old value. The only reliable order is: stop the running instance, wait until it has saved and quit, write the config, start it fresh — exactly what the hook block does. A nheko that was not running is left closed.

The cost is a brief reconnect of the Matrix client per mode switch; remove the restart part of the block if you prefer switching nheko manually. Two traps follow from the restart itself:

Hooks run inside darkman.service, which does not see ~/.xprofile — without the QT_QPA_PLATFORMTHEME export from the hook header, a hook-restarted nheko silently skips qt6ct and renders with unthemed Qt defaults.
A restarted app is a new window, and i3 places new windows on the currently focused workspace — the old position died with the old window. The root-level fix is i3’s own session-restore mechanism: restart_app_in_place (defined with the other hook helpers) appends a placeholder container with swallow criteria to the app’s old workspace via append_layout, and i3 materializes the next matching window directly inside it — on whatever workspace the app happened to live, with no capture-and-move-back scripting. Two implementation notes: i3 returns success even when a criteria matches nothing (scripted post-hoc moves fail silently), and a watchdog removes the placeholder if the app fails to come back. If you instead keep an app on one fixed workspace anyway, a declarative assign [class="..."] number N rule is the simpler alternative.

GTK and Qt

GTK Dracula via AUR (yay -S dracula-gtk-theme); Adwaita is shipped by default. Qt color schemes: see Step 3.

Neovim

The hook scripts manage ~/.config/nvim/colorscheme.vim. This only has an effect if your Neovim config sources that file:

source ~/.config/nvim/colorscheme.vim

Then create theme-specific files, for example:

cat > ~/.config/themes/dracula/nvim-colorscheme.vim <<'EOF'
set background=dark
colorscheme dracula
EOF

cat > ~/.config/themes/solarized-light/nvim-colorscheme.vim <<'EOF'
set background=light
colorscheme solarized
EOF

Adjust the colorscheme names to match the plugins actually installed in your Neovim setup.

Reference table

App	File	Source
GTK	Theme via AUR/Pacman	`dracula-gtk-theme`, Adwaita is default
Xresources/urxvt	`Xresources`	local flat files aligned with the Alacritty palettes (Step 10)
Alacritty	`alacritty.toml`	`dracula/alacritty`, `alacritty/alacritty-theme`
i3	`i3-theme.conf`	inlined examples in Step 4
Polybar	`polybar.ini` → `~/.config/polybar/colors.ini`	inlined examples in Step 5
Rofi	`rofi.rasi` → `~/.config/rofi/theme.rasi`	local `.rasi` files
neomutt	`mutt-colors`	local semantic 16-color palette
khal / ikhal	`~/.config/khal/config`	local semantic ANSI palette
jellyfin-tui	`config.yaml`, preferences JSON	live-reloaded custom `Mode Switcher` theme
sonicradio	`~/.config/sonicRadio/config.json`	built-in numeric themes
Dunst	`~/.config/dunst/dunstrc`	local color keys, reload via `dunstctl reload`
KeePassXC	`~/.config/keepassxc/keepassxc.ini`	set app theme to Automatic
VSCodium	built-in / Extension	Solarized built-in, “Dracula Official” via marketplace
Claude Code	`~/.claude/settings.json`	built-in `dark`/`light` truecolor themes
nheko	`~/.config/nheko/nheko.conf`	built-in themes via `[user] theme`
qt5ct/qt6ct	`*.conf`	`dracula/qt5`, Solarized via qt5ct GUI

You can find Dracula themes collected at https://draculatheme.com – Solarized at https://ethanschoonover.com/solarized.

Caveats and Honest Expectations

What switches live (without restart):

Alacritty (with live_config_reload = true)
i3 (after reload)
Polybar (after restart)
Rofi on the next menu invocation, because Rofi reads theme.rasi at startup
VSCodium (mostly, via file watcher on settings.json)
KeePassXC if View → Theme → Automatic is selected
Dunst notifications after the hook updates dunstrc and runs dunstctl reload
jellyfin-tui, if it is already using the stable Mode Switcher custom theme; the hooks rewrite that theme in config.yaml, which the app watches.
NeoMutt and ikhal after they have loaded the semantic ANSI palette once; the hook changes the terminal’s 16-color palette and sends SIGWINCH for redraw.
The XDG portal color-scheme value consumed by portal-aware apps
Terminal foreground/background/cursor nudges for running urxvt/Alacritty windows via OSC sequences
Tray applet icons, because the hooks restart the applets (nm-applet, pasystray, flameshot) with the freshly switched GTK icon theme

What requires an app restart:

Firefox/Thunderbird chrome can require a restart even when the portal signal itself updates live. Web content using prefers-color-scheme is usually more likely to follow than the full browser UI.
Generic GTK apps in plain i3 setups, such as Thunar, may read the new theme only on next start unless an XSettings/settings daemon propagates changes.
nheko and other Qt apps that keep their own in-memory palette. The hooks handle nheko by restarting it automatically (stop, wait for its settings write-back on exit, keep theme=system, start fresh) — note that nheko’s built-in light theme deliberately uses a dark sidebar, so theme=system plus a complete qt6ct palette is the only fully light/dark-consistent configuration.
Claude Code: the hooks switch its truecolor theme in ~/.claude/settings.json; new sessions match automatically, running sessions keep the old theme until restart or an in-session /config change.
GIMP, LibreOffice (own theme logic)
urxvt terminals still do not fully reload arbitrary Xresources live. The included PTS escape-sequence trick updates running urxvt Background/Foreground/Cursor and the 16-color ANSI palette, but font/resource changes and app-internal colors still require a restart or app-level reload.
Terminal apps with their own theme state, such as sonicradio, usually need restart or an app-internal theme change. jellyfin-tui is the exception when the stable Mode Switcher strategy above is used; NeoMutt and ikhal are the exception when the semantic ANSI palette strategy above is used.
Bubble Tea/Lipgloss/termenv apps can briefly use the old AdaptiveColor branch after a live terminal theme change. The Alacritty OSC nudge reduces this, but a running TUI can still repaint one step late.
Chromium (flags file takes effect on start)

What needs to be configured manually within the app:

LibreOffice: set Light/Dark once in Tools → Options → Application Colors
GIMP: has its own theme system under Preferences → Theme
KeePassXC: set View → Theme → Automatic once; hardcoded dark or light overrides the portal
Inkscape: follows GTK, but restart required

Tips

Geo-based Auto-Switching: darkman can do this automatically based on sunrise/sunset – see Step 9.
Debugging: journalctl --user -u darkman.service -f shows if hooks are being executed.
Manual Hook Testing: Execute ~/.local/share/dark-mode.d/apply-theme directly to see errors in isolation.
Terminal OSC Nudges: The hook enables targeted urxvt and Alacritty PTS recoloring plus OSC 4 ANSI-palette updates by default. Set RECOLOR_URXVT_PTS=0 or RECOLOR_ALACRITTY_PTS=0 when running the hook if you want to disable these partial live updates.
Consistency Across Multiple Machines: Version ~/.config/themes/, ~/.local/share/dark-mode.d/, ~/.local/share/light-mode.d/, and ~/.config/qt5ct/colors/ in your dotfiles repository.

Extension Ideas

base16-Framework instead of Dracula/Solarized: Generate a unified scheme for hundreds of apps from a single palette (https://github.com/chriskempson/base16).
Per-Workspace-Themes: Theoretically possible via i3-IPC, but rarely practical.
Polybar Module with current theme status as an indicator.

Summary

The implemented architecture is:

darkman (Trigger + Portal + Persistence)
    ├── Hooks → GTK, Qt, Xresources, App Configs
    ├── Live-Reload: i3, Polybar, Alacritty, XDG portal signal, VSCodium
    └── Accepted: Some apps require restart

You switch with $mod+Shift+d. Most apps react immediately, some require a restart – this is the current state of Linux desktop reality, not a flaw in your setup.

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 config, XDG portal, i3, Alacritty), then extensions, and finally the “problem children.” This way, you can more easily identify the cause of problems if they arise.

📚ARCH WIKI: DARK MODE THEME SWITCHING 💻DARKMAN PROJECT ON GITLAB

Server Security Audit Script for Debian/Ubuntu

Unknown — Mon, 04 May 2026 00:00:00 +0000

Changelog

Date	Change
2026-05-04	Initial Version: Full audit script with comprehensive explanations.

Introduction to the Server Security Audit Script

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.

This script is designed to be run with root privileges and will:

Check System Fundamentals: Hostname, timezone, kernel, pending updates, and reboot status.
Audit User & Authentication: Verify the existence and sudo privileges of a dedicated admin user, check root password status, and identify accounts with UID 0 or empty passwords.
Harden SSH: 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.
Firewall Configuration (UFW): Confirm UFW’s active status, default policies, specific rule sets (e.g., rate-limiting for SSH), and log redirection.
Intrusion Prevention (Fail2Ban): Validate that Fail2Ban is running, its SSH jail is active, and it’s monitoring the correct SSH port.
Automated Updates: Ensure unattended-upgrades is installed and configured to keep your system patched.
Docker Security: If Docker is installed, it checks daemon status, Docker Compose presence, user group membership, and critically, Docker’s log rotation settings and network configuration.
Log Rotation: Verify persistent journaling and logrotate configurations for Traefik and UFW logs.
Network & Open Ports: List actively listening ports and check for known insecure legacy services.
Filesystem Security: Scan for world-writable files in critical directories and report disk usage.

At the end, it provides a summary of PASS, WARN, and FAIL counts, giving you an immediate understanding of areas needing attention.

Why is this important? 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.

How to Use the Script

Save the script: Copy the entire script content into a file, for example, server-audit.sh.
Make it executable:
```
chmod +x server-audit.sh
```
Run with sudo: The script requires root privileges to access system configurations and logs.
```
sudo ./server-audit.sh
```
Review the output: Pay close attention to [FAIL] and [WARN] messages, which indicate potential security vulnerabilities or areas for improvement.

The Server Security Audit Script

Here is the complete script. You can customize the ADMIN_USER variable at the beginning to match your dedicated administrative username.

#!/bin/bash
# =============================================================================
# Server Security Audit Script
# =============================================================================
# Checks if the cloud-init setup has been correctly applied and if current
# security standards are met.
#
# Usage: sudo bash server-audit.sh
# =============================================================================

set -u

# --- Colors & Symbols --------------------------------------------------------
GREEN="\033[0;32m"
RED="\033[0;31m"
YELLOW="\033[0;33m"
CYAN="\033[0;36m"
BOLD="\033[1m"
NC="\033[0m"

PASS="${GREEN}PASS${NC}"
FAIL="${RED}FAIL${NC}"
WARN="${YELLOW}WARN${NC}"
INFO="${CYAN}INFO${NC}"

pass_count=0
fail_count=0
warn_count=0

log_pass() { echo -e "  [${PASS}]  $1"; ((pass_count++)); }
log_fail() { echo -e "  [${FAIL}]  $1"; ((fail_count++)); }
log_warn() { echo -e "  [${WARN}]  $1"; ((warn_count++)); }
log_info() { echo -e "  [${INFO}]  $1"; }

section() { echo -e "\n${BOLD}=== $1 ===${NC}"; }

# --- Root Check --------------------------------------------------------------
if [[ $EUID -ne 0 ]]; then
    echo -e "${RED}This script must be run with sudo.${NC}"
    exit 1
fi

ADMIN_USER="delightfuldude" # <--- CUSTOMIZE THIS TO YOUR ADMIN USERNAME

echo -e "${BOLD}"
echo "============================================================"
echo "  Server Security Audit - $(date '+%Y-%m-%d %H:%M:%S')"
echo "============================================================"
echo -e "${NC}"

# =============================================================================
# 1. SYSTEM FUNDAMENTALS
# =============================================================================
section "1. System Fundamentals"

# Hostname
CURRENT_HOSTNAME=$(hostnamectl --static 2>/dev/null || hostname)
if [[ "$CURRENT_HOSTNAME" != "localhost" && -n "$CURRENT_HOSTNAME" ]]; then
    log_pass "Hostname set: ${CURRENT_HOSTNAME}"
else
    log_warn "Hostname is still on default"
fi

# Timezone
CURRENT_TZ=$(timedatectl show -p Timezone --value 2>/dev/null || cat /etc/timezone 2>/dev/null || echo "unknown")
if [[ "$CURRENT_TZ" == "Europe/Berlin" ]]; then
    log_pass "Timezone: ${CURRENT_TZ}"
else
    log_warn "Timezone is ${CURRENT_TZ} (expected: Europe/Berlin)"
fi

# Kernel & OS
log_info "OS: $(grep PRETTY_NAME /etc/os-release 2>/dev/null | cut -d= -f2 | tr -d '"')"
log_info "Kernel: $(uname -r)"

# Uptime
log_info "Uptime: $(uptime -p)"

# Pending Updates
UPDATES=$(apt list --upgradable 2>/dev/null | grep -c upgradable || true)
if [[ "$UPDATES" -eq 0 ]]; then
    log_pass "No pending package updates"
else
    log_warn "${UPDATES} package update(s) available"
fi

# Reboot required?
if [[ -f /var/run/reboot-required ]]; then
    log_warn "System reboot required"
else
    log_pass "No reboot required"
fi

# =============================================================================
# 2. USER & AUTHENTICATION
# =============================================================================
section "2. User & Authentication"

# Admin user exists
if id "$ADMIN_USER" &>/dev/null; then
    log_pass "User '${ADMIN_USER}' exists"
else
    log_fail "User '${ADMIN_USER}' does NOT exist"
fi

# sudo group
if groups "$ADMIN_USER" 2>/dev/null | grep -qw sudo; then
    log_pass "'${ADMIN_USER}' is in the sudo group"
else
    log_fail "'${ADMIN_USER}' is NOT in the sudo group"
fi

# NOPASSWD in sudoers (accepted for cloud-init without password)
if grep -r "NOPASSWD" /etc/sudoers /etc/sudoers.d/ 2>/dev/null | grep -v "^#" | grep -q "$ADMIN_USER"; then
    log_info "'${ADMIN_USER}' has NOPASSWD (intended, as cloud-init doesn't set a password)"
else
    log_pass "No NOPASSWD for '${ADMIN_USER}' - sudo requires password"
fi

# Root password (should be locked or random, not empty)
ROOT_PW_STATUS=$(passwd -S root 2>/dev/null | awk '{print $2}')
case "$ROOT_PW_STATUS" in
    L)  log_pass "Root account is locked" ;;
    P)  log_info "Root has a password set (randomized by cloud-init)" ;;
    NP) log_fail "Root has NO password!" ;;
    *)  log_info "Root password status: ${ROOT_PW_STATUS}" ;;
esac

# Accounts with empty password
EMPTY_PW=$(awk -F: '($2 == "" ) { print $1 }' /etc/shadow 2>/dev/null || true)
if [[ -z "$EMPTY_PW" ]]; then
    log_pass "No accounts with empty password"
else
    log_fail "Accounts with empty password: ${EMPTY_PW}"
fi

# UID-0 accounts (only root should have UID 0)
ROOT_ACCOUNTS=$(awk -F: '($3 == 0) { print $1 }' /etc/passwd)
if [[ "$ROOT_ACCOUNTS" == "root" ]]; then
    log_pass "Only 'root' has UID 0"
else
    log_fail "Multiple accounts with UID 0: ${ROOT_ACCOUNTS}"
fi

# =============================================================================
# 3. SSH HARDENING
# =============================================================================
section "3. SSH Hardening"

# Read effective SSH configuration
SSHD_CONFIG=$(sshd -T 2>/dev/null || true)

if [[ -z "$SSHD_CONFIG" ]]; then
    log_fail "Cannot read SSH configuration (sshd -T failed)"
else
    # Port
    SSH_PORT=$(echo "$SSHD_CONFIG" | grep "^port " | awk '{print $2}')
    if [[ "$SSH_PORT" != "22" ]]; then
        log_pass "SSH port changed: ${SSH_PORT}"
    else
        log_warn "SSH is running on default port 22"
    fi

    # Root Login
    ROOT_LOGIN=$(echo "$SSHD_CONFIG" | grep "^permitrootlogin " | awk '{print $2}')
    if [[ "$ROOT_LOGIN" == "no" ]]; then
        log_pass "Root login disabled"
    else
        log_fail "Root login is '${ROOT_LOGIN}' (should be 'no')"
    fi

    # Password Auth
    PW_AUTH=$(echo "$SSHD_CONFIG" | grep "^passwordauthentication " | awk '{print $2}')
    if [[ "$PW_AUTH" == "no" ]]; then
        log_pass "Password authentication disabled"
    else
        log_fail "Password authentication is enabled!"
    fi

    # Pubkey Auth
    PUBKEY_AUTH=$(echo "$SSHD_CONFIG" | grep "^pubkeyauthentication " | awk '{print $2}')
    if [[ "$PUBKEY_AUTH" == "yes" ]]; then
        log_pass "Public-key authentication enabled"
    else
        log_fail "Public-key authentication is disabled!"
    fi

    # MaxAuthTries
    MAX_AUTH=$(echo "$SSHD_CONFIG" | grep "^maxauthtries " | awk '{print $2}')
    if [[ "$MAX_AUTH" -le 3 ]]; then
        log_pass "MaxAuthTries: ${MAX_AUTH}"
    else
        log_warn "MaxAuthTries is ${MAX_AUTH} (recommended: <=3)"
    fi

    # LoginGraceTime
    GRACE_TIME=$(echo "$SSHD_CONFIG" | grep "^logingracetime " | awk '{print $2}')
    if [[ "$GRACE_TIME" -le 60 ]]; then
        log_pass "LoginGraceTime: ${GRACE_TIME}s"
    else
        log_warn "LoginGraceTime is ${GRACE_TIME}s (recommended: <=60)"
    fi

    # X11Forwarding
    X11=$(echo "$SSHD_CONFIG" | grep "^x11forwarding " | awk '{print $2}')
    if [[ "$X11" == "no" ]]; then
        log_pass "X11Forwarding disabled"
    else
        log_warn "X11Forwarding is enabled"
    fi

    # TCP Forwarding
    TCP_FWD=$(echo "$SSHD_CONFIG" | grep "^allowtcpforwarding " | awk '{print $2}')
    if [[ "$TCP_FWD" == "no" ]]; then
        log_pass "TCP-Forwarding disabled"
    else
        log_warn "TCP-Forwarding is enabled"
    fi

    # Agent Forwarding
    AGENT_FWD=$(echo "$SSHD_CONFIG" | grep "^allowagentforwarding " | awk '{print $2}')
    if [[ "$AGENT_FWD" == "no" ]]; then
        log_pass "Agent-Forwarding disabled"
    else
        log_warn "Agent-Forwarding is enabled"
    fi

    # AllowUsers set
    ALLOW_USERS=$(echo "$SSHD_CONFIG" | grep "^allowusers " | awk '{$1=""; print $0}' | xargs)
    if [[ -n "$ALLOW_USERS" ]]; then
        log_pass "AllowUsers restricted to: ${ALLOW_USERS}"
    else
        log_warn "AllowUsers is not set (all users can use SSH)"
    fi

    # Check if insecure Key Algorithms are accepted
    ACCEPTED_ALGOS=$(echo "$SSHD_CONFIG" | grep "^pubkeyacceptedalgorithms " | awk '{$1=""; print $0}' | xargs)
    if [[ -n "$ACCEPTED_ALGOS" ]]; then
        if echo "$ACCEPTED_ALGOS" | grep -qw "ssh-rsa"; then
            log_fail "ssh-rsa (SHA-1) is still allowed - use rsa-sha2-* only!"
        else
            log_pass "Only modern Key Algorithms allowed"
        fi
        log_info "Allowed Algorithms: ${ACCEPTED_ALGOS}"
    else
        log_info "PubkeyAcceptedAlgorithms: System Default (SHA-1 blocked since OpenSSH 8.8)"
    fi
fi

# SSH Key present for Admin User
ADMIN_HOME=$(eval echo ~"$ADMIN_USER")
if [[ -f "${ADMIN_HOME}/.ssh/authorized_keys" ]]; then
    KEY_COUNT=$(grep -c "^ssh-" "${ADMIN_HOME}/.ssh/authorized_keys" 2>/dev/null || true)
    if [[ "$KEY_COUNT" -gt 0 ]]; then
        log_pass "${KEY_COUNT} SSH key(s) stored for '${ADMIN_USER}'"
        while IFS= read -r line; do
            KEY_TYPE=$(echo "$line" | awk '{print $1}')
            KEY_COMMENT=$(echo "$line" | awk '{print $3}')
            KEY_BITS=$(ssh-keygen -l -f /dev/stdin <<< "$line" 2>/dev/null | awk '{print $1}' || true)
            log_info "  Key: ${KEY_TYPE} ${KEY_BITS:-?} bit (${KEY_COMMENT:-no comment})"
        done < <(grep "^ssh-" "${ADMIN_HOME}/.ssh/authorized_keys")
    else
        log_fail "No SSH keys in authorized_keys!"
    fi
else
    log_fail "No authorized_keys file for '${ADMIN_USER}'!"
fi

SSH_VERSION=$(ssh -V 2>&1)
log_info "SSH Version: ${SSH_VERSION}"

# =============================================================================
# 4. FIREWALL (UFW)
# =============================================================================
section "4. Firewall (UFW)"

# SSH_PORT for later use (if sshd -T failed)
SSH_PORT=${SSH_PORT:-8496} # Fallback to a common custom port

if command -v ufw &>/dev/null; then
    UFW_STATUS=$(ufw status 2>/dev/null || true)
    if echo "$UFW_STATUS" | grep -q "Status: active"; then
        log_pass "UFW is active"

        # Default Policies
        UFW_VERBOSE=$(ufw status verbose 2>/dev/null || true)
        if echo "$UFW_VERBOSE" | grep -q "deny (incoming)"; then
            log_pass "Default policy incoming: deny"
        else
            log_fail "Default policy incoming is NOT deny!"
        fi

        if echo "$UFW_VERBOSE" | grep -q "allow (outgoing)"; then
            log_pass "Default policy outgoing: allow"
        else
            log_info "Default policy outgoing is not 'allow'"
        fi

        # List open ports
        echo ""
        log_info "Active rules:"
        ufw status numbered 2>/dev/null | grep -E "^\[" | while IFS= read -r rule; do
            echo -e "         ${rule}"
        done

        # SSH port with rate-limit?
        if echo "$UFW_STATUS" | grep -q "${SSH_PORT}.*LIMIT"; then
            log_pass "SSH port ${SSH_PORT} has Rate-Limiting"
        elif echo "$UFW_STATUS" | grep -q "${SSH_PORT}"; then
            log_warn "SSH port ${SSH_PORT} is open, but WITHOUT Rate-Limiting"
        else
            log_warn "SSH port ${SSH_PORT} is not explicitly in UFW"
        fi
    else
        log_fail "UFW is NOT active"
    fi

    # UFW Logging Redirect (VNC Console fix)
    if [[ -f /etc/rsyslog.d/20-ufw.conf ]]; then
        log_pass "UFW logs are redirected to /var/log/ufw.log (console remains clean)"
    else
        log_warn "UFW logs not redirected - VNC console will be flooded with [UFW BLOCK]"
    fi
else
    log_fail "UFW is not installed"
fi

# =============================================================================
# 5. FAIL2BAN
# =============================================================================
section "5. Fail2Ban"

if command -v fail2ban-client &>/dev/null; then
    if systemctl is-active --quiet fail2ban; then
        log_pass "Fail2Ban is running"

        # SSH Jail active?
        if fail2ban-client status sshd &>/dev/null; then
            log_pass "SSH Jail is active"
            F2B_STATUS=$(fail2ban-client status sshd 2>/dev/null || true)
            BANNED=$(echo "$F2B_STATUS" | grep "Currently banned" | awk '{print $NF}')
            TOTAL_BANNED=$(echo "$F2B_STATUS" | grep "Total banned" | awk '{print $NF}')
            log_info "Currently banned: ${BANNED:-0}, Total banned: ${TOTAL_BANNED:-0}"
        else
            log_fail "SSH Jail is NOT active"
        fi

        # Check configuration
        F2B_PORT=$(grep -r "^port" /etc/fail2ban/jail.local 2>/dev/null | head -1 | awk '{print $NF}' || true)
        if [[ "$F2B_PORT" == "$SSH_PORT" ]]; then
            log_pass "Fail2Ban monitors correct SSH port (${F2B_PORT})"
        elif [[ -n "$F2B_PORT" ]]; then
            log_fail "Fail2Ban monitors port ${F2B_PORT}, SSH runs on ${SSH_PORT}!"
        fi
    else
        log_fail "Fail2Ban is installed, but NOT active"
    fi
else
    log_fail "Fail2Ban is not installed"
fi

# =============================================================================
# 6. AUTOMATIC UPDATES
# =============================================================================
section "6. Automatic Updates"

if dpkg -l unattended-upgrades &>/dev/null; then
    log_pass "unattended-upgrades is installed"

    if [[ -f /etc/apt/apt.conf.d/20auto-upgrades ]]; then
        if grep -q 'Unattended-Upgrade "1"' /etc/apt/apt.conf.d/20auto-upgrades; then
            log_pass "Automatic upgrades are enabled"
        else
            log_warn "20auto-upgrades exists, but upgrades appear disabled"
        fi
    else
        log_warn "20auto-upgrades configuration is missing"
    fi
else
    log_fail "unattended-upgrades is not installed"
fi

# =============================================================================
# 7. DOCKER
# =============================================================================
section "7. Docker"

if command -v docker &>/dev/null; then
    log_pass "Docker is installed: $(docker --version 2>/dev/null | head -1)"

    if systemctl is-active --quiet docker; then
        log_pass "Docker daemon is running"
    else
        log_warn "Docker daemon is not active"
    fi

    # Docker Compose
    if docker compose version &>/dev/null; then
        log_pass "Docker Compose: $(docker compose version 2>/dev/null | head -1)"
    else
        log_warn "Docker Compose Plugin not found"
    fi

    # User in docker group
    if groups "$ADMIN_USER" 2>/dev/null | grep -qw docker; then
        log_pass "'${ADMIN_USER}' is in the docker group"
    else
        log_warn "'${ADMIN_USER}' is NOT in the docker group"
    fi

    # Log rotation configured?
    if [[ -f /etc/docker/daemon.json ]]; then
        if grep -q "max-size" /etc/docker/daemon.json; then
            log_pass "Docker Log rotation configured"
            MAX_SIZE=$(grep "max-size" /etc/docker/daemon.json | tr -d ' ",' | cut -d: -f2)
            MAX_FILE=$(grep "max-file" /etc/docker/daemon.json | tr -d ' ",' | cut -d: -f2)
            log_info "max-size: ${MAX_SIZE}, max-file: ${MAX_FILE}"
        else
            log_warn "daemon.json exists, but no Log rotation configured"
        fi
    else
        log_warn "No daemon.json - Docker logs can grow indefinitely!"
    fi

    # Proxy network
    if docker network ls 2>/dev/null | grep -q "proxy"; then
        log_pass "Docker network 'proxy' exists"
    else
        log_warn "Docker network 'proxy' is missing"
    fi
else
    log_fail "Docker is not installed"
fi

# =============================================================================
# 8. TRAEFIK PREPARATION
# =============================================================================
section "8. Traefik Stack Preparation"

TRAEFIK_DIR="/opt/containers/traefik-stack"
if [[ -d "$TRAEFIK_DIR" ]]; then
    log_pass "Directory ${TRAEFIK_DIR} exists"

    # Subdirectories
    for dir in traefik/dynamic traefik/logs traefik/certs crowdsec/config crowdsec/data; do
        if [[ -d "${TRAEFIK_DIR}/${dir}" ]]; then
            log_pass "  ${dir}/ is present"
        else
            log_fail "  ${dir}/ is missing"
        fi
    done

    # acme.json Permissions
    if [[ -f "${TRAEFIK_DIR}/traefik/certs/acme.json" ]]; then
        ACME_PERMS=$(stat -c "%a" "${TRAEFIK_DIR}/traefik/certs/acme.json")
        if [[ "$ACME_PERMS" == "600" ]]; then
            log_pass "acme.json has correct permissions (600)"
        else
            log_fail "acme.json has permissions ${ACME_PERMS} (should be 600)"
        fi
    else
        log_warn "acme.json does not exist yet"
    fi
else
    log_fail "Directory ${TRAEFIK_DIR} is missing"
fi

# =============================================================================
# 9. LOG ROTATION
# =============================================================================
section "9. Log Rotation"

# Persistent Journal
if [[ -d /var/log/journal ]]; then
    log_pass "Persistent Journal activated"
    JOURNAL_SIZE=$(journalctl --disk-usage 2>/dev/null | grep -oP '[\d.]+\w+' | head -1 || true)
    log_info "Journal size: ${JOURNAL_SIZE:-unknown}"
else
    log_warn "Journal is NOT persistent (logs are lost on reboot)"
fi

# Logrotate: Traefik
if [[ -f /etc/logrotate.d/traefik ]]; then
    log_pass "Logrotate for Traefik configured"
else
    log_warn "Logrotate for Traefik is missing"
fi

# Logrotate: UFW
if [[ -f /etc/logrotate.d/ufw-custom ]]; then
    log_pass "Logrotate for UFW logs configured"
elif [[ -f /etc/logrotate.d/ufw ]]; then
    log_pass "Logrotate for UFW logs configured (system default)"
else
    log_warn "Logrotate for UFW logs is missing - /var/log/ufw.log can grow indefinitely!"
fi

# Docker Log Rotation (Summary)
if [[ -f /etc/docker/daemon.json ]] && grep -q "max-size" /etc/docker/daemon.json 2>/dev/null; then
    log_pass "Docker Container logs rotated"
else
    log_warn "Docker Container logs are not rotated"
fi

# =============================================================================
# 10. NETWORK & OPEN PORTS
# =============================================================================
section "10. Network & Open Ports"

log_info "Listening ports (externally accessible):"
ss -tlnp 2>/dev/null | grep -v "127.0.0" | grep "LISTEN" | while IFS= read -r line; do
    PORT=$(echo "$line" | awk '{print $4}' | rev | cut -d: -f1 | rev)
    PROC=$(echo "$line" | grep -oP 'users:\(\("\K[^"]+' || echo "unknown")
    echo -e "         Port ${PORT} (${PROC})"
done

# Check for known insecure services
INSECURE_FOUND=0
for svc in telnetd rshd rlogind vsftpd proftpd; do
    if systemctl is-active --quiet "$svc" 2>/dev/null; then
        log_fail "Insecure service running: ${svc}"
        INSECURE_FOUND=1
    fi
done
if [[ "$INSECURE_FOUND" -eq 0 ]]; then
    log_pass "No insecure legacy services active"
fi

# =============================================================================
# 11. FILESYSTEM SECURITY
# =============================================================================
section "11. Filesystem"

# World-writable files in critical directories
WW_COUNT=$(find /etc /usr -xdev -type f -perm -o+w 2>/dev/null | wc -l)
if [[ "$WW_COUNT" -eq 0 ]]; then
    log_pass "No world-writable files in /etc and /usr"
else
    log_warn "${WW_COUNT} world-writable file(s) in /etc or /usr"
fi

# SUID Binaries (informative)
SUID_COUNT=$(find / -xdev -type f -perm -4000 2>/dev/null | wc -l)
log_info "SUID binaries found: ${SUID_COUNT} (manual review if needed)"

# Disk Usage
DISK_USAGE=$(df -h / | awk 'NR==2 {print $5}' | tr -d '%')
if [[ "$DISK_USAGE" -lt 80 ]]; then
    log_pass "Disk usage: ${DISK_USAGE}%"
elif [[ "$DISK_USAGE" -lt 90 ]]; then
    log_warn "Disk usage: ${DISK_USAGE}% (getting low)"
else
    log_fail "Disk usage: ${DISK_USAGE}% (critical!)"
fi

# =============================================================================
# SUMMARY
# =============================================================================
echo ""
echo -e "${BOLD}============================================================${NC}"
echo -e "${BOLD}  SUMMARY${NC}"
echo -e "${BOLD}============================================================${NC}"
echo -e "  ${GREEN}Passed:${NC}   ${pass_count}"
echo -e "  ${YELLOW}Warnings:${NC} ${warn_count}"
echo -e "  ${RED}Failed:${NC}    ${fail_count}"
echo -e "${BOLD}============================================================${NC}"

if [[ "$fail_count" -eq 0 && "$warn_count" -eq 0 ]]; then
    echo -e "\n${GREEN}${BOLD}Excellent! All checks passed.${NC}"
elif [[ "$fail_count" -eq 0 ]]; then
    echo -e "\n${YELLOW}${BOLD}Good - no critical failures, but review warnings.${NC}"
else
    echo -e "\n${RED}${BOLD}Attention - there are critical failures that should be resolved!${NC}"
fi

echo ""
exit "$fail_count"

Self-Hosting Plausible Analytics with Docker and Traefik

Unknown — Wed, 11 Mar 2026 00:00:00 +0000

This guide walks you through deploying a fully self-hosted Plausible Analytics 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.

We use the official Plausible Community Edition repository as the foundation and integrate it with our existing Traefik v3 reverse proxy via a compose.override.yml. This approach keeps the original compose.yml untouched, making future updates clean and painless.

Changelog

Date	Change
2026-03-11	Initial Version: Guide created for self-hosting Plausible CE v3.2.0 behind Traefik v3 with CrowdSec, based on the official repository.

1. Prerequisites

This guide builds upon a secure Docker environment. Before you begin, you must have a fully functional Traefik v3 and CrowdSec stack.

⚠️ HARD REQUIREMENT
The following steps will not work correctly without the Traefik stack running as described in the prerequisite guide. Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack: This is the foundation for our public-facing reverse proxy and security.

You will also need:

A dedicated subdomain for your Plausible instance (e.g., plausible.your-domain.com) pointed to your server’s IP address.
sudo or root access.
git and the openssl utility (sudo apt install git openssl).

2. Clone the Official Repository

Instead of building our own Docker Compose configuration from scratch, we clone the official Plausible CE repository. It ships with a tested compose.yml and pre-configured ClickHouse settings (including IPv4-only mode and resource-friendly defaults).

cd /opt/containers
sudo git clone -b v3.2.0 --single-branch https://github.com/plausible/community-edition plausible
cd plausible

The repository contains the following structure:

plausible/
├── clickhouse/
│   ├── default-profile-low-resources-overrides.xml
│   ├── ipv4-only.xml
│   ├── logs.xml
│   └── low-resources.xml
├── compose.yml
├── LICENSE
└── README.md

ℹ️ WHY NOT A CUSTOM COMPOSE FILE?
The official `compose.yml` 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 `compose.override.yml` to add only our Traefik-specific configuration — Docker Compose merges both files automatically.

3. Configuration

We only need to create two files: an .env file with your settings and a compose.override.yml for Traefik integration.

3.1. Generate Secrets

Plausible requires a secret key base for signing tokens and a TOTP vault key for two-factor authentication.

# Generate the secret key base (at least 64 bytes)
SECRET_KEY_BASE=$(openssl rand -base64 48)
echo "Your Secret Key Base is: $SECRET_KEY_BASE"

# Generate the TOTP vault key
TOTP_VAULT_KEY=$(openssl rand -base64 32)
echo "Your TOTP Vault Key is: $TOTP_VAULT_KEY"

ℹ️ SAVE THESE SECRETS
Copy these generated values into a temporary text file. You will need to paste them into the `.env` file in the next step.

3.2. Environment Configuration (`.env`)

This single file holds all your instance-specific settings. Create it in the repository root:

cat > .env << 'EOF'
# --- Required Settings ---
# Replace with your actual domain, including https://
BASE_URL=https://plausible.your-domain.com
# Paste the secret key base generated in step 3.1
SECRET_KEY_BASE=PASTE-YOUR-SECRET-KEY-BASE-HERE
# Paste the TOTP vault key generated in step 3.1
TOTP_VAULT_KEY=PASTE-YOUR-TOTP-VAULT-KEY-HERE

# --- Registration ---
# "invite_only" = only you can invite users. "true" = no new signups at all.
# Remove this line entirely to allow open registration.
DISABLE_REGISTRATION=invite_only

# --- Email / SMTP (Optional but recommended) ---
# Without SMTP, features like password resets and weekly reports will not work.

# The "From:" address shown in emails sent by Plausible.
# Use your SMTP login address or an alias your mail server accepts.
MAILER_EMAIL=plausible@your-domain.com
# Your SMTP server address, e.g. smtp.mailbox.org or mail.your-domain.com
SMTP_HOST_ADDR=your-mail-server.com
# Your SMTP port: typically 587 (STARTTLS) or 465 (SSL)
SMTP_HOST_PORT=587
# Your SMTP username — usually your full email address
SMTP_USER_NAME=your-smtp-username
# Your SMTP password
SMTP_USER_PWD=your-smtp-password
# Set to "true" only if your port is 465 (implicit SSL). For port 587, keep "false".
SMTP_HOST_SSL_ENABLED=false
EOF

⚠️ BASE_URL MUST BE CORRECT
The `BASE_URL` must match your public URL exactly, including `https://`. A mismatch will cause tracking scripts to fail and break the dashboard.

💡 REGISTRATION POLICY
The `DISABLE_REGISTRATION=invite_only` setting means that only you (the admin) can invite new users. This is the recommended setting for personal instances. Set it to `true` to completely disable new signups, or remove the line entirely to allow open registration.

3.3. Traefik Integration (`compose.override.yml`)

This file adds the Traefik labels and network connection to the Plausible service. Docker Compose merges it automatically with the official compose.yml — no need to modify the original file.

cat > compose.override.yml << 'EOF'
services:
  plausible:
    networks:
      - default
      - proxy
    labels:
      - "traefik.enable=true"
      # Replace plausible.your-domain.com with your actual domain.
      # This tells Traefik which incoming requests to route to this container.
      - "traefik.http.routers.plausible.rule=Host(`plausible.your-domain.com`)"
      - "traefik.http.routers.plausible.entrypoints=websecure"
      - "traefik.http.routers.plausible.tls.certresolver=tls_resolver"
      - "traefik.http.routers.plausible.middlewares=security-headers@file,crowdsec-bouncer@docker"
      - "traefik.http.services.plausible.loadbalancer.server.port=8000"
      - "traefik.docker.network=proxy"

networks:
  proxy:
    external: true
EOF

ℹ️ WHY DOES THE DOMAIN APPEAR TWICE?
`BASE_URL` in `.env` tells Plausible which URL it runs under — for generating correct links, cookies, and tracking scripts. The Traefik `Host()` label in `compose.override.yml` tells Traefik 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.

3.4. Update Configuration with Your Values

Replace all placeholders in the two files you just created. Every value that needs your input is marked with inline comments.

Domain Name: In .env (BASE_URL) and compose.override.yml (Traefik Host label), replace plausible.your-domain.com with your actual domain.
Secrets: In .env, paste the SECRET_KEY_BASE and TOTP_VAULT_KEY you generated in step 3.1.
Email Settings: In .env, update the SMTP section with your mail server details. Each field has an inline comment explaining what to enter.

4. Launch the Stack

With both files in place, start the stack:

# From within the /opt/containers/plausible directory
sudo docker compose up -d

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:

sudo docker compose logs -f

Press CTRL+C to exit the logs view once all services are stable. You should see Plausible report that it is ready.

5. Verify the Installation

Check Running Containers:
```
docker ps --format '{{.Names}}'
```
You should see three containers running: plausible-plausible-1, plausible-plausible_db-1 (PostgreSQL), and plausible-plausible_events_db-1 (ClickHouse).
Access the Dashboard: Open a web browser and navigate to https://plausible.your-domain.com. You should see the Plausible registration page.
Create Your Admin Account: Register with your email address and a strong password. Since we set DISABLE_REGISTRATION=invite_only, this first account becomes the admin. All future registrations will require an invitation from you.

💡 EMAIL VERIFICATION WITHOUT SMTP
If you skipped the SMTP configuration, you can manually verify your email address by running: `sudo docker compose exec plausible_db psql -U postgres -h localhost -d plausible_db -c "UPDATE users SET email_verified = true;"`

6. Add Plausible to Your Website

After logging in and creating your first site in the dashboard, Plausible will provide a tracking snippet. Starting with v3, Plausible generates a dynamic, site-specific script for each site you add. Simply copy the snippet from the site settings and add it to the <head> section of your website.

For a Zola-based site, add the provided snippet to your templates/base.html (or equivalent template). It will look something like this:

<!-- Replace both domains: plausible.your-domain.com = your Plausible instance, your-website.com = the site you want to track -->
<script defer src="https://plausible.your-domain.com/js/script.js" data-domain="your-website.com"></script>

ℹ️ NEW DYNAMIC SNIPPET IN V3
Plausible v3 introduced a new, more configurable tracking snippet that is specific to each site. Legacy `script.js` 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.

7. Maintenance

Updating Plausible

Since we cloned the official repository, updating involves fetching the new version tag and restarting. Your compose.override.yml and .env remain untouched.

cd /opt/containers/plausible

# Fetch the latest tags from the repository
sudo git fetch --tags

# Check out the new version (replace v3.x.x with the actual new version tag)
sudo git checkout v3.x.x

# Re-apply your override (it's preserved — just verify it's still there)
cat compose.override.yml

# Pull the new images and restart
sudo docker compose pull
sudo docker compose up -d --remove-orphans

💡 CHECK RELEASE NOTES
Always consult the official Plausible release notes before updating. Major version upgrades may require changes to your `.env` or introduce new configuration options.

Backing Up

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.

# From your /opt/containers/plausible directory

# 1. Back up the PostgreSQL database
sudo docker compose exec -T plausible_db pg_dump -U postgres -d plausible_db | gzip > plausible_pg_backup_$(date +%F).sql.gz

# 2. Back up the ClickHouse data via a temporary Alpine container
sudo docker run --rm \
  -v plausible_event-data:/data \
  -v $(pwd):/backup \
  alpine tar -czvf /backup/plausible_clickhouse_backup_$(date +%F).tar.gz -C /data .

echo "Backup complete."

ℹ️ BACKUP STRATEGY
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.

Restoring from Backup

To restore your instance from a backup:

cd /opt/containers/plausible

# 1. Stop the main application
sudo docker compose stop plausible

# 2. Restore PostgreSQL
gunzip < plausible_pg_backup_YYYY-MM-DD.sql.gz | sudo docker compose exec -T plausible_db psql -U postgres -d plausible_db

# 3. Restore ClickHouse (stop ClickHouse first)
sudo docker compose stop plausible_events_db
sudo docker run --rm \
  -v plausible_event-data:/data \
  -v $(pwd):/backup \
  alpine sh -c "rm -rf /data/* && tar -xzvf /backup/plausible_clickhouse_backup_YYYY-MM-DD.tar.gz -C /data"
sudo docker compose start plausible_events_db

# 4. Start everything
sudo docker compose start plausible

Conclusion

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 compose.override.yml for Traefik, your setup is easy to maintain and update — closely following the upstream project without custom workarounds.

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.

📚PLAUSIBLE SELF-HOSTING DOCS 📦PLAUSIBLE CE ON GITHUB

Git & GitHub for Beginners: Navigating the Version Control Labyrinth

Unknown — Sat, 07 Feb 2026 00:00:00 +0000

Welcome, intrepid coder, to the world of Git and GitHub! 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.

Changelog

Date	Change
2026-02-07	Initial Version: Guide created for beginners with practical tips, authentication troubleshooting, and common workflow patterns.

1. Git vs. GitHub: A Tale of Two Systems

Understanding the distinction between Git (the tool) and GitHub (the service) is foundational.

Local Git

Git is a version control system that lives on your computer. It meticulously tracks the history of your project as a series of commits.

Repository (Repo): This is your project folder, distinguished by a hidden .git/ directory.
Commit: A “snapshot” of your changes at a specific point in time.
Branch: An independent line of development (e.g., main, feature/my-new-thing).
Remote: A counterpart of your local repository hosted on a server (e.g., GitHub).

GitHub.com

GitHub is a hosting service built around Git repositories. It offers a suite of tools for collaborative development:

Stores repositories online (publicly or privately).
Facilitates collaboration through Pull Requests, Issues, and Code Reviews.
Provides Continuous Integration/Continuous Deployment (CI/CD) with GitHub Actions.
Can host container images and packages (e.g., GitHub Container Registry (GHCR): ghcr.io/...).

ℹ️ KEY TAKEAWAY
Git can function entirely without GitHub. GitHub enhances Git by providing cloud hosting and robust collaboration features.

2. Open-Source Alternatives to GitHub

If you prefer self-hosting or exploring other platforms, these are excellent alternatives that all speak the same Git language:

GitLab CE/EE: GitLab Community Edition is fully open-source, offering a comprehensive suite of DevOps tools.
Gitea: A lightweight, self-hostable Git service, popular for its ease of deployment and minimal resource footprint.
Forgejo: A community-driven fork of Gitea, focused on open governance.
SourceHut: A minimalist, “Git-first” development platform.

💡 UNIVERSAL COMMANDS
Regardless of the platform, your local Git commands remain almost identical. This is the power of Git!

3. The Typical Workflow: Six Key Concepts & Visualized

To master Git, grasp these six core areas, and visualize their flow.

Working Tree: The actual files in your project directory, including any uncommitted changes.
Staging Area / Index: A temporary area where you select which changes will be included in your next commit.
Commit History: The chronological record of all your project’s commits.
Branch: The current line of development you are working on.
Remote origin: The URL pointing to your online repository (often called origin by default).
Push/Pull: The actions of sending (pushing) or receiving (pulling) changes between your local repository and the remote.

Visualizing the Workflow

A simple mental model helps understand the core Git flow:

Working Directory (Your files)
        ↓ (`git add`)
Staging Area (Index)
        ↓ (`git commit`)
Local Repository (Commit history)
        ↓ (`git push`)
Remote Repository ([GitHub](https://github.com/), [GitLab](https://about.gitlab.com/), etc.)
        ↓ (`git pull`)
(Back to Working Directory for others)

4. Initial Setup: A Clean Start

Setting up Git correctly from the beginning prevents many headaches.

4.1. Set Your Git Identity (For Commits)

These details define the author of your commits; they are not your login credentials for GitHub. The user.name and user.email you set here are what will appear in the commit history on platforms like GitHub.

git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"

How to Check Your Current Git Identity

To see what user.name and user.email are currently set for your active repository or globally:

For the current repository:

git config user.name
git config user.email

Globally (for all repositories):

git config --global user.name
git config --global user.email

How to Change Your Git Identity

To change your Git identity:

Globally (recommended for most users, applies to all new repos):

git config --global user.name "Your New Name"
git config --global user.email "your-new-email@domain.tld"

For only the current repository (overrides global settings for this repo):

git config user.name "Project Specific Name"
git config user.email "project-email@domain.tld"

⚠️ EXISTING COMMITS RETAIN THEIR AUTHOR
Changing these settings only affects future commits. Commits you have already made will retain the `user.name` and `user.email` 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.

4.2. Initialize or Clone a Repository

There are two main ways to start:

Clone an existing repository: This is standard for team projects or contributing to open source.

# Using HTTPS
git clone https://github.com/ORG/REPO.git
# Using SSH
git clone git@github.com:ORG/REPO.git

Initialize a brand-new project: If you’re starting a project from scratch on your local machine.
```
mkdir my-new-project
cd my-new-project
git init
```
You can then connect it to a remote repository later once you create one online.

4.3. Check Your Remotes

Confirm the remote repository is correctly configured:

git remote -v

5. Essential Commands: Your Daily Toolkit

Here are the most frequently used Git commands and their purposes.

Status & Overview

git status
git log --oneline --decorate -n 20
git diff

Stage Files (Prepare for Commit)

git add .
# Or stage specific files:
git add path/to/file

Create a Commit

git commit -m "Brief, descriptive message"

Push / Pull Explained

git push: Sends your local commits to the remote repository.
git pull: Fetches changes from the remote and then merges them into your current local branch.

git push
git pull # = git fetch + git merge

💡 AVOID ACCIDENTAL MERGE COMMITS
For a cleaner history, especially when working on a personal branch, consider using `git pull --rebase`. This fetches remote changes and then re-applies your local commits on top of them, avoiding an explicit merge commit.

Branching (Typical Workflow)

git checkout -b feature/my-new-feature
git push -u origin feature/my-new-feature

Mini-Example: Your First Commit!

Let’s try a complete cycle:

# 1. Create a new directory and initialize Git
mkdir my-first-repo
cd my-first-repo
git init

# 2. Create a file
echo "Hello, Git World!" > index.html

# 3. Check status (it's untracked)
git status

# 4. Stage the file
git add index.html

# 5. Check status again (it's staged)
git status

# 6. Commit the file
git commit -m "Add initial homepage with Hello World"

# 7. Check log (see your commit)
git log --oneline

# At this point, you'd typically connect to a remote and push.
# For now, you have a local commit!

6. Ignoring Files with `.gitignore`

Not every file belongs in your repository. Temporary files, build artifacts, and sensitive data should be ignored.

Why is `node_modules` (or `target/`) in my Git?!

This is a common beginner question. Files generated by your build system (like node_modules for JavaScript or target/ for Rust) should not be committed. They bloat your repository and cause unnecessary merge conflicts.

How to Use `.gitignore`

Create a file named .gitignore in the root of your repository and list the files or directories you want Git to ignore.

# Example .gitignore content
# Node.js dependencies
node_modules/

# Logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# OS generated files
.DS_Store
.env

# Build artifacts (e.g., for Rust)
target/

# Your application's local settings (if applicable)
config/local.yaml

# To create and add to .gitignore:
echo "node_modules/" >> .gitignore
echo "*.log" >> .gitignore
git add .gitignore
git commit -m "Add .gitignore to exclude common temporary files"

💡 EFFECTIVE .GITIGNORE
Make sure `.gitignore` is committed before you add any files that should be ignored. If files are already tracked, adding them to `.gitignore` won’t untrack them. You’d need `git rm --cached <file>` first.

7. Crucial Context: Accounts vs. Repository Permissions

This is where many newcomers (and even seasoned pros) stumble.

GitHub Account (Personal) vs. Company/Organization Repository

On GitHub, repositories are often owned by an Organization (e.g., DELIGHTFUL-corp/my-project).

You log in with a GitHub User Account (which might be your personal one).
This user account needs permissions (e.g., WRITE, MAINTAIN, ADMIN) within the Organization’s repository.
Without sufficient permissions, you might be able to read the repository but not push changes.

Common Pitfall: The Identity Crisis

⚠️ THE STEALTHY 'REPOSITORY NOT FOUND' ERROR
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.

Symptom: Your git push fails, even though you “know” you have access to the repository. The error message is often misleading (fatal: repository 'https://github.com/ORG/REPO.git/' not found) rather than an explicit “permission denied.” GitHub frequently returns a 404 (“not found”) for private repositories when permissions are lacking, to avoid leaking the existence of private repos.

8. Authentication: HTTPS vs. SSH (And Why Your Error Happened)

Authentication methods can be a source of confusion.

HTTPS (Token/Credentials)

With HTTPS, Git requires authentication details. While passwords were used in the past, today it’s almost always:

A Personal Access Token (PAT), or
The GitHub CLI (gh) managing a token for you automatically. The GitHub CLI is an optional but highly recommended tool for smoother authentication workflows.

Installing GitHub CLI

Debian/Ubuntu:

sudo apt update
sudo apt install gh

Arch Linux:

sudo pacman -S github-cli

Your specific stumbling block was classic:

gh repo view ... viewerPermission correctly showed ADMIN (meaning permissions were there).
But git ls-remote origin HEAD reported Repository not found.
This often happens when Git uses incorrect or cached credentials.

The Fix (from your real-world case)

gh auth login
gh auth setup-git

This sequence ensures that Git is configured to use the credentials managed by the GitHub CLI for https://github.com/... remotes.

SSH (Keys)

SSH is often more “set it and forget it” once correctly configured:

You add an SSH public key to your GitHub account.
Your remote URL will look like git@github.com:ORG/REPO.git.
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.

9. Troubleshooting Checklist: When `git push` Acts Up

If git push fails, go through this checklist.

9.1. Is the Remote Correct?

git remote -v

9.2. Can You Even “See” the Repository? (Authenticating Access)

git ls-remote origin HEAD

If this command fails with “repository not found” or “authentication failed,” the issue is almost certainly authentication, the remote URL, or your permissions. This is the first diagnostic step for “git push repository not found” problems.

9.3. Which GitHub Identity is Active (GH CLI)?

gh auth status

9.4. What Permissions Do You Have?

gh repo view ORG/REPO --json viewerPermission

9.5. If HTTPS Credentials are Stuck: Re-link

gh auth setup-git

9.6. Clear Cached Credentials (If Necessary)

printf "protocol=https\nhost=github.com\n\n" | git credential reject

10. Your Minimal Daily Workflow

Once authentication is set up correctly (as it should be now), your daily routine is simple:

# 1. Start by pulling any remote changes (optional, but good practice)
git pull

# 2. Check what you've modified
git status

# 3. Stage your changes
git add .

# 4. Commit your changes
git commit -m "Description of your changes"

# 5. Push your changes to the remote repository
git push

11. Practical Rules: Keeping it Clean Long-Term

Adhere to these rules for a smoother Git experience.

One Identity Per Purpose:
- GitHub Account (login) = Access & Permissions.
- Git user.name/user.email = Commit Author (can be your company identity).
For Private/Org Repos: Always ensure your GitHub user is explicitly part of the Organization’s team with the necessary permissions.
When Switching Accounts: After changing GitHub accounts (e.g., personal to work), always run gh auth status and potentially gh auth setup-git again. This is key to resolving “git authentication failed” issues.
When it says “Repository not found”: First, check git ls-remote origin HEAD. 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.

12. Managing Multiple Git Identities (e.g., Work vs. Personal)

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.

Git applies configurations in a specific order:

Repository-specific (.git/config): These settings override all others for the current repository.
Global (~/.gitconfig): These settings apply to all repositories that don’t have their own specific configuration.
System-wide ($(prefix)/etc/gitconfig): Least specific, rarely modified directly.

Option A (Simple): Set Identity Per Repository

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.

Set your default global identity (e.g., your personal one, or the one you use most often):

git config --global user.name "Your Default Name"
git config --global user.email "your-default@mail.tld"

Navigate to a specific project folder (e.g., a work project).
Set the identity for only this repository:
```
git config user.name "Work Name"
git config user.email "work@company.com"
```
This creates/modifies the .git/config file in that repository.

To verify the local settings:

git config --local user.name
git config --local user.email

Option B (Advanced): Conditional Includes for Directories

If you organize your projects into separate top-level directories (e.g., ~/work/company-projects/ and ~/personal-projects/), you can use Git’s includeIf directive. This automatically applies different configurations based on the path of the repository.

Define your default global identity in ~/.gitconfig (e.g., your personal one):

# ~/.gitconfig
[user]
  name = Dude (Personal)
  email = dude.personal@mail.tld

[includeIf "gitdir:~/work/delightful/"]
  path = ~/.gitconfig-delightful

[includeIf "gitdir:~/personal-projects/"]
  path = ~/.gitconfig-personal

Note: The gitdir: path should end with a / to indicate a directory. Make sure these paths exist on your system.

Create separate configuration files for each specific context.

~/.gitconfig-delightful:

[user]
  name = DELIGHTFUL Inc.
  email = dude.work@delightful.tld

~/.gitconfig-personal:

[user]
  name = Dude (Open Source)
  email = dude.opensource@mail.tld

Now, when you enter a repository within ~/work/delightful/, Git will automatically use the DELIGHTFUL Inc. identity. When you’re in ~/personal-projects/, it will use Dude (Open Source). Any other repository will fall back to the default Dude (Personal).

What if You Use Multiple GitHub Accounts (not just identities)?

If you manage entirely separate GitHub accounts (e.g., github.com/my-personal-account and github.com/my-work-account), you’ll also need to configure separate SSH keys and SSH host aliases in your ~/.ssh/config file. This tells Git which SSH key to use when connecting to github.com 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.

Conclusion

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.

📚OFFICIAL GIT DOCUMENTATION 📦GITHUB DOCUMENTATION

Self-hosting Immich with Docker, Traefik, and CrowdSec

Unknown — Thu, 15 Jan 2026 00:00:00 +0000

Immich 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 existing Traefik v3 reverse proxy and securing it with the CrowdSec IPS.

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.

Changelog

Date	Change
2026-01-15	Initial Version: Immich v1.12x+, Traefik v3 integration, pgvector, and specific CrowdSec bypass notes for mobile sync.

1. Prerequisites

This deployment assumes you have followed our foundational security stack guide. Immich is resource-intensive, especially during the initial scan of your library.

⚠️ HARD REQUIREMENT
The following steps will not work correctly without the Traefik stack running as described in the prerequisite guide: Traefik v3 and CrowdSec with Docker Compose: This provides the `proxy` network and the `crowdsec-bouncer` middleware.

System Recommendations:

RAM: Minimum 4GB (8GB+ recommended for AI/Machine Learning).
Storage: A large dedicated disk or mount point for your photo library.
Domain: A subdomain like photos.your-domain.com.

2. Directory Structure

Immich requires several volumes for its database, machine learning cache, and the actual photo library.

# Create the main directory
sudo mkdir -p /opt/containers/immich
cd /opt/containers/immich

# Create directories for data persistence
sudo mkdir -p volumes/db      # Postgres data
sudo mkdir -p volumes/library # Your actual photos/videos
sudo mkdir -p volumes/model-cache # AI models

3. Configuration

Immich uses a .env file for core settings and a docker-compose.yml for service orchestration.

3.1. Generate Database Password

DB_PASSWORD=$(openssl rand -hex 32)
echo "Your Immich DB password: $DB_PASSWORD"

3.2. Environment Variables (`.env`)

Create the .env file. Replace placeholders with your values.

sudo tee .env > /dev/null << EOF
# --- Database ---
DB_PASSWORD=$DB_PASSWORD
DB_USERNAME=immich
DB_DATABASE_NAME=immich

# --- System ---
TZ=Europe/Vienna
IMMICH_VERSION=release

# --- Library Location ---
# Ensure this path has sufficient space (ideally a dedicated disk)
UPLOAD_LOCATION=./volumes/library

# --- Domain ---
DOMAIN_NAME=photos.your-domain.com
EOF

3.3. Docker Compose (`docker-compose.yml`)

sudo tee docker-compose.yml > /dev/null << 'EOF'
services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - .env
    depends_on:
      - redis
      - database
    restart: unless-stopped
    networks:
      - proxy
      - immich-net
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.immich.rule=Host(`${DOMAIN_NAME}`)"
      - "traefik.http.routers.immich.entrypoints=websecure"
      - "traefik.http.routers.immich.tls.certresolver=tls_resolver"
      # See Section 4.3 for opting out of CrowdSec if needed
      - "traefik.http.routers.immich.middlewares=security-headers@file,crowdsec-bouncer@docker"
      - "traefik.http.services.immich.loadbalancer.server.port=2283"

  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    volumes:
      - ./volumes/model-cache:/cache
    env_file:
      - .env
    restart: unless-stopped
    networks:
      - immich-net

  redis:
    container_name: immich_redis
    image: redis:6.2-alpine
    restart: unless-stopped
    networks:
      - immich-net

  database:
    container_name: immich_postgres
    image: tensorchord/pgvecto-rs:pg16-v0.2.0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
    volumes:
      - ./volumes/db:/var/lib/postgresql/data
    restart: unless-stopped
    networks:
      - immich-net

networks:
  proxy:
    external: true
  immich-net:
    driver: bridge
EOF

4. Hardware & Security Tuning

4.1. Hardware Acceleration (Optional)

Using an iGPU or GPU speeds up video transcoding and AI processing significantly.

💡 TRANSCODING & ML
To enable Intel QuickSync, add the following to both `immich-server` (for video) and `immich-machine-learning` (for AI) in your `docker-compose.yml`: `devices: - /dev/dri:/dev/dri`

4.2. Mobile Apps & CrowdSec

Immich mobile apps (especially on iOS) perform many rapid requests during background synchronization.

⚠️ MOBILE SYNC & FALSE POSITIVES
If you experience “Connection Lost” or sync issues in the mobile app, check your CrowdSec decisions (`cscli decisions list`). Frequent background requests can sometimes trigger rate-limiting or bot-detection scenarios.

4.3. Running Immich without CrowdSec (Optional)

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.

To disable CrowdSec for Immich, update the labels in your docker-compose.yml by removing crowdsec-bouncer@docker:

# In the immich-server labels section:
- "traefik.http.routers.immich.middlewares=security-headers@file"

For more details on why you might want to do this, see:

Scenario 2: Service Bypassing CrowdSec

5. Maintenance & Backup

Updating Immich

cd /opt/containers/immich
sudo docker compose pull
sudo docker compose up -d

Backup Strategy

Gezieltes Database Backup:

# Export only the 'immich' database for a cleaner dump
sudo docker compose exec -t database pg_dump -U immich immich > immich_db_backup_$(date +%F).sql

Conclusion

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.

📚OFFICIAL IMMICH DOCS 📦IMMICH GITHUB

BIOS & Firmware Update on Framework 13 (AMD Ryzen AI 300) under Arch Linux

Unknown — Wed, 14 Jan 2026 00:00:00 +0000

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 Linux Vendor Firmware Service (LVFS). This guide outlines the exact, reproducible workflow to keep your system up to date using fwupd on Arch Linux.

Changelog

Date	Change
2026-01-14	Initial Version: Full protocol for Framework 13 (AMD Ryzen AI 300) BIOS updates.

1. Prerequisites

Before starting the process, ensure your environment meets these requirements:

Hardware: Framework Laptop 13 (AMD Ryzen AI 300 Series, e.g., AI 9 HX 370).
Power: Power adapter must be connected and charging.
Partitioning: EFI System Partition (ESP) must be mounted (usually at /boot or /efi).

⚠️ MANDATORY POWER CONNECTION
The BIOS flash will refuse to start if the laptop is running on battery. Ensure your power cable is securely plugged in before proceeding.

2. Understanding fwupd & LVFS

Framework officially supports firmware updates via:

fwupd: The Firmware Update Daemon that manages the installation.
LVFS: The online repository where vendors upload their firmware.

The process uses UEFI Capsules. fwupd 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.

3. Installation

Install the necessary tools on Arch Linux using pacman:

sudo pacman -S fwupd fwupd-efi

The fwupd.service is a static systemd service. It doesn’t need to be “enabled”; it starts automatically when called. You can verify its status:

systemctl status fwupd.service

4. Refreshing Firmware Metadata

First, update the local database of available firmware from LVFS:

sudo fwupdmgr refresh

If prompted to enable the LVFS remote, confirm with Y.

5. Checking for Updates

List all available updates for your hardware:

sudo fwupdmgr get-updates

You will likely see several entries, such as:

System Firmware (The BIOS/UEFI)
Fingerprint Sensor Firmware
UEFI dbx (Secure Boot revocation list)

6. Performing the Update

ℹ️ SAFETY FIRST
During the update: Do not power off the machine. Do not close the lid. Be patient. The screen may stay black for several minutes.

Start the update process:

sudo fwupdmgr update

What to expect:

Fingerprint Sensor: This usually updates instantly without a reboot.
System Firmware (BIOS): This is the core update. fwupd will schedule it for the next boot.
UEFI dbx: Updates the Secure Boot blacklist. (Note: If you use a custom Secure Boot setup with your own keys, review this step carefully before confirming.)

7. The Reboot & Flash Process

After the command finishes, fwupd will prompt you to restart:

A reboot is required to complete the update.

What happens during reboot:

The system enters a special firmware update mode.
The screen might remain black, and fans might spin up loudly.
Do not interrupt this. There might not be a visible progress bar depending on the specific firmware version.

The system will automatically reboot into Arch Linux once the flash is complete.

8. Verifying Success

Once back in your terminal, verify that all devices are on the latest version:

fwupdmgr get-devices

Alternatively, check the version directly in the BIOS by pressing F2 during startup. You should see the updated version number (e.g., 0.0.3.5).

Summary

Updating firmware on a Framework laptop is a seamless experience that respects the user’s choice of OS:

✅ Full BIOS update support under Linux ✅ No USB-Stick or Windows required ✅ Safe, transactional updates via UEFI Capsules ✅ Officially supported by Framework

🔧OFFICIAL FRAMEWORK BIOS RELEASES 📚ARCH WIKI: FWUPD 🌐FWUPD PROJECT HOME

Enhancing Ranger with exiftool: Advanced Image Metadata Viewing

Unknown — Mon, 12 Jan 2026 00:00:00 +0000

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 exiftool utility with the ranger file manager, allowing you to view comprehensive metadata for images and other media files without leaving your terminal.

Changelog

Date	Change
2026-01-12	Shortcut Update: Switched metadata shortcut from `ei` to `ii` (inspect/media prefix)
2025-07-18	Initial Version: Created guide for integrating exiftool with ranger

1. Prerequisites

Before we begin, make sure you have the following tools installed:

ranger: The terminal file manager
exiftool: A powerful utility for reading, writing, and manipulating metadata

Installation on Various Distributions

# For Debian/Ubuntu
sudo apt update && sudo apt install ranger libimage-exiftool-perl

# For Arch Linux
sudo pacman -S ranger perl-image-exiftool

# For Fedora
sudo dnf install ranger perl-Image-ExifTool

2. Creating the Custom exif_info Command

The integration requires adding a custom command to ranger that will use exiftool to display metadata for the selected file.

2.1. Create or Edit commands.py

First, navigate to your ranger configuration directory and create or edit the commands.py file:

mkdir -p ~/.config/ranger
touch ~/.config/ranger/commands.py

If you don’t have a commands.py file yet, you can generate a template with:

ranger --copy-config=commands

2.2. Add the exif_info Command

Open the commands.py file in your favorite text editor and add the following code:

from ranger.api.commands import Command
import mimetypes
import os
import shlex
import shutil
import subprocess

class exif_info(Command):
    """
    :exif_info

    Shows file metadata using exiftool
    """
    def execute(self):
        f = self.fm.thisfile
        if not f:
            return

        filename = f.path
        if not filename or os.path.isdir(filename):
            return

        mime = None

        if shutil.which("file"):
            try:
                mime = subprocess.check_output(
                    ["file", "--mime-type", "-Lb", filename],
                    text=True,
                    stderr=subprocess.DEVNULL,
                ).strip()
            except Exception:
                mime = None

        if not mime:
            mime, _ = mimetypes.guess_type(filename)

        is_media = False
        if mime:
            is_media = (
                mime.startswith(("image/", "video/", "audio/"))
                or mime == "application/pdf"
            )

        if is_media:
            q = shlex.quote(filename)
            self.fm.execute_command(f"exiftool {q} | less")
        else:
            self.fm.display_file()

This command will:

Detect whether the selected file is an image, video, audio file, or PDF (using file --mime-type when available, with an extension-based fallback)
Run exiftool on media/PDF files and pipe the output to less for easy viewing
Fall back to ranger’s default preview (display_file()) for all other file types

3. Creating a Keyboard Shortcut

Now that we have our custom command, let’s create a keyboard shortcut to invoke it easily.

3.1. Edit rc.conf

Open your ranger configuration file:

vim ~/.config/ranger/rc.conf

If you don’t have this file yet, you can generate it with:

ranger --copy-config=rc

3.2. Add the Keyboard Mapping

Add the following line to map the exif_info command to a keyboard shortcut. In this example, we’ll use ii (which stands for “inspect info”):

map ii exif_info

We use i as a generic inspect / media prefix to group all image and media-related actions and avoid conflicts with ranger’s built-in o (order) commands.

This shortcut is easy to remember as ii stands for “inspect info” - which is exactly what this command does: it shows you detailed metadata information about your files.

Shortcut	Description
`ii`	Show detailed metadata for the selected file using exiftool

4. Advanced Configuration

4.1. Using with Different File Types

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:

Common image formats (JPG, PNG, GIF, TIFF, etc.)
RAW camera formats (CR2, NEF, ARW, DNG, etc.)
Video files (MP4, MOV, AVI, MKV, etc.)
Document formats (PDF, etc.)
Audio files (MP3, FLAC, etc.)

For everything else, it will fall back to ranger’s normal file preview.

4.2. Format the Output

You can customize how the metadata is displayed by modifying the command that calls exiftool. For example, to show only specific tags:

q = shlex.quote(filename)
self.fm.execute_command(f"exiftool -DateTimeOriginal -Make -Model -LensModel -ExposureTime -FNumber -ISO {q} | less")

4.3. Create a Colorized Output

For a more visually appealing output, you can use bat instead of less if you have it installed:

q = shlex.quote(filename)
self.fm.execute_command(f"exiftool {q} | bat --style=plain --color=always | less -R")

5. Usage

Once everything is set up, you can use your new metadata viewing capability:

Open ranger in your terminal
Navigate to an image or media file
Press your configured shortcut (e.g., ii)
Browse through the metadata information
Press q to exit the viewer and return to ranger

6. Practical Examples

6.1. Photography Workflow

For photographers, this integration is particularly useful for quickly checking:

Camera settings (aperture, shutter speed, ISO)
Lens information
Date and time the photo was taken
GPS coordinates (if available)
Copyright information

6.2. Batch Processing

You can combine this with other ranger commands to create a powerful workflow. For example, you could:

Use zi (if you have the fzf integration) to quickly find images
Use ii to check their metadata
Use ranger’s tagging system to organize files based on metadata information

6.3. Checking File Integrity

For downloaded files or files received from others, you can quickly check:

Creation and modification dates
Software used to create the file
Embedded comments or descriptions
File integrity information

7. Troubleshooting

7.1. Command Not Found

If you get a “Command not found” error when trying to use the shortcut:

Make sure you’ve saved the commands.py file correctly
Restart ranger to load the new command
Check that exiftool is installed and in your PATH

7.2. No Metadata Displayed

If no metadata is displayed for a file:

The file might not contain any metadata
The file format might not be supported by exiftool
There might be permission issues with the file

Try running exiftool directly on the file to see if it works outside of ranger:

exiftool path/to/your/file

Summary

With this integration, you’ve enhanced ranger’s capabilities for working with digital media files:

✅ Quick access to comprehensive file metadata ✅ Support for a wide range of file formats ✅ Customizable keyboard shortcuts ✅ Seamless integration with your terminal workflow

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.

📚EXIFTOOL DOCUMENTATION 🔧RANGER CUSTOM COMMANDS 🏷️EXIFTOOL TAG NAMES

Enhance your ranger experience with these additional tutorials:

Ranger and fzf Integration - Add powerful fuzzy search capabilities
File Compression Workflow - Create and extract archives easily
Advanced Media Preview Configuration - Customize file previews for various formats
Ranger and sxiv Integration - Create a seamless image viewing workflow

A Modern Image Optimization Workflow in ranger (with Rofi, ImageMagick & WebP)

Unknown — Mon, 12 Jan 2026 00:00:00 +0000

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.

This guide shows you how to build a fully terminal-based image optimization workflow around ranger, 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.

Changelog

Date	Change
2026-01-12	Shortcut Update: Switched optimization shortcut from `oi` to `io` (inspect/media prefix)
2026-01-09	Initial Version: Created guide for image optimization workflow with Rofi presets

1. Prerequisites

This guide assumes a Linux system with a keyboard-focused workflow. Ensure you have the following tools installed:

ranger: The terminal file manager
ImageMagick: The image processing backend
pngquant: Lossy PNG optimization
oxipng: Lossless PNG optimization
rofi: Interactive preset menu
libwebp: WebP support

ℹ️ NOTE ON IMAGEMAGICK VERSIONS
This workflow supports both ImageMagick 6 (`convert`) and ImageMagick 7 (`magick`). On modern systems, ImageMagick 7 is preferred for better performance and syntax consistency. The script automatically detects which version is available.

1.1. Installation Examples

# Arch Linux
sudo pacman -S ranger imagemagick pngquant oxipng rofi libwebp

# Debian / Ubuntu
sudo apt update && sudo apt install ranger imagemagick pngquant oxipng rofi libwebp

2. Design Goals & Processing Strategy

Before diving into the code, it is important to understand the design principles behind this setup:

Non-destructive: Original images are never modified.
Preset-driven: No manual tweaking of parameters during daily use.
Pixel-safe where required: Graphics and screenshots are handled differently from photos.
Privacy-aware: Metadata is stripped by default.
Fast access: One keybinding opens all optimization options.

2.1. Photos vs Graphics

A critical distinction is made between two image categories:

Photos (JPEG/PNG): Lossy compression is acceptable. Target: small file size for web/social platforms.
Graphics / UI / Screenshots: Pixel integrity matters. Target: lossless or near-lossless processing.

3. Implementation in commands.py

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.

3.1. Edit commands.py

Open your ranger configuration directory:

vim ~/.config/ranger/commands.py

3.2. Add the Optimization Logic

from ranger.api.commands import Command
import os
import shutil
import shlex
import subprocess
from ranger.core.loader import CommandLoader

class scale_base(Command):
    """ Backend logic for image optimization """
    def optimize(self, target_width, quality, mode='lossy', suffix='', force_fmt=None, 
                 keep_meta=False, webp_lossless=False, do_colorspace=True):
        cwd = self.fm.thisdir
        marked_files = cwd.get_selection()

        if not marked_files:
            self.fm.notify("No files selected!", bad=True)
            return

        output_dir = cwd.path

        image_exts = ('.jpg', '.jpeg', '.png', '.webp', '.tif', '.tiff')
        images = [f for f in marked_files if f.path.lower().endswith(image_exts)]

        if not images:
            self.fm.notify("No images found!", bad=True)
            return

        magick_bin = 'magick' if shutil.which('magick') else ('convert' if shutil.which('convert') else None)
        if not magick_bin:
            self.fm.notify("Error: ImageMagick missing!", bad=True)
            return

        pngquant_bin = shutil.which('pngquant')
        oxipng_bin = shutil.which('oxipng')

        self.fm.notify(f"Starting optimization ({suffix})...")

        for f in images:
            base = os.path.basename(f.path)
            name, raw_ext = os.path.splitext(base)
            src_ext = raw_ext.lower()
            out_ext = force_fmt if force_fmt else src_ext
            
            final_suffix = suffix if suffix else f"_w{target_width}_{mode}"
            out_name = f"{name}{final_suffix}{out_ext}"
            dest = os.path.join(output_dir, out_name)
            
            # Avoid overwriting
            counter = 1
            while os.path.exists(dest):
                out_name = f"{name}{final_suffix}_{counter}{out_ext}"
                dest = os.path.join(output_dir, out_name)
                counter += 1

            cmd_im = [magick_bin, f.path, '-auto-orient']
            if target_width > 0:
                cmd_im.extend(['-resize', f'{target_width}x>'])
            if do_colorspace:
                cmd_im.extend(['-colorspace', 'sRGB'])

            do_strip_in_im = True
            if keep_meta:
                do_strip_in_im = False
            elif out_ext == '.png' and mode == 'hq' and oxipng_bin:
                do_strip_in_im = False

            if do_strip_in_im:
                cmd_im.append('-strip')

            if out_ext in ['.jpg', '.jpeg']:
                cmd_im.extend(['-quality', str(quality)])
                if mode == 'lossy':
                    cmd_im.extend(['-sampling-factor', '4:2:0', '-interlace', 'Plane'])
                cmd_im.append(dest)
                self.fm.loader.add(CommandLoader(args=cmd_im, descr=f"JPG {mode}: {base}", read=True))

            elif out_ext == '.webp':
                cmd_im.extend(['-define', 'webp:method=6'])
                if webp_lossless:
                    cmd_im.extend(['-define', 'webp:lossless=true'])
                else:
                    cmd_im.extend(['-quality', str(quality)])
                    cmd_im.extend(['-define', 'webp:alpha-quality=90'])
                cmd_im.append(dest)
                self.fm.loader.add(CommandLoader(args=cmd_im, descr=f"WebP: {base}", read=True))

            elif out_ext == '.png':
                cmd_im.append(dest)
                safe_im_cmd = " ".join(shlex.quote(arg) for arg in cmd_im)

                full_cmd = safe_im_cmd
                descr = f"PNG (IM): {base}"

                if mode == 'lossy' and pngquant_bin:
                    cmd_pq = [pngquant_bin, '--force', '--skip-if-larger', '--speed', '3', '--quality=65-85', dest]
                    safe_pq_cmd = " ".join(shlex.quote(arg) for arg in cmd_pq)
                    full_cmd = f"{safe_im_cmd} && {safe_pq_cmd}"
                    descr = f"PNG Lossy: {base}"
                elif mode == 'hq' and oxipng_bin:
                    cmd_oxi = [oxipng_bin, '-o', '2', '--strip', 'safe', dest]
                    safe_oxi_cmd = " ".join(shlex.quote(arg) for arg in cmd_oxi)
                    full_cmd = f"{safe_im_cmd} && {safe_oxi_cmd}"
                    descr = f"PNG HQ: {base}"

                self.fm.loader.add(CommandLoader(args=['sh', '-c', full_cmd], descr=descr, read=True))

            else:
                cmd_im.append(dest)
                self.fm.loader.add(CommandLoader(args=cmd_im, descr=f"Convert: {base}", read=True))

if True:
    # --- PRESETS ---
    class scale_web(scale_base):
        def execute(self):
            self.optimize(1920, 82, 'lossy', "_web")


    class scale_web_xl(scale_base):
        def execute(self):
            self.optimize(2560, 82, 'lossy', "_webXL")


    class scale_web_hq(scale_base):
        def execute(self):
            self.optimize(1920, 92, 'hq', "_webHQ")


    class scale_blog(scale_base):
        def execute(self):
            self.optimize(1400, 82, 'lossy', "_blog")


    class scale_thumb(scale_base):
        def execute(self):
            self.optimize(600, 75, 'lossy', "_thumb")


    class scale_ig_feed(scale_base):
        def execute(self):
            self.optimize(1080, 85, 'lossy', "_ig")


    class scale_ig_portrait(scale_base):
        def execute(self):
            self.optimize(1350, 85, 'lossy', "_ig4x5")


    class scale_story(scale_base):
        def execute(self):
            self.optimize(1080, 85, 'lossy', "_story")


    class scale_linkedin(scale_base):
        def execute(self):
            self.optimize(1200, 85, 'lossy', "_li")


    class scale_meta_ads(scale_base):
        def execute(self):
            self.optimize(1200, 85, 'lossy', "_ads")


    class scale_jpeg_email(scale_base):
        def execute(self):
            self.optimize(1280, 80, 'lossy', "_email", force_fmt='.jpg')


    class scale_webp_hq(scale_base):
        def execute(self):
            self.optimize(1920, 85, 'lossy', "_web", force_fmt='.webp')


    class scale_webp_lossless(scale_base):
        def execute(self):
            self.optimize(0, 0, 'hq', "_graphic", force_fmt='.webp', webp_lossless=True, do_colorspace=False)


    class scale_webp_no_resize(scale_base):
        def execute(self):
            self.optimize(0, 82, 'lossy', "_webp", force_fmt='.webp')


    class scale_png_graphic(scale_base):
        def execute(self):
            self.optimize(0, 0, 'hq', "_graphic", force_fmt='.png', do_colorspace=False)


    class scale_strip_only(scale_base):
        def execute(self):
            self.optimize(0, 0, 'hq', "_stripped", keep_meta=False, do_colorspace=False)

    # --- ROFI MENU ---
    class image_optimization_menu(Command):
        """ Rofi Menu for Image Optimization """
        def execute(self):
            menu_structure = [
                ("--- WEB ---", "true"),
                ("Web Standard (1920px)", "scale_web"),
                ("Web XL (2560px)", "scale_web_xl"),
                ("Web HQ (1920px)", "scale_web_hq"),
                ("Blog (1400px)", "scale_blog"),
                ("Thumbnail (600px)", "scale_thumb"),
                ("--- SOCIAL ---", "true"),
                ("IG Feed (1080px)", "scale_ig_feed"),
                ("IG Portrait (1350px)", "scale_ig_portrait"),
                ("IG Story/Reel (1080px)", "scale_story"),
                ("LinkedIn (1200px)", "scale_linkedin"),
                ("Meta Ads (1200px)", "scale_meta_ads"),
                ("JPEG Email (1280px)", "scale_jpeg_email"),
                ("--- MODERN/TOOLS ---", "true"),
                ("WebP HQ (1920px)", "scale_webp_hq"),
                ("WebP Lossless (Grafik)", "scale_webp_lossless"),
                ("WebP Convert (Original Size)", "scale_webp_no_resize"),
                ("PNG Graphic (Original, no sRGB)", "scale_png_graphic"),
                ("Strip Metadata Only", "scale_strip_only")
            ]
            
            if not shutil.which('rofi'):
                self.fm.notify("Rofi missing!", bad=True)
                return

            options_str = "\n".join([item[0] for item in menu_structure])

            try:
                p = subprocess.Popen(
                    ['rofi', '-dmenu', '-p', 'Optimize', '-i', '-lines', str(len(menu_structure))],
                    stdin=subprocess.PIPE,
                    stdout=subprocess.PIPE,
                    stderr=subprocess.PIPE,
                    text=True
                )
                stdout, _ = p.communicate(input=options_str)
                selection = stdout.strip()

                if not selection:
                    return

                for label, cmd in menu_structure:
                    if label == selection:
                        if cmd != "true":
                            self.fm.execute_console(cmd)
                        break
            except Exception as e:
                self.fm.notify(f"Error: {e}", bad=True)
                return

4. Creating Keyboard Shortcuts

Now, let’s map the interactive menu to a shortcut.

4.1. Edit rc.conf

Open your rc.conf:

vim ~/.config/ranger/rc.conf

4.2. Add the Mapping

# Image Optimization Menu
map io image_optimization_menu

We use i as a generic inspect / media prefix to group all image and media-related actions and avoid conflicts with ranger’s built-in o (order) commands.

Shortcut	Description
io	Open Rofi menu to select image optimization preset

5. Preset Overview

The workflow provides curated presets for real-world scenarios:

Web Standard (1920px): Balanced compression for websites.
Web XL (2560px): Extra-wide output for large screens.
Web HQ (1920px): Minimal compression for high-quality portfolios.
Blog (1400px): Cleaner sizing for article layouts.
Thumbnail (600px): Small previews.
Instagram Feed (1080px): Optimized for Instagram’s upload limits.
IG Portrait (1350px): 4:5 portrait-friendly sizing.
IG Story/Reel (1080px): Vertical-first exports.
LinkedIn (1200px): Social sharing format.
Meta Ads (1200px): Ad-friendly sizing.
JPEG Email (1280px): Compatibility-first export.
WebP HQ: Modern lossy format for superior size-to-quality ratio.
WebP Lossless (Graphic): Lossless WebP for pixel-perfect graphics.
WebP Convert (Original Size): Convert without resizing.
PNG Graphic (Original, no sRGB): Preserve pixel values and skip sRGB conversion.
Strip Metadata: Removes EXIF/GPS data without changing pixel values.

💡 WHY ROFI?
Rofi provides fuzzy search and instant feedback. It fits perfectly into window manager workflows and avoids the need to memorize dozens of separate keybindings.

6. Practical Use Cases

6.1. Content Publishing

Navigate to your image folder in ranger.
Mark images with Space.
Press io and select Web Standard.
Optimized files appear in the same folder as the originals.

6.2. Privacy Stripping

Before sharing photos online, mark them and run Strip Metadata Only to ensure no GPS or camera information is leaked.

7. Troubleshooting

7.1. Images appear rotated

The script uses -auto-orient before processing. This ensures that the orientation tag is respected even when metadata is stripped.

7.2. Colors look different

Web presets normalize images to sRGB. If you need to preserve a specific color profile, use the Strip Only or PNG Graphic presets which skip colorspace conversion.

8. Summary

With this integration, you’ve transformed ranger into a high-performance image processing station:

✅ Batch processing of multiple images
✅ Searchable Rofi menu for all presets
✅ Background execution via CommandLoader
✅ Support for modern formats like WebP
✅ Optimized for web, social media, and privacy

This setup combines the simplicity of ranger with the industrial-grade power of ImageMagick, ensuring your images are always perfectly optimized for any platform.

📚IMAGEMAGICK CLI DOCS 🔧MORE RANGER TOOLS 🖼️PNGQUANT HOME

Ranger and fzf Integration: Search files at lightning speed
Image Metadata Viewing with exiftool: View EXIF data before optimizing
File Compression Workflow: Archive your optimized assets
Advanced Media Preview Configuration: Better previews for WebP files

Turning on Samsung M51 without Power Button: The Heimdall Method

Unknown — Tue, 09 Dec 2025 00:00:00 +0000

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.

This guide demonstrates a reliable workaround: We force the device into Download Mode using a button combination and use the open-source tool Heimdall on Linux to force a reboot.

ℹ️ COMPATIBILITY
This guide was specifically verified with a Samsung Galaxy M51. However, the method works with almost all Samsung devices that have physical volume keys due to the underlying technology: Galaxy S-Series (e.g., S7 to S21) Galaxy A-Series (e.g., A51, A52, A21s) Galaxy M-Series Galaxy Tab Tablets

Changelog

Date	Change
2025-12-09	Update & Refinement: Updated to Heimdall 2.2.2, added troubleshooting section, and clarified distinction between Warning Screen and Download Mode.
2025-12-08	Initial Version: Guide created based on successful tests with a Samsung Galaxy M51.

1. Prerequisites

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.

⚠️ IMPORTANT: ROOT & BATTERY
No Root on Phone needed: Your smartphone does not need to be rooted. We only need `sudo` rights on the PC to access the USB interface. Charge Battery: Ensure the device has been on the charger for at least 15 minutes, even if the display remained black. Data Cable: Use a fully functional USB data cable, not a charge-only cable.

2. Forcing Download Mode

Since the power button is non-functional, we utilize a service button combination. This step is performed while the device is powered off.

Disconnect Cable: Ensure the USB cable is not connected to the smartphone (but is already plugged into the PC).
Hold Buttons: Press and hold both Volume Up (Vol+) and Volume Down (Vol-) simultaneously.
Connect: While holding both buttons, plug the USB cable into the smartphone.

The display should now light up and show a turquoise Warning Screen (Warning! A custom OS can cause...).

Note: This is not Download Mode yet.

Confirm: Now press the Vol Up key once. Only now does the device switch to the actual Download Mode. The screen will display a large “Downloading…”.

3. Heimdall Setup

We use the tool heimdall, an open-source alternative to Samsung’s Odin.

3.1. Installation

On Arch Linux, install the package as follows (tested with version 2.2.2):

sudo pacman -S heimdall

For Debian/Ubuntu users, the command is usually sudo apt install heimdall-flash.

3.2. Verify Connection

Check if your PC recognizes the smartphone in Download Mode.

heimdall detect

The expected output should be:

Device detected

(If an error occurs here, see Section 5 “Troubleshooting”.)

4. Triggering the Reboot

Now for the crucial step. We send a command to the smartphone that usually cleanly terminates a flashing session.

Run the following command in your terminal:

sudo heimdall close-pc-screen

The Result

You should see a success message in the terminal:

Attempting to close connect to pc screen...
Rebooting device...
Attempt complete

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.

5. Troubleshooting

If it doesn’t work right away, here are the common pitfalls:

Problem: heimdall detect shows “Failed to detect compatible device”

Solution A (Cable): The most common issue is low-quality USB cables. Try a different one, ideally the original Samsung cable.
Solution B (Permissions): Missing udev rules might be the cause. Try running the command with admin privileges: sudo heimdall detect.

Problem: libusb error or Claiming interface failed

Solution: 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.

Problem: Device reboots back into Download Mode

Solution: In rare cases, one of the volume buttons might be stuck physically. Ensure the keys are not jammed.

6. Technical Background

Why does this work?

Hardware Design: Samsung devices have a hardware trigger (Vol+ & Vol- + USB Insert) that activates before the main bootloader. This allows technicians to access the device even with corrupted software or broken physical buttons.
The Protocol: The command close-pc-screen sends a specific End-of-Session command to the bootloader. The bootloader interprets this as “Maintenance successfully finished” and initiates a regular system reboot.

📦HEIMDALL SOURCE CODE 📚ARCH WIKI: HEIMDALL

Deploying Mastodon with Docker and a Modern Traefik Stack

Unknown — Thu, 30 Oct 2025 00:00:00 +0000

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.

This setup ensures a robust, scalable, and secure social media platform that you control.

Changelog

Date	Change
2025-10-30	Initial Version: Guide created, adapting the official Mastodon Docker setup for a modern Traefik v3 and CrowdSec security stack.

1. Prerequisites

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.

⚠️ HARD REQUIREMENT
The following steps will not work correctly without the Traefik stack running as described in the prerequisite guide. Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack: This is the foundation for our public-facing reverse proxy and security.

You will also need:

A dedicated domain for your Mastodon instance (e.g., mastodon.your-domain.com) pointed to your server’s IP address.
sudo or root access.
A functional email (SMTP) server for sending transactional emails.

2. Directory Structure

First, create a dedicated directory for your Mastodon configuration and data. This structure will hold all necessary files and persistent data.

# Create the main directory
sudo mkdir -p /opt/containers/mastodon
cd /opt/containers/mastodon

# Create directories for persistent data
sudo mkdir -p postgres redis public/system

# Mastodon runs as user 991. We need to set the correct permissions.
sudo chown -R 991:991 public/system

3. Configuration

Configuring Mastodon involves generating a configuration file using an interactive wizard and then creating our Docker Compose file to orchestrate the services.

3.1. Docker Compose (`docker-compose.yml`)

First, create the docker-compose.yml file. We create this file before running the setup wizard so that Docker knows which image to use.

sudo tee docker-compose.yml > /dev/null << 'EOF'
services:
  db:
    image: postgres:14-alpine
    restart: unless-stopped
    shm_size: 256mb
    networks:
      - mastodon-net
    healthcheck:
      test: ['CMD', 'pg_isready', '-U', 'postgres']
    volumes:
      - ./postgres:/var/lib/postgresql/data
    environment:
      - 'POSTGRES_HOST_AUTH_METHOD=trust'

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    networks:
      - mastodon-net
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
    volumes:
      - ./redis:/data

  web:
    image: ghcr.io/mastodon/mastodon:v4.4.8
    container_name: mastodon-web
    restart: unless-stopped
    env_file: .env.production
    command: bash -c "rm -f /mastodon/tmp/pids/server.pid; bundle exec rails s -p 3000"
    networks:
      - proxy
      - mastodon-net
    healthcheck:
      test: ['CMD-SHELL', 'wget -q --spider --proxy=off localhost:3000/health || exit 1']
    depends_on:
      - db
      - redis
    user: 991:991
    volumes:
      - ./public/system:/mastodon/public/system
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.mastodon-web.rule=Host(`${MASTODON_HOST}`)"
      - "traefik.http.routers.mastodon-web.entrypoints=websecure"
      - "traefik.http.routers.mastodon-web.tls.certresolver=tls_resolver"
      - "traefik.http.routers.mastodon-web.middlewares=security-headers@file,crowdsec-bouncer@docker"
      - "traefik.http.services.mastodon-web.loadbalancer.server.port=3000"
      - "traefik.docker.network=proxy"

  streaming:
    image: ghcr.io/mastodon/mastodon:v4.4.8 # Note: Since v4.3.0, streaming is part of the main image
    container_name: mastodon-streaming
    restart: unless-stopped
    env_file: .env.production
    command: node ./streaming
    networks:
      - proxy
      - mastodon-net
    healthcheck:
      test: ['CMD-SHELL', 'wget -q --spider --proxy=off localhost:4000/api/v1/streaming/health || exit 1']
    depends_on:
      - db
      - redis
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.mastodon-streaming.rule=Host(`${MASTODON_HOST}`) && PathPrefix(`/api/v1/streaming`)"
      - "traefik.http.routers.mastodon-streaming.entrypoints=websecure"
      - "traefik.http.routers.mastodon-streaming.tls.certresolver=tls_resolver"
      - "traefik.http.routers.mastodon-streaming.middlewares=security-headers@file,crowdsec-bouncer@docker"
      - "traefik.http.services.mastodon-streaming.loadbalancer.server.port=4000"
      - "traefik.docker.network=proxy"

  sidekiq:
    image: ghcr.io/mastodon/mastodon:v4.4.8
    container_name: mastodon-sidekiq
    restart: unless-stopped
    env_file: .env.production
    command: bundle exec sidekiq
    depends_on:
      - db
      - redis
    networks:
      - mastodon-net
    volumes:
      - ./public/system:/mastodon/public/system
    healthcheck:
      test: ['CMD-SHELL', "ps aux | grep '[s]idekiq' || false"]
    user: 991:991

networks:
  proxy:
    external: true
  mastodon-net:
    driver: bridge
EOF

ℹ️ A NOTE ON DATABASE SECURITY
The `POSTGRES_HOST_AUTH_METHOD=trust` 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 `docker-compose.yml` to connect without a password. For production environments with stricter security requirements, you should configure proper password-based authentication.

💡 TRAEFIK LABELS EXPLAINED
The `labels` section is crucial. It tells our Traefik proxy how to handle requests for Mastodon. `tls.certresolver=tls_resolver`: This uses the Let’s Encrypt resolver we defined in our main Traefik stack. `middlewares=security-headers@file,crowdsec-bouncer@docker`: This is the key integration. It applies our predefined security headers and protects the instance with the CrowdSec bouncer, blocking malicious IPs.

3.2. Environment File (`.env`)

Create a simple .env file to store your domain name. The docker-compose.yml will use this.

sudo tee .env > /dev/null << 'EOF'
MASTODON_HOST=mastodon.your-domain.com
EOF

⚠️ IMPORTANT
Replace `mastodon.your-domain.com` with your actual domain. This file is separate from the main Mastodon configuration (`.env.production`) that we will generate next.

3.3. Mastodon Setup Wizard

Mastodon provides an interactive setup wizard to generate its main configuration file (.env.production). Let’s run it.

# This command runs the setup task in a temporary container
sudo docker compose run --rm web bundle exec rake mastodon:setup

The wizard will ask you a series of questions. Here are some recommendations:

Domain name: Enter the same domain you used in your .env file (e.g., mastodon.your-domain.com).
Single user mode?: n (unless you want a private, single-person instance).
Are you using Docker?: y. This will correctly set the database and Redis hostnames.
Database host: It should default to db. Press Enter.
Redis host: It should default to redis. Press Enter.
SMTP settings: Provide the details for your email server. Mastodon needs this to send confirmation emails.
Save configuration?: y. This will create the .env.production file.

4. Launch the Stack

Now that all configuration is in place, you can start your Mastodon instance.

4.1. Initial Database Migration

Before the first full launch, we need to prepare the database.

# Run the database migration in a temporary container
sudo docker compose run --rm web rails db:migrate

4.2. Start All Services

With the database ready, bring the entire stack online.

sudo docker compose up -d

The first launch will take a few minutes as Docker downloads the images. You can monitor the progress with sudo docker compose logs -f.

5. Post-Installation Steps

Your instance is running, but you need to create an admin account.

# Use this command to create an admin user interactively
sudo docker compose run --rm web tootctl accounts create YOUR_USERNAME \
  --email YOUR_EMAIL@example.com --confirmed --role Admin

Replace YOUR_USERNAME and YOUR_EMAIL@example.com with your desired credentials. You will be prompted to set a password.

You can now navigate to https://mastodon.your-domain.com and log in with your new admin account.

6. Maintenance

Updating Mastodon

Updating is a straightforward process. First, check the official Mastodon release notes for any special instructions.

cd /opt/containers/mastodon

# Update the image tags in your docker-compose.yml to the new version

# Pull the new images
sudo docker compose pull

# Stop the services before migrating the database
sudo docker compose down

# Run database migrations required by the new version
sudo docker compose run --rm web rails db:migrate

# Start the stack again
sudo docker compose up -d --remove-orphans

Backing Up

A complete backup consists of the database, user-uploaded files, and Redis data.

cd /opt/containers/mastodon

# 1. Back up the database
sudo docker compose exec -T db pg_dump -U postgres -d mastodon_production | gzip > mastodon_db_backup_$(date +%F).sql.gz

# 2. Back up user-uploaded files
sudo tar -czvf mastodon_files_backup_$(date +%F).tar.gz public/system

# 3. Back up Redis data
sudo tar -czvf mastodon_redis_backup_$(date +%F).tar.gz redis

Conclusion

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.

📚OFFICIAL MASTODON DOCS 📦OFFICIAL GITHUB REPO

Deploying Mailcow with Docker and Traefik for a Full E-Mail Stack

Unknown — Fri, 03 Oct 2025 00:00:00 +0000

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.

Changelog

Date	Change
2025-10-03	Major Revision: Corrected `certdumper` command, simplified Traefik labels, and fixed critical `mailcow.conf` networking settings to resolve 404 errors. Enhanced troubleshooting for network conflicts.
2025-09-18	Initial Version: First version of this guide was created.

1. Prerequisites

This guide assumes you have a fully functional server environment with the following components already set up:

Traefik v3 and CrowdSec with Docker Compose: This is the foundation for our reverse proxy, security, and certificate management.
Docker and Docker Compose: Must be installed on your server.
Required Tools: You will need git and jq. Install them with:
```
sudo apt update && sudo apt install -y git jq
```
sudo or root access.

2. Directory Structure

First, create a dedicated directory for your Mailcow installation.

ℹ️ PATH CONSISTENCY
This guide uses `/opt/containers/mailcow/` as the primary directory for the Mailcow stack. The Traefik stack is assumed to be in `/opt/containers/traefik-stack/`, consistent with our Traefik v3 tutorial. If your paths differ, be sure to adjust them in all configuration files and commands throughout this guide.

sudo mkdir -p /opt/containers/mailcow

3. Clone the Mailcow Repository

Clone the latest version of the Mailcow Dockerized project from GitHub into the directory you just created.

sudo git clone https://github.com/mailcow/mailcow-dockerized /opt/containers/mailcow

4. Generate the Configuration File

Navigate into the new directory and run the configuration generation script.

cd /opt/containers/mailcow
./generate_config.sh

You will be prompted for the following information:

Mail server hostname (FQDN): Enter the fully qualified domain name for your mail server, for example, mail.your-domain.com.
Timezone: Press Enter to accept the default or provide your own.
Available Branches: Press 1 to select the master branch.

5. Configure for Traefik Integration

To make Mailcow work with our external Traefik instance, we need to create an override file and modify the main configuration.

5.1. Create `docker-compose.override.yml`

This file contains all our customizations, telling Mailcow to use the external proxy network and defining labels for Traefik to route traffic correctly. It also sets up a certdumper service, which is crucial for sharing Traefik’s Let’s Encrypt certificates with Mailcow’s services (Postfix and Dovecot).

ℹ️ HOW THE CERTDUMPER WORKS
The `certdumper` is essential. It extracts certificates from Traefik’s `acme.json` and saves them as `.pem` files that Postfix and Dovecot can read. The command `--restart-containers mailcowdockerized-postfix-mailcow-1,...` 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.

Create the file:

sudo tee /opt/containers/mailcow/docker-compose.override.yml > /dev/null << 'EOF'
networks:
  proxy:
    name: proxy
    external: true

services:
  certdumper:
    image: ghcr.io/kereis/traefik-certs-dumper:latest
    restart: unless-stopped
    network_mode: none
    # Correct command to restart containers by their full name. Mailcow's project name is "mailcowdockerized".
    command: --restart-containers mailcowdockerized-postfix-mailcow-1,mailcowdockerized-dovecot-mailcow-1
    volumes:
      # Adjust this path to match YOUR Traefik stack's certificate location
      - /opt/containers/traefik-stack/traefik/certs:/traefik:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./data/assets/ssl:/output:rw
    environment:
      DOMAIN: ${MAILCOW_HOSTNAME}
      # Adjust this to match YOUR Traefik acme file name
      ACME_FILE_PATH: "/traefik/acme.json"
    healthcheck:
      test: ["CMD", "/usr/bin/healthcheck"]
      interval: 30s
      timeout: 10s
      retries: 5

  nginx-mailcow:
    # We use !reset to completely remove the default port bindings set by Mailcow.
    ports: !reset
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"

      # HTTPS Router (Secure)
      # The HTTP to HTTPS redirect is handled globally by our Traefik setup, so we only need the secure router.
      - "traefik.http.routers.nginx-mailcow-secure.entrypoints=websecure"
      - "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`)"
      - "traefik.http.routers.nginx-mailcow-secure.tls=true"
      - "traefik.http.routers.nginx-mailcow-secure.tls.certresolver=tls_resolver"
      - "traefik.http.routers.nginx-mailcow-secure.service=nginx-mailcow"
      - "traefik.http.routers.nginx-mailcow-secure.middlewares=security-headers@file,crowdsec-bouncer@docker"

      # Service Definition: Point to Mailcow's internal Nginx port.
      # This must be 80, as we are NOT changing the internal ports in mailcow.conf
      - "traefik.http.services.nginx-mailcow.loadbalancer.server.port=80"
EOF

ℹ️ CROWDSEC BOUNCER SCOPE
The `crowdsec-bouncer@docker` middleware only protects the HTTP/HTTPS endpoints routed through Traefik (like the Mailcow UI and SOGo). It does not 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 `crowdsecurity/postfix` and `crowdsecurity/dovecot` collections on the host).

⚠️ IMPORTANT
You must replace `your-domain.com` with your actual domain name. You can do this manually or with the following command: `sudo sed -i "s/your-domain.com/your-actual-domain.com/g" docker-compose.override.yml`

5.2. Adjust `mailcow.conf`

Next, edit the main configuration file. There are only two changes needed here.

sudo nano /opt/containers/mailcow/mailcow.conf```

{% <infobox type="danger" title="Critical: Do Not Change Ports or Bindings!"> %}
Do **not** change `HTTP_PORT`, `HTTPS_PORT`, `HTTP_BIND`, or `HTTPS_BIND`. Leaving them at their default values is crucial. Changing `HTTP_BIND` to `127.0.0.1` will prevent Traefik from reaching the Mailcow web UI, resulting in a **404 Not Found error**. The internal ports do not conflict with Traefik because they are inside the Docker network, not on the host.
{% </infobox> %}

1.  **Disable Mailcow's Let's Encrypt:** Traefik is responsible for all certificate management. This is the most important change.
    ```ini
    # Find this line:
    SKIP_LETS_ENCRYPT=n
    # Change it to:
    SKIP_LETS_ENCRYPT=y
    ```


2.  **Add SAN for Internal TLS:** This helps internal services correctly recognize the hostname on the certificate provided by the `certdumper`.
    ```ini
    # Find this line (it may be commented out):
    # ADDITIONAL_SAN=
    # Change it to:
    ADDITIONAL_SAN=${MAILCOW_HOSTNAME}
    ```

Save and close the file. No other changes are needed in this file.

### 5.3. Activate MTA-STS

MTA-STS (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.


<table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1">
    <tr>
        <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;">
            💡 
            EASIER ALTERNATIVE: USE THE MAILCOW UI
        </td>
    </tr>
    <tr>
        <td bgcolor="#000000" style="color: #ffffff;">
<p>Instead of creating the policy file by hand, you can navigate to <strong>System -&gt; Configuration -&gt; MTA-STS</strong> 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.</p>

</td>
</tr>
</table>


If you choose the manual route, create the required directory:
```bash
sudo mkdir -p /opt/containers/mailcow/data/web/.well-known/

Now, create the policy file with a simple enforce policy. This file will be served by Mailcow’s web server.

sudo tee /opt/containers/mailcow/data/web/.well-known/mta-sts.txt > /dev/null << 'EOF'
version: STSv1
mode: enforce
max_age: 15552000
mx: mail.your-domain.com
EOF

⚠️ IMPORTANT
You must replace `your-domain.com` with your actual domain name in the file above. You can do this with the following command: `sudo sed -i "s/your-domain.com/your-actual-domain.com/g" /opt/containers/mailcow/data/web/.well-known/mta-sts.txt`

6. Launch Mailcow

You can now start the Mailcow stack.

cd /opt/containers/mailcow
docker compose up -d

💡 TROUBLESHOOTING TIPS
Pool Overlaps: If you see an error like `Pool overlaps with other one on this address space`, another Docker network is using Mailcow’s default IP range. You can fix this permanently by editing `mailcow.conf` and setting `IPV4_NETWORK` to an unused subnet prefix (e.g., `IPV4_NETWORK=172.25.1`). Mailcow will correctly append `.0/24` to create the network. RAM Usage: On a VPS with limited memory, you can disable resource-intensive services by setting `SKIP_FTS=y` (disables full-text search in Solr) or `SKIP_CLAMD=y` (disables the ClamAV antivirus engine) in `mailcow.conf`. This reduces security and functionality, so use it with caution. IPv6 Issues: Some Mailcow versions had startup issues when `ENABLE_IPV6=y` was set. If you face problems, check the official Mailcow blog for release notes and patches.

7. DNS Configuration

Correct DNS setup is critical for a mail server to function.

7.1. Reverse DNS (PTR Record)

Your server’s Reverse DNS (PTR) record for both IPv4 and IPv6 must match the hostname you configured in mailcow.conf (mail.your-domain.com). 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.

7.2. DNS Records

⚠️ USING CLOUDFLARE?
If you are using Cloudflare for your DNS, all mail-related records (including `mail`, `imap`, `smtp`, `autodiscover`, `autoconfig`, and `mta-sts`) must 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 official Cloudflare documentation.

In your domain’s DNS management panel, add the following records. We start with a non-restrictive DMARC policy (p=none) to prevent legitimate emails from being rejected during the initial setup.

⚠️ GMAIL & YAHOO SENDER REQUIREMENTS (2024)
As of 2024, major providers like Gmail and Yahoo enforce stricter sender policies: All Senders: Must have either SPF or DKIM configured. Bulk Senders (5,000+ emails/day): Must have SPF, DKIM, and a DMARC policy. They also require one-click unsubscribe links and must maintain a low spam complaint rate. Failing to meet these requirements will result in your emails being rejected. For more details, see the official announcements from Google and Yahoo.

ℹ️ DMARC STAGED ROLLOUT
Starting with `p=none` is the safest approach. This allows you to monitor email traffic via the reports sent to your `rua` address without affecting mail delivery. Monitor: Keep `p=none` for a few weeks and analyze the reports to ensure all legitimate sending sources are correctly authenticated with SPF and DKIM. Quarantine: Once you are confident, switch to `p=quarantine`. This tells receiving servers to treat failing emails with suspicion (e.g., by sending them to the spam folder). Reject: After another monitoring period, you can move to the final policy, `p=reject`, which instructs receivers to block emails that fail DMARC checks.

Name	Type	Value
mail	A	your-server-ip
mail	AAAA	your-server-ipv6
autodiscover	CNAME	mail.your-domain.com.
autoconfig	CNAME	mail.your-domain.com.
imap	CNAME	mail.your-domain.com.
pop3	CNAME	mail.your-domain.com.
smtp	CNAME	mail.your-domain.com.
@	MX 10	mail.your-domain.com.
SPF
@	TXT	`v=spf1 mx a -all`

💡 SPF FINE-TUNING
The `v=spf1 mx a -all` record is a safe default. The `a` part authorizes the server’s main IP address (from the `A` record) to send mail. If you only send mail from Mailcow, you can make this slightly stricter by using `v=spf1 mx -all`, which only authorizes servers listed in your `MX` records.

A DKIM record will be added later after it’s generated by Mailcow.

ℹ️ UNUSED SRV RECORDS
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.

ℹ️ DNS RECORD NOTES
A vs. CNAME for `mta-sts`: We use `A`/`AAAA` records for `mta-sts` pointing directly to the server’s IP. While a `CNAME` pointing to `mail.your-domain.com` is also valid, using `A`/`AAAA` records avoids potential edge cases with some DNS resolvers. Trailing Dots: Note the trailing dot (`.`) at the end of hostnames in `MX` and `SRV` records (e.g., `mail.your-domain.com.`). This signifies that the name is fully qualified. Some DNS providers add this automatically, while others require you to add it manually.

8. Firewall Configuration

Your firewall must allow traffic on several ports for email services to be reachable.

Port	Service	Protocol
25	SMTP	TCP
587	Submission	TCP
465	SMTPS	TCP
143	IMAP	TCP
993	IMAPS	TCP
110	POP3	TCP
995	POP3S	TCP
4190	ManageSieve	TCP

💡 PROTOCOL HYGIENE
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.

ℹ️ RESERVED INTERNAL PORTS
Mailcow uses several ports internally (e.g., 8081, 9081, 65510). Avoid using these for your own services on the Docker host to prevent conflicts.

Use ufw to open these ports:

⚠️ DOCKER BYPASSES UFW RULES
By default, Docker manipulates `iptables` directly and bypasses UFW rules, meaning your container ports might be exposed even if `ufw` is configured to block them. There are two effective ways to mitigate this: Bind Services to Localhost (Recommended): As we did in `mailcow.conf` with `HTTP_BIND`, binding services to `127.0.0.1` ensures they are never exposed externally by Docker. This is the most secure approach. Modify UFW’s Configuration: For services that must be exposed, you can edit `/etc/ufw/after.rules` to correctly manage traffic from Docker’s network. This is more complex but necessary for direct external access. For more details, see the official Docker documentation on packet filtering.

sudo ufw allow 25/tcp
sudo ufw allow 587/tcp
sudo ufw allow 465/tcp
sudo ufw allow 143/tcp
sudo ufw allow 993/tcp
sudo ufw allow 110/tcp
sudo ufw allow 995/tcp
sudo ufw allow 4190/tcp
sudo ufw status

9. Initial Mailcow Setup

Navigate to your Mailcow UI at https://mail.your-domain.com.

Default Username: admin
Default Password: moohoo

First, change the administrator password under System -> Configuration -> Edit.

9.1. Add Your Domain

Go to Email -> Configuration and click “Add domain”. Enter your main domain (e.g., your-domain.com, not mail.your-domain.com).

9.2. Generate DKIM Key

A DKIM key is essential for email authentication.

Go to System -> Configuration.
Navigate to the Options -> ARC/DKIM keys tab.
A 2048-bit key should already be generated for your domain. Copy the public key text from the text box.
Go back to your DNS provider and add a new TXT record:
- Name: dkim._domainkey
- Value: Paste the entire copied key, including the v=DKIM1;k=rsa;p=... part.

💡 LONG DKIM RECORDS

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.

10. Testing and Verification

After waiting for DNS propagation, thoroughly test your setup.

10.1. Internal DNS and Certificate Check

Mailcow DNS Check: In the Mailcow UI, go to Email -> Configuration -> DNS next to your domain for an internal check of your records.
Verify Certificates: Ensure that the certificates from Traefik have been correctly passed to Mailcow’s services. Run these commands, replacing mail.your-domain.com with your mail server’s FQDN:
```
# Check SMTP certificate
echo "Q" | openssl s_client -starttls smtp -crlf -connect mail.your-domain.com:587

# Check IMAP certificate
echo "Q" | openssl s_client -starttls imap -crlf -connect mail.your-domain.com:143
```
In the output, look for a certificate chain issued by a trusted authority. For Let’s Encrypt, the chain typically starts with ISRG Root X1. The key is to confirm it is not a self-signed certificate. If you see a self-signed certificate (where the issuer matches the subject), it indicates a problem with the certdumper service or its path mappings. In that case, check the certdumper logs:
```
cd /opt/containers/mailcow
docker compose logs certdumper
```

10.2. External Testing Tools

mail-tester.com: Send an email to the address provided on their site to get a score out of 10.
mxtoolbox.com: Provides various checks for your mail server.
checktls.com/TestReceiver: Use this to specifically verify your MTA-STS configuration.

11. Create Mailboxes and Log In

Under Email -> Mailboxes, you can add new users. Once a user is created, the primary way to access the webmail interface (SOGo) is by clicking Apps -> Webmail from within the Mailcow UI. While you can also try going directly to https://mail.your-domain.com/SOGo/, be aware that recent Mailcow versions may redirect unauthenticated access back to the main login page.

12. Conclusion

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.

13. Further Reading

For more detailed information, refer to the official Mailcow documentation:

Reverse Proxy Overview: docs.mailcow.email/post_installation/reverse-proxy/r_p/
IP Bindings: docs.mailcow.email
MTA-STS Setup: docs.mailcow.email

🛡️TEST YOUR EMAIL SCORE

Deploying a Secure Nginx Website with Traefik and Docker Compose

Unknown — Wed, 17 Sep 2025 00:00:00 +0000

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.

Changelog

Date	Change
2026-06-12	Matrix Federation: Corrected the future Matrix `.well-known` federation port to `8448`.
2025-09-17	Initial Version: Article created to demonstrate a secure Nginx deployment behind a Traefik v3 stack.

1. Prerequisites

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.

⚠️ CRUCIAL PREREQUISITE
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: Traefik v3 and CrowdSec with Docker Compose: A Modern Security Stack: This is the foundation for our reverse proxy and security. If you haven’t already created the external network for Traefik, do so now: `docker network create proxy`

You will also need:

Docker and Docker Compose installed on your server.
A domain name pointed to your server’s IP address.
sudo or root access.

2. Directory Structure

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.

# Create the main directory for your Nginx site
sudo mkdir -p /opt/containers/nginx
cd /opt/containers/nginx

# Create subdirectories for configuration and website files
sudo mkdir conf html

This structure separates your Nginx configuration from your actual website content.

3. Configuration Files

Next, we will create the necessary configuration files for Nginx and Docker Compose.

3.1. Environment File (`.env`)

First, create a .env file to store your domain name. This makes the configuration cleaner and easier to update.

sudo tee .env > /dev/null << 'EOF'
DOMAIN_NAME=your-domain.com
EOF

⚠️ IMPORTANT
Replace `your-domain.com` with your actual domain name.

3.2. Docker Compose File

Now, create the docker-compose.yml file. It will read the DOMAIN_NAME variable from your .env file.

sudo tee docker-compose.yml > /dev/null << 'EOF'
services:
  nginx:
    image: nginx:1.27.1
    container_name: nginx
    restart: unless-stopped
    volumes:
      - ./html:/usr/share/nginx/html:ro
      - ./conf/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./conf/mime.types:/etc/nginx/mime.types:ro
    labels:
      - "traefik.enable=true"
      # --- Routing ---
      - "traefik.http.routers.nginx.rule=Host(`${DOMAIN_NAME}`) || Host(`www.${DOMAIN_NAME}`)"
      - "traefik.http.routers.nginx.entrypoints=websecure"
      - "traefik.http.routers.nginx.tls=true"
      - "traefik.http.routers.nginx.tls.certresolver=tls_resolver"

      # --- Middlewares ---
      # 1. CORS headers for Matrix federation (defined on-the-fly)
      - "traefik.http.middlewares.nginx-cors.headers.accessControlAllowMethods=GET,OPTIONS,PUT,POST"
      - "traefik.http.middlewares.nginx-cors.headers.accessControlAllowHeaders=*"
      - "traefik.http.middlewares.nginx-cors.headers.accessControlAllowOriginList=*"
      
      # 2. Assignment of all middlewares
      - "traefik.http.routers.nginx.middlewares=security-headers@file,crowdsec-bouncer@docker,nginx-cors@docker"

      # --- Service Definition ---
      - "traefik.http.services.nginx.loadbalancer.server.port=80"
    networks:
      - proxy

networks:
  proxy:
    external: true
EOF

Key Points from this file:

labels: These are instructions for Traefik. We define routing, TLS, and a chain of middlewares.
middlewares: We apply three middlewares: security-headers (from a file), crowdsec-bouncer (from the Traefik service’s own labels), and nginx-cors. The nginx-cors middleware is defined on-the-fly here and is critical for Matrix federation, as it allows other servers to access the .well-known delegation files. For a standard website without Matrix integration, this middleware and its assignment can be omitted.
volumes: We mount our local html and conf directories into the container as read-only (ro) for better security.
networks: The service is attached to the external proxy network, allowing it to communicate with the Traefik container.

3.3. Nginx Configuration

Next, create the main Nginx configuration file at /opt/containers/nginx/conf/nginx.conf. This file controls the behavior of the web server and is optimized for serving a static site with Gzip compression.

sudo tee conf/nginx.conf > /dev/null << 'EOF'
worker_processes  2;
user              www-data;

events {
    use           epoll;
    worker_connections  128;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    # --- Basic Settings ---
    sendfile        on;
    tcp_nopush      on;
    tcp_nodelay     on;
    keepalive_timeout  65;
    types_hash_max_size 2048;

    # --- Gzip Settings ---
    gzip on;
    gzip_disable "msie6";
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_buffers 16 8k;
    gzip_http_version 1.1;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    # --- Main Server Block ---
    server {
        listen 80;
        server_name _;

        root /usr/share/nginx/html;
        index index.html;

        location / {
            try_files $uri $uri/ =404;
        }

        # --- Future-Proofing for Matrix Synapse ---
        location /.well-known/matrix/server {
            return 200 '{"m.server": "matrix.YOUR_DOMAIN_COM_PLACEHOLDER:8448"}';
            add_header "Content-Type" "application/json";
        }
        location /.well-known/matrix/client {
             return 200 '{"m.homeserver": {"base_url": "https://matrix.YOUR_DOMAIN_COM_PLACEHOLDER"}, "m.identity_server": {"base_url": "https://vector.im"}}';
             add_header "Content-Type" "application/json; charset=utf-8";
             add_header "Access-Control-Allow-Origin" "*";
        }

        # --- Error Pages ---
        error_page 404 /404.html;
        location = /404.html {
            internal;
        }

        error_page 500 502 503 504 /50x.html;
        location = /50x.html {
            internal;
        }
    }
}
EOF

Now, read the .env file and use sed to replace the placeholders:

export $(grep -v '^#' .env | xargs)
sudo sed -i "s/YOUR_DOMAIN_COM_PLACEHOLDER/${DOMAIN_NAME}/g" conf/nginx.conf

ℹ️ PREPARING FOR MATRIX SYNAPSE
The `location /.well-known/matrix` blocks are included as a forward-thinking measure. They are required for setting up a federated Matrix Synapse server 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.

3.4. Mime Types

Create a mime.types file at /opt/containers/nginx/conf/mime.types. This file ensures that Nginx sends the correct Content-Type header for various file formats, which is particularly important for web fonts and modern web assets.

sudo tee conf/mime.types > /dev/null << 'EOF'
types {
    text/html                                        html htm shtml;
    text/css                                         css;
    text/xml                                         xml;
    image/gif                                        gif;
    image/jpeg                                       jpeg jpg;
    application/javascript                           js;
    application/atom+xml                             atom;
    application/rss+xml                              rss;

    # Fonts
    application/vnd.ms-fontobject                    eot;
    font/truetype                                    ttf;
    font/opentype                                    otf;
    font/woff                                        woff;
    font/woff2                                       woff2;

    image/svg+xml                                    svg svgz;
    image/png                                        png;
    image/x-icon                                     ico;
}
EOF

3.5. Website Content

Before launching the server, place your website files into the /opt/containers/nginx/html directory. For a quick test, create a simple index.html file within it.

# Create a simple index.html for testing
sudo tee html/index.html > /dev/null << 'EOF'
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Welcome to My Nginx Site</title>
    <style>
        body { font-family: sans-serif; background-color: #f0f0f0; text-align: center; padding: 50px; }
        h1 { color: #333; }
    </style>
</head>
<body>
    <h1>Success!</h1>
    <p>Your Nginx website is running securely behind Traefik.</p>
</body>
</html>
EOF

# Create custom error pages
sudo tee html/404.html > /dev/null << 'EOF'
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>404 Not Found</title>
</head>
<body>
    <h1>404 - Page Not Found</h1>
    <p>The page you are looking for does not exist.</p>
</body>
</html>
EOF

sudo tee html/50x.html > /dev/null << 'EOF'
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Server Error</title>
</head>
<body>
    <h1>50x - Server Error</h1>
    <p>An internal server error occurred.</p>
</body>
</html>
EOF

5. Launch and Verify

With all the files in place, you can start your Nginx container. Use docker compose for consistency with the main Traefik stack.

# Navigate to your project directory if you aren't already there
cd /opt/containers/nginx

# Start the service in the background
docker compose up -d

You can check the status of your new container with docker compose ps. It should show a state of Up.

Now, open a web browser and navigate to https://your-domain.com. You should see the “Success!” message from your index.html file, served over a secure HTTPS connection managed by Traefik.

6. Conclusion

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 Matrix Synapse server.

Secure Server-to-Server File Transfers with rsync and tmux

Unknown — Fri, 08 Aug 2025 00:00:00 +0000

This guide provides a definitive, “terminal-first” approach to transferring large amounts of data directly between two remote servers. By combining the power of rsync for data synchronization, tmux 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.

This method avoids routing traffic through your local machine, saving you bandwidth and making the process immune to local network disconnects.

Changelog

Date	Change
2025-08-08	Initial Version: Article created.

1. The Goal: Direct, Robust Server-to-Server Transfers

Before we begin, it’s essential to understand the data flow we are building.

ℹ️ UNDERSTANDING THE ARCHITECTURE
The goal is to initiate a transfer that runs entirely on Server1, pulling data from itself and pushing it directly to Server2. Your local computer is only used to set up the infrastructure and start the process; it can be disconnected immediately afterward. Data Flow: `Server1 (Source) ---(Data Transfer)---> Server2 (Destination)`

2. Prerequisites

You have key-based SSH access from your local computer to two Linux servers, Server1 and Server2.
Password authentication on your servers is (correctly) disabled.
You have sudo or root privileges on Server1 to install software.

Local SSH Configuration (For Your Convenience)

Define aliases for your servers in your local computer’s ~/.ssh/config file. This only makes it easier for you to connect; it does not affect the servers themselves.

# In ~/.ssh/config on your LOCAL machine
Host Server1
    HostName cloud.server1.xyz
    User your_user

Host Server2
    HostName cloud.server2.xyz
    User root
    Port 2222 # Use your actual port

3. The Core Method: Building the Key Infrastructure

This is the most critical part of the tutorial. We will:

Create a deploy key on Server1.
Configure the SSH client on Server1 so it knows how to find Server2.
Use our local PC as a trusted intermediary to securely install and restrict the key on Server2.

3.1. On Server1: Create the Deploy Key

# On your local machine, connect to Server1
ssh Server1

# Now, on Server1, generate a new, passwordless SSH key pair
# When prompted for a passphrase, press Enter twice to leave it empty.
ssh-keygen -t ed25519 -f ~/.ssh/id_deploy_to_server2 -C "rsync deploy key for server2"

3.2. On Server1: Configure its SSH Client

We must teach Server1 how to connect to Server2. We do this by creating a config file in its .ssh directory.

# On Server1, create and open the config file
nano ~/.ssh/config

Add the following configuration. Replace the values with the actual connection details for Server2.

Host Server2
    HostName cloud.server2.xyz
    User root
    Port 2222
    IdentityFile ~/.ssh/id_deploy_to_server2

IdentityFile: This line is key. It tells Server1’s SSH client: “When connecting to the host aliased as ‘Server2’, always use this specific private key.”

Save the file (Ctrl+X, then Y, then Enter) and set the correct permissions:

# On Server1
chmod 600 ~/.ssh/config

3.3. On Server1: Copy the Public Key for Transfer

Display the public key so you can copy it to your clipboard.

# On Server1
cat ~/.ssh/id_deploy_to_server2.pub

Action: Mark and copy the entire output (the line starting ssh-ed25519 AAAA...). Then, log out from Server1.

exit

3.4. From Your Local PC: Install and Restrict the Key on Server2

# 1. On your local PC, append the key to Server2's authorized_keys.
#    Replace 'PASTE_KEY_FROM_CLIPBOARD_HERE' with the key you just copied.
ssh Server2 "echo 'PASTE_KEY_FROM_CLIPBOARD_HERE' >> ~/.ssh/authorized_keys"

# 2. Now, SSH to Server2 to restrict the key.
ssh Server2

# 3. Once on Server2, open the file for editing.
nano ~/.ssh/authorized_keys

In the editor, find the key you just added at the bottom of the file. Navigate to the very beginning of that line and prepend the command restriction.

Before:

ssh-ed25519 AAAA... rsync deploy key for server2

After (replace /path/to/destination/ with your actual path!):

command="rsync --server -vlogDtpre.iL --partial . /path/to/destination/",no-port-forwarding,no-x11-forwarding,no-agent-forwarding,no-pty ssh-ed25519 AAAA... rsync deploy key for server2

Save the file and exit the editor (Ctrl+X, then Y, then Enter).

4. Test the Connection and Launch the Transfer

4.1. Test the Inter-Server Connection

This test now verifies that the new configuration on Server1 is working correctly.

# On your local PC
ssh Server1

# Now, on Server1, this command will work because of the new ~/.ssh/config
ssh Server2

💡 SUCCESS LOOKS LIKE A FAILURE!
The terminal may appear to hang and show a message like `PTY allocation request failed on channel 0`. This is the expected and correct behavior! It proves that the server has successfully rejected your request for an interactive shell due to our security rule. Press `Ctrl+C` to return to the prompt. Your test was successful.

4.2. Launch the Uninterruptible Transfer

# On Server1, install tmux if you haven't already
sudo apt update && sudo apt install tmux

# Start a new tmux session
tmux new -s syncJob

# Inside the tmux session, execute the now-simplified rsync command.
# No -e option is needed because Server1's SSH client is now configured!
rsync -avh --info=progress2 --partial \
  /path/to/source/ \
  Server2:/path/to/destination/

4.3. Detach and Disconnect

The process is now running. Detach from the tmux session and log out.

Ctrl+b, then d

# On Server1
exit

5. Managing the `rsync` Session

You can check on, re-attach, or terminate your transfer at any time.

To check the progress: ssh Server1 and then tmux attach -t syncJob.
To kill the session: ssh Server1 and then tmux kill-session -t syncJob.

6. Quick Troubleshooting

  <colgroup>
    
      <col width="40%">
    
      <col width="60%">
    
  </colgroup>


<thead><tr><th>Problem</th><th>Solution</th></tr></thead><tbody>

“Could not resolve hostname Server2”	The `~/.ssh/config` file on Server1 is missing, has incorrect permissions (should be 600), or the `Host Server2` entry is misspelled.
“Permission denied (publickey).”	The `IdentityFile` path in `Server1`’s `~/.ssh/config` might be wrong. Or, the public key was not correctly added to `Server2`’s `authorized_keys`.
`ssh Server2` test works, but `rsync` fails	Check the `User` in `Server1`’s `~/.ssh/config`. Does that user have permission to write to the destination directory on `Server2`? Also, check the path in the `command=` restriction.
Files are copied into a nested directory	You likely omitted the trailing slash (`/`) on your source path. `/path/to/source` copies the directory itself, while `/path/to/source/` copies its contents.

7. Conclusion

By following this definitive guide, you have built a powerful and professionally architected data transfer system. The key was configuring the client (Server1) to know how to reach the target (Server2), 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.

📚RSYNC DOCUMENTATION 🛡️TMUX WIKI & DOCS

A Smart, mimeapps.list-Aware File Opener for Neomutt

Unknown — Mon, 04 Aug 2025 00:00:00 +0000

Tired of being locked into a single default program for your email attachments in Neomutt? This tutorial will guide you through creating an intelligent file-open-chooser that dynamically reads your system’s mimeapps.list 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.

Changelog

Date	Change
2025-08-04	Initial version of the tutorial published.

1. Prerequisites

Before we begin, ensure your system has the necessary software and configuration in place.

1.1. Required Software

This script relies on a few common command-line utilities.

# Arch Linux Installation
sudo pacman -S neomutt rofi file

# Optional: dmenu as a fallback for rofi
sudo pacman -S dmenu

1.2. Existing Configuration

You should already have:

A working Neomutt setup (e.g., one configured with mutt-wizard).
A populated ~/.config/mimeapps.list file with your preferred application associations.

2. The Core Script: `file-open-chooser`

This script is the heart of our new functionality. It identifies an attachment’s file type, finds all associated programs from your mimeapps.list, and presents them in a selection menu.

ℹ️ BEYOND NEOMUTT
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.

Step 1: Create the Script’s Directory and File

To keep your scripts organized, we will create a dedicated folder and the script file within it.

# Create the subdirectory for our project
mkdir -p ~/Scripts/file-open-chooser

# Create the script file itself
touch ~/Scripts/file-open-chooser/file-open-chooser.sh

Now, open the file ~/Scripts/file-open-chooser/file-open-chooser.sh and paste the entire content below into it.

#!/bin/bash
set -euo pipefail

# Create a temporary file to hold the attachment content piped from Neomutt
tempfile=$(mktemp)
cat > "$tempfile"

# Determine the MIME type of the temporary file
mimetype=$(file --mime-type -b "$tempfile")

# --- Function to extract available programs from mimeapps.list ---
get_programs_for_mime() {
    local mime="$1"
    
    # Read from both [Default Applications] and [Added Associations] sections
    for section in "Default Applications" "Added Associations"; do
        if grep -q "^\[$section\]" ~/.config/mimeapps.list 2>/dev/null; then
            # Use awk to find and print programs for the given MIME type
            apps=$(awk -v section="$section" -v mime="$mime" '
                /^\[.*\]/ { current_section = $0; gsub(/[\[\]]/, "", current_section) }
                current_section == section && $0 ~ "^" mime "=" {
                    sub("^" mime "=", "")
                    gsub(/;/, "\n")
                    print
                }' ~/.config/mimeapps.list)
            
            if [ -n "$apps" ]; then
                echo "$apps"
            fi
        fi
    done
    
    # Always include a "Default" option to use the system's xdg-open
    echo "Default"
}

# --- Function to convert a .desktop file name to a human-readable application name ---
desktop_to_name() {
    local desktop="$1"
    local desktop_file=""
    
    # Search for the .desktop file in standard system locations
    for dir in ~/.local/share/applications /usr/share/applications /usr/local/share/applications; do
        if [ -f "$dir/$desktop" ]; then
            desktop_file="$dir/$desktop"
            break
        fi
    done
    
    if [ -n "$desktop_file" ]; then
        # Extract the 'Name=' field from the .desktop file
        name=$(grep "^Name=" "$desktop_file" | head -1 | cut -d'=' -f2-)
        echo "${name:-$desktop}" # Fallback to the filename if Name is not found
    else
        echo "$desktop"
    fi
}

# --- Main Logic ---

# Collect a unique, sorted list of programs
programs=$(get_programs_for_mime "$mimetype" | sort -u)
display_programs=""

# Build the display list with readable names
while IFS= read -r program; do
    if [ "$program" = "Default" ]; then
        display_programs="$display_programs$program\n"
    else
        readable_name=$(desktop_to_name "$program")
        display_programs="$display_programs$readable_name ($program)\n"
    fi
done <<< "$programs"

# Show the selection menu using rofi, dmenu, or a terminal prompt as fallback
choice="" # Initialize variable
if command -v rofi >/dev/null; then
    choice=$(echo -e "$display_programs" | rofi -dmenu -p "Open $mimetype with:")
elif command -v dmenu >/dev/null; then
    choice=$(echo -e "$display_programs" | dmenu -p "Open $mimetype with:")
else
    echo "Choose program to open $mimetype file:"
    echo -e "$display_programs" | nl
    read -p "Enter choice number: " num
    choice=$(echo -e "$display_programs" | sed -n "${num}p")
fi

# Exit if the user cancelled the selection (e.g., by pressing Esc in rofi)
if [ -z "$choice" ]; then
    rm -f "$tempfile"
    exit 0
fi

# Execute the chosen program
if [ "$choice" = "Default" ]; then
    setsid xdg-open "$tempfile" >/dev/null 2>&1 &
else
    # Extract the .desktop filename from the selection (e.g., from "Okular (org.kde.okular.desktop)")
    desktop_file=$(echo "$choice" | sed 's/.*(\(.*\))/\1/')
    if [ -n "$desktop_file" ] && [ "$desktop_file" != "$choice" ]; then
        # Use gtk-launch for .desktop files, as it's the proper way to launch them
        setsid gtk-launch "$desktop_file" "$tempfile" >/dev/null 2>&1 &
    else
        # Fallback to xdg-open if something went wrong
        setsid xdg-open "$tempfile" >/dev/null 2>&1 &
    fi
fi

# Clean up the temporary file after a delay to give the program time to open it
(sleep 60; rm -f "$tempfile") &

Step 2: Make the Script Executable

Your shell needs permission to run the script file.

chmod +x ~/Scripts/file-open-chooser/file-open-chooser.sh

3. Neomutt Integration

Now, let’s teach Neomutt our new trick. We will bind the o key (for “open”) in the attachment view to execute our script directly.

Add the following line to your Neomutt configuration file (e.g., ~/.config/mutt/muttrc):

# Add a macro to the attachment menu (key 'o') to pipe the
# attachment to our script by calling it with its full path.
macro attach o "<pipe-entry>bash $HOME/Scripts/file-open-chooser/file-open-chooser.sh<enter>" "Choose program to open attachment"

ℹ️ WHY 'BASH $HOME/...'?
By explicitly calling `bash`, we ensure the script is executed with the Bash interpreter. Using `$HOME` instead of `~` is a good practice inside configurations, as it’s more robustly expanded in different contexts.

4. Usage in Neomutt

Your new workflow is simple and efficient:

Navigate to an email with an attachment.
Press v to open the attachment view.
Use the arrow keys to select the desired attachment.
Press o (our new macro).
A Rofi (or dmenu) window will appear, listing all compatible programs.
Select a program, and the file will open.

Example Workflows:

PDF Attachment → o → Choose between Okular, Zathura, Evince…
Image Attachment → o → Choose between Viewnior, GIMP, Inkscape…
Video Attachment → o → Choose between MPV, VLC…

5. Customization

To add a new program to the list for a specific file type, simply edit your ~/.config/mimeapps.list file. The changes are picked up by the script immediately, with no need to restart anything!

Example [Added Associations] section:

[Added Associations]
application/pdf=org.kde.okular.desktop;org.pwmt.zathura.desktop;org.gnome.Evince.desktop;
image/jpeg=viewnior.desktop;gimp.desktop;

Another Useful Keybinding

You can still define a separate shortcut to always use the default system application without seeing the menu.

# Add this to your muttrc. 'O' (Shift+o) will open with the default handler.
macro attach O "<pipe-entry>xdg-open<enter>" "Open with default application"

6. Troubleshooting

If things don’t work as expected, here are some common issues and their solutions.

  <colgroup>
    
      <col width="40%">
    
      <col width="60%">
    
  </colgroup>


<thead><tr><th>Problem</th><th>Solution</th></tr></thead><tbody>

Permission denied error	The script is likely not executable. Run `chmod +x ~/Scripts/file-open-chooser/file-open-chooser.sh` again to be sure.
File not found error	Double-check the path in your Neomutt macro. Make sure it exactly matches the location of your script. Verify with `ls -l ~/Scripts/file-open-chooser/file-open-chooser.sh`.
Rofi/dmenu does not start	Test `rofi` directly by running `rofi -show run`. If it fails, check for error messages. Ensure it’s installed. The script should fall back to a terminal prompt if `rofi` is missing.
Incorrect or no programs listed	Test the MIME type detection with `file --mime-type -b /path/to/some/file.pdf`. Check your `~/.config/mimeapps.list` to ensure the associations for that MIME type are correct.

7. Conclusion

By implementing this file-open-chooser, you’ve significantly enhanced Neomutt’s capabilities. Your setup now:

✅ Leverages your existing mimeapps.list configuration without duplication.
✅ Works universally with any file type.
✅ Provides flexible application choices with a single keypress.
✅ Integrates elegantly with modern tools like Rofi.
✅ Is robust, with fallbacks for different system configurations.
✅ Is easy to set up with a direct, simple configuration.

You now have the same power and flexibility to open files in your email client as you do in your file manager.

📚NEOMUTT DOCS: EXTERNAL PROGRAMS 🚀ROFI ON GITHUB

Guide: NVIDIA Legacy Drivers & Multi-Monitor Setup on a ThinkPad W520 (Arch Linux)

Unknown — Wed, 30 Jul 2025 00:00:00 +0000

This tutorial walks you through the process of setting up a ThinkPad W520 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.

ℹ️ THE GOAL
The primary objective is to enable the NVIDIA Quadro 1000M/2000M GPU in “Discrete Graphics” mode, install the required legacy `nvidia-390xx` driver, and configure the system for a stable multi-monitor experience without the freezes commonly caused by compositors like `picom`.

Changelog

Date	Change
2025-07-29	Initial version of the guide created.

1. Correct BIOS Configuration

First, we need to instruct the system to use only the NVIDIA GPU, bypassing the integrated Intel graphics.

Press F1 during startup to enter the BIOS setup utility.
Navigate to the Config → Display menu.
Set the Graphics Device option to Discrete Graphics. Do not use “Optimus” or “Integrated Graphics.”
If the option exists, disable OS Detection for Optimus.
Save your changes and exit the BIOS. The system will now reboot.

💡 WHY DISCRETE GRAPHICS?
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.

2. Installing the NVIDIA Legacy Driver

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 nvidia-390xx legacy driver from the Arch User Repository (AUR).

2.1. Install an AUR Helper (yay)

If you don’t already have an AUR helper, yay is a popular choice.

sudo pacman -S --needed git base-devel
git clone https://aur.archlinux.org/yay.git
cd yay
makepkg -si

2.2. Install the NVIDIA 390xx Driver from the AUR

Now, use your AUR helper to install the driver and its utilities.

yay -S nvidia-390xx-dkms nvidia-390xx-utils

The -dkms package ensures that the NVIDIA kernel module is automatically rebuilt every time your Linux kernel is updated, which prevents breakage.
During the installation, if prompted, allow the installer to blacklist the open-source nouveau driver, as it conflicts with the proprietary NVIDIA driver.

2.3. Ensure Kernel Headers are Present

DKMS requires kernel headers to build modules. Install them if they are not already on your system.

sudo pacman -S linux-headers

After installation, you can run sudo dkms autoinstall to manually rebuild the module if needed.

2.4. Reboot and Verify

A reboot is necessary to load the new kernel module.

sudo reboot

After rebooting, check if the NVIDIA GPU is active and the driver is loaded correctly by running:

nvidia-smi

If this command displays your GPU details and driver version, the installation was successful.

3. Minimal Xorg Configuration

To ensure the X server starts correctly, we will create a minimal configuration file.

Create the directory if it doesn’t exist:

sudo mkdir -p /etc/X11/xorg.conf.d

Create and edit the configuration file:

sudo nano /etc/X11/xorg.conf.d/20-nvidia.conf

Add the following content to the file:

Section "Device"
    Identifier "NVIDIA Card"
    Driver "nvidia"
    Option "AllowEmptyInitialConfiguration"
EndSection

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.

4. Taming the Compositor (picom)

The nvidia-390xx driver can have stability issues with modern compositors like picom, often causing applications like rofi or terminal emulators to freeze the entire desktop. Here are two solutions.

4.1. The Stable Solution: Configure picom

You can make picom more stable by changing its rendering backend.

Open your picom configuration file:

nano ~/.config/picom/picom.conf

Find and set the following lines:

backend = "xrender";
vsync = false;

The xrender 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.

4.2. The Rock-Solid Alternative: Disable picom

If you don’t need transparency or other compositor effects, the most stable option is to disable picom entirely.

First, stop any running instance:

killall picom

Then, prevent it from starting automatically by commenting out or deleting the relevant line in your i3 config (~/.config/i3/config):

# exec --no-startup-id picom

💡 ACHIEVING TEAR-FREE VIDEO WITHOUT A COMPOSITOR
You can still get a tear-free experience by enabling the “Force Full Composition Pipeline” option in the NVIDIA settings. Run `nvidia-settings` from the terminal. Navigate to X Server Display Configuration → Advanced. Check the box for Force Full Composition Pipeline. Click Apply, and then save the configuration by running `sudo nvidia-settings --write-config`. This will make the setting persistent across reboots.

5. Multi-Monitor Autostart in i3

To have i3 automatically arrange your monitors every time it starts, create a simple shell script.

First, create a directory for your layout scripts:

mkdir -p ~/.screenlayout

Create the script:

nano ~/.screenlayout/monitors.sh

Add your xrandr command to the script. Use the xrandr command with no arguments to find the names of your connected outputs (e.g., eDP-1, DP-1, DP-5, etc.).

#!/bin/bash
xrandr --output eDP-1 --primary --mode 1920x1080 --pos 0x0 --rotate normal \
       --output DP-1 --mode 1920x1080 --right-of eDP-1 --rotate normal

Make the script executable:

chmod +x ~/.screenlayout/monitors.sh

Finally, add this script to your i3 config to execute it on startup:

# In ~/.config/i3/config
exec --no-startup-id ~/.screenlayout/monitors.sh

You’re All Set!

Congratulations! You should now have a fully functional and stable setup.

Your ThinkPad W520 is running on its powerful NVIDIA GPU.
External monitors connected via the dock are recognized and working.
Desktop freezes caused by the compositor have been resolved.
Your i3 session automatically configures your monitor layout on startup.

Efficient File Compression in Ranger File Manager

Unknown — Fri, 18 Jul 2025 00:00:00 +0000

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.

Changelog

Date	Change
2025-07-18	Initial Version: Created guide for compression workflow in ranger

1. Prerequisites

Before we begin, make sure you have the following tools installed:

ranger: The terminal file manager
atool: A script for managing file archives of various types
Archive utilities: While atool is a wrapper, you’ll need the actual compression tools installed:
- zip, unzip: For .zip archives
- tar: For .tar, .tar.gz, .tar.bz2 archives
- p7zip-full (Debian/Ubuntu) or p7zip (Arch/Fedora): For .7z archives
- rar, unrar: For .rar archives

Installation on Various Distributions

# For Debian/Ubuntu
sudo apt update && sudo apt install ranger atool

# For Arch Linux
sudo pacman -S ranger atool

# For Fedora
sudo dnf install ranger atool

The atool package provides commands like apack (for creating archives) and aunpack (for extracting archives), which we’ll use in our custom ranger commands.

2. Creating the Custom compress Command

The integration requires adding a custom command to ranger that will use apack to compress selected files into an archive.

2.1. Create or Edit commands.py

First, navigate to your ranger configuration directory and create or edit the commands.py file:

mkdir -p ~/.config/ranger
touch ~/.config/ranger/commands.py

If you don’t have a commands.py file yet, you can generate a template with:

ranger --copy-config=commands

2.2. Add the compress Command

Open the commands.py file in your favorite text editor and add the following code:

import os
from ranger.core.loader import CommandLoader

class compress(Command):
    def execute(self):
        """ Compress marked files to current directory """
        cwd = self.fm.thisdir
        marked_files = cwd.get_selection()

        if not marked_files:
            return

        def refresh(_):
            cwd = self.fm.get_directory(original_path)
            cwd.load_content()

        original_path = cwd.path
        parts = self.line.split()
        au_flags = parts[1:]

        descr = "Compressing to: " + os.path.basename(parts[1])
        obj = CommandLoader(args=['apack'] + au_flags + \
                [os.path.relpath(f.path, cwd.path) for f in marked_files], descr=descr, read=True)

        obj.signal_bind('after', refresh)
        self.fm.loader.add(obj)

    def tab(self, tabnum):
        """ Complete with current folder name """

        extension = ['.zip', '.tar.gz', '.rar', '.7z']
        return ['compress ' + os.path.basename(self.fm.thisdir.path) + ext for ext in extension]

This command will:

Take the marked files in ranger
Use apack to compress them into an archive
Refresh the directory view after compression
Provide tab completion for common archive formats

3. Adding an Extract Command (Optional)

For a complete compression workflow, you might also want to add an extraction command. Add this to your commands.py file:

class extract_here(Command):
    def execute(self):
        """ Extract selected files to current directory """
        cwd = self.fm.thisdir
        marked_files = cwd.get_selection()

        if not marked_files:
            return

        def refresh(_):
            cwd = self.fm.get_directory(original_path)
            cwd.load_content()

        original_path = cwd.path
        au_flags = ['-X', cwd.path]  # Extract to current directory
        au_flags += self.line.split()[1:]
        au_flags += ['-e']

        self.fm.copy_buffer.clear()
        self.fm.cut_buffer = False

        if len(marked_files) == 1:
            descr = "extracting: " + os.path.basename(marked_files[0].path)
        else:
            descr = "extracting {} files".format(len(marked_files))

        obj = CommandLoader(args=['aunpack'] + au_flags + \
                [f.path for f in marked_files], descr=descr, read=True)

        obj.signal_bind('after', refresh)
        self.fm.loader.add(obj)

4. Creating Keyboard Shortcuts

Now that we have our custom commands, let’s create keyboard shortcuts to invoke them easily.

4.1. Edit rc.conf

Open your ranger configuration file:

vim ~/.config/ranger/rc.conf

If you don’t have this file yet, you can generate it with:

ranger --copy-config=rc

4.2. Add the Keyboard Mappings

Add the following lines to map the commands to keyboard shortcuts:

# Compression and extraction
map cc console compress%space
map cx extract_here

With these shortcuts:

cc will start the compress command and wait for you to specify the archive name
cx will extract the selected archive in the current directory

Shortcut	Description
`cc`	Compress selected files into an archive
`cx`	Extract selected archive in the current directory

5. Advanced Configuration

5.1. Customize Archive Formats

You can modify the list of supported archive extensions in the tab method of the compress command:

def tab(self, tabnum):
    """ Complete with current folder name """
    extension = ['.zip', '.tar.gz', '.tar.bz2', '.tar.xz', '.rar', '.7z']
    return ['compress ' + os.path.basename(self.fm.thisdir.path) + ext for ext in extension]

Add or remove archive formats based on your needs and installed utilities.

5.2. Add Compression Options

You can enhance the compress command to support additional options like compression level:

def tab(self, tabnum):
    """ Complete with current folder name and compression options """
    extension = ['.zip', '.tar.gz', '.rar', '.7z']
    base_name = os.path.basename(self.fm.thisdir.path)
    
    # Basic archive names
    options = ['compress ' + base_name + ext for ext in extension]
    
    # Add options with compression levels for zip
    if tabnum == 1:
        options += ['compress ' + base_name + '.zip -mx=9']  # Maximum compression
        options += ['compress ' + base_name + '.zip -mx=1']  # Fastest compression
    
    return options

5.3. Exclude Certain Files

You might want to exclude certain files from compression (like temporary files or already compressed files). You can modify the execute method to filter the marked files:

marked_files = [f for f in cwd.get_selection() if not f.path.endswith(('.zip', '.rar', '.7z'))]

6. Usage

Once everything is set up, you can use your new compression workflow:

6.1. Creating Archives

Open ranger in your terminal
Navigate to the directory containing files you want to compress
Select files using the space key (or select a single file with the cursor)
Press cc to start the compress command
Type the archive name or press Tab to auto-complete with suggested formats
Press Enter to create the archive

6.2. Extracting Archives

Navigate to an archive file or select it
Press cx to extract its contents to the current directory

7. Practical Examples

7.1. Backup Workflow

Create quick backups of important directories:

Navigate to a project folder
Press cc then Tab to get suggestions
Select .tar.gz format for good compression
Add a date to the filename: project-backup-2025-07-18.tar.gz

Compress files for sharing:

Select multiple files with space
Press cc and create a .zip file (most compatible format)
The archive is ready to be emailed or transferred

7.3. Working with Different Archive Types

The workflow supports various archive formats:

.zip - Good compatibility across platforms
.tar.gz - Better compression, common on Linux
.7z - Best compression ratio
.rar - Good for split archives

8. Troubleshooting

8.1. Command Not Found

If you get a “Command not found” error when trying to use the shortcut:

Make sure you’ve saved the commands.py file correctly
Restart ranger to load the new command
Check that atool is installed and in your PATH

8.2. Compression Fails

If compression fails:

Check if you have the appropriate compression tools installed
Verify that you have write permissions in the current directory
Make sure you have enough disk space

Try running apack directly to see if it works outside of ranger:

apack archive.zip file1 file2 file3

8.3. File Not Found Errors

If you get “file not found” errors:

Make sure you’re not trying to compress files with special characters in their names
Check if the paths are correct
Try using relative paths instead of absolute paths

Summary

With this compression workflow integration, you’ve enhanced ranger’s capabilities for working with archives:

✅ 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

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.

📚ATOOL DOCUMENTATION 🔧RANGER CUSTOM COMMANDS 📦ARCH WIKI: RANGER ARCHIVES

Enhance your ranger experience with these additional tutorials:

Ranger and fzf Integration - Add powerful fuzzy search capabilities
Image Metadata Viewing with exiftool - View detailed metadata for images and media files
Advanced Media Preview Configuration - Customize file previews for various formats
Ranger and sxiv Integration - Create a seamless image viewing workflow

Enhancing Ranger with fzf and bat: A Powerful File Search Integration

Unknown — Fri, 18 Jul 2025 00:00:00 +0000

The ranger file manager is already a powerful tool for navigating your filesystem, but with the addition of fzf (fuzzy finder) and bat (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.

Changelog

Date	Change
2025-07-18	Initial Version: Created guide for integrating fzf and bat with ranger

1. Prerequisites

Before we begin, ensure you have the following tools installed on your system:

ranger: The terminal file manager
fzf: Command-line fuzzy finder
bat: A cat clone with syntax highlighting

Installation on Various Distributions

# For Debian/Ubuntu
sudo apt update && sudo apt install ranger fzf bat

# For Arch Linux
sudo pacman -S ranger fzf bat

# For Fedora
sudo dnf install ranger fzf bat

Note: On some distributions, bat might be packaged as batcat. You can create an alias in your shell configuration file:

alias bat='batcat'

2. Creating the Custom fzf_select Command

The integration requires adding a custom command to ranger. This command will use fzf for searching and bat for file previews.

2.1. Create or Edit commands.py

First, navigate to your ranger configuration directory and create or edit the commands.py file:

mkdir -p ~/.config/ranger
touch ~/.config/ranger/commands.py

If you don’t have a commands.py file yet, you can generate a template with:

ranger --copy-config=commands

2.2. Add the fzf_select Command

Open the commands.py file in your favorite text editor and add the following code:

from ranger.api.commands import Command
import os
import subprocess

class fzf_select(Command):
    """
    :fzf_select

    Find a file or directory using fzf with preview using bat, excluding certain directories unless currently in them.
    """
    def execute(self):
        exclude_dirs = ['Remote', 'USBmount', 'NFSshares', 'Games_ROMS']  # List of directories to exclude
        current_dir = os.getcwd()
        base_name = os.path.basename(current_dir)

        # Check if the current directory is in the list of directories to exclude
        if base_name in exclude_dirs:
            find_command = "find . -type f -o -type d"
        else:
            # Construct the find command with exclusion criteria
            exclude_opts = ' '.join(f"-path './{d}' -prune -o" for d in exclude_dirs)
            find_command = f"find . \\( {exclude_opts} -false \\) -o \\( -type f -o -type d \\) -print"

        command = f"{find_command} | fzf --preview '[[ -f {{}} ]] && bat --style=numbers --color=always {{}} || echo {{}} is a directory' --preview-window=right:70%:wrap --exact"

        fzf = subprocess.Popen(command, stdout=subprocess.PIPE, shell=True, text=True, cwd=current_dir)
        selected, _ = fzf.communicate()

        if fzf.returncode == 0:
            selected = selected.strip()
            selected_path = os.path.abspath(selected)
            if os.path.isdir(selected_path):
                # Change to the directory if it's a directory
                self.fm.cd(selected_path)
            else:
                # Open the file if it's a file
                self.fm.select_file(selected_path)

            # Explicitly refresh the ranger window
            self.fm.ui.redraw_window()

This command will:

Exclude specific directories from the search (unless you’re already in one of them)
Use bat for file previews and show a simple message for directories
Execute fzf with the appropriate options
Navigate to the selected file or directory
Explicitly refresh the ranger window after selection

3. Creating a Keyboard Shortcut

Now that we have our custom command, let’s create a keyboard shortcut to invoke it easily.

3.1. Edit rc.conf

Open your ranger configuration file:

vim ~/.config/ranger/rc.conf

If you don’t have this file yet, you can generate it with:

ranger --copy-config=rc

3.2. Add the Keyboard Mapping

Add the following line to map the fzf_select command to a keyboard shortcut. In this example, we’ll use zi (which stands for “zoom in”):

map zi fzf_select

This shortcut is easy to remember as zi 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.

Shortcut	Description
`zi`	Start fuzzy search with fzf and bat preview (“zoom in” to your files)

4. Advanced Configuration

4.1. Customize Directory Exclusions

You can modify the list of directories to exclude from the search by changing the exclude_dirs list in the fzf_select command:

exclude_dirs = ['Remote', 'USBmount', 'NFSshares', 'Games_ROMS', 'VirtualMachines']  # Add or remove directories as needed

4.2. Show Hidden Files

If you want to include hidden files in your search, modify the find_command variable:

find_command = "find . -type f -o -type d -name '.*' -o -type f -o -type d"

4.3. Customize Preview Options

You can customize how bat displays file previews by modifying the preview part of the command:

command = f"{find_command} | fzf --preview '[[ -f {{}} ]] && bat --style=full --color=always --line-range :150 {{}} || echo {{}} is a directory' --preview-window=right:60%:wrap --exact"

This example:

Uses the “full” style for bat (includes line numbers, Git modifications, etc.)
Shows up to 150 lines in the preview
Sets the preview window width to 60% of the terminal

5. Usage

Once everything is set up, you can use your new fuzzy search capability:

Open ranger in your terminal
Press your configured shortcut (e.g., zi)
Type to search for files
Use arrow keys to navigate through results
Press Enter to select a file or directory

6. Troubleshooting

6.1. Command Not Found

If you get a “Command not found” error when trying to use the shortcut:

Make sure you’ve saved the commands.py file correctly
Restart ranger to load the new command
Check that fzf and bat are installed and in your PATH

6.2. Preview Not Working

If file previews aren’t displaying:

Verify that bat is installed correctly
Try using batcat instead of bat if you’re on Debian/Ubuntu
Check if your terminal supports the preview feature

Summary

With this integration, you’ve significantly enhanced ranger’s search capabilities:

✅ Lightning-fast file searching with fuzzy matching ✅ Beautiful syntax-highlighted previews ✅ Seamless navigation to selected files ✅ Customizable interface and behavior

This setup combines the best of three powerful tools: ranger’s file management, fzf’s search capabilities, and bat’s beautiful syntax highlighting.

📚RANGER CUSTOM COMMANDS 🔍FZF DOCUMENTATION 🦇BAT DOCUMENTATION

Advanced Media Preview Configuration in Ranger

Unknown — Fri, 18 Jul 2025 00:00:00 +0000

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.

Changelog

Date	Change
2025-07-18	Initial Version: Created guide for customizing media previews in ranger

1. Understanding Ranger’s Preview System

Ranger uses a script called scope.sh 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.

1.1. The Preview Process

When you select a file in ranger:

Ranger calls the scope.sh script
The script identifies the file type
It selects an appropriate preview method
The preview is displayed in the preview pane

1.2. Default Configuration

By default, ranger comes with a sample scope.sh file, but it’s not automatically installed. You need to copy it to your configuration directory and customize it for your needs.

2. Setting Up the Preview Script

2.1. Copy the Default scope.sh

First, create your ranger configuration directory if it doesn’t exist:

mkdir -p ~/.config/ranger

Then, copy the default scope.sh script:

ranger --copy-config=scope

This will create ~/.config/ranger/scope.sh with the default configuration.

2.2. Make the Script Executable

Ensure the script is executable:

chmod +x ~/.config/ranger/scope.sh

3. Installing Preview Dependencies

To get the most out of ranger’s preview capabilities, you’ll need to install various tools for different file types:

# For Debian/Ubuntu
sudo apt update && sudo apt install highlight atool lynx mediainfo poppler-utils \
    ffmpegthumbnailer imagemagick transmission-cli odt2txt \
    python3-pygments catdoc docx2txt fontforge

# For Arch Linux
sudo pacman -S highlight atool lynx mediainfo poppler ffmpegthumbnailer \
    imagemagick transmission-cli python-pygments catdoc fontforge

# For Fedora
sudo dnf install highlight atool lynx mediainfo poppler-utils ffmpegthumbnailer \
    ImageMagick transmission python3-pygments catdoc fontforge

# Optional: Install xlsx2csv for spreadsheet previews
pip install xlsx2csv

4. Customizing the Preview Script

Now let’s customize the scope.sh script to enhance the preview capabilities. Open the file in your favorite text editor:

vim ~/.config/ranger/scope.sh

4.1. Image Preview Configuration

Find the section that handles images and customize it:

case "${mimetype}" in
    # Image previews
    image/*)
        # Use preview size of 1920px for large images
        local geometry="1920x1080"
        if [[ "${mimetype}" == "image/svg+xml" ]]; then
            convert -- "${FILE_PATH}" "${IMAGE_CACHE_PATH}" && exit 6
        else
            exiftool -b -PreviewImage -w "${IMAGE_CACHE_PATH}" "${FILE_PATH}" && exit 6
            # If exiftool failed, try standard conversion
            convert -- "${FILE_PATH}[0]" -resize "${geometry}" "${IMAGE_CACHE_PATH}" && exit 6
        fi
        ;;

4.2. Video Preview with FFmpegthumbnailer

Enhance the video preview section:

video/*)
    # Video preview using ffmpegthumbnailer
    ffmpegthumbnailer -i "${FILE_PATH}" -o "${IMAGE_CACHE_PATH}" -s 0 -q 10 && exit 6
    exit 1
    ;;

4.3. PDF Preview Configuration

Improve PDF preview with higher resolution:

application/pdf)
    # Higher quality PDF preview (first page)
    pdftoppm -f 1 -l 1 -scale-to 1024 -singlefile -jpeg "${FILE_PATH}" "${IMAGE_CACHE_PATH%.*}" && exit 6
    exit 1
    ;;

4.4. Office Documents Preview

Add better support for office documents:

# Office documents
application/vnd.openxmlformats-officedocument.wordprocessingml.document|application/vnd.oasis.opendocument.text)
    # Convert to plain text
    docx2txt "${FILE_PATH}" - && exit 5
    odt2txt "${FILE_PATH}" && exit 5
    exit 1
    ;;
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet|application/vnd.oasis.opendocument.spreadsheet)
    # Convert to CSV
    xlsx2csv "${FILE_PATH}" && exit 5
    exit 1
    ;;

4.5. Archive Content Preview

Enhance archive preview:

# Archives
application/zip|application/x-rar|application/x-7z-compressed|application/x-tar|application/x-bzip2|application/x-gzip|application/x-xz)
    # List archive contents
    atool --list -- "${FILE_PATH}" && exit 5
    bsdtar --list --file "${FILE_PATH}" && exit 5
    exit 1
    ;;

4.6. Syntax Highlighting for Code

Improve code syntax highlighting:

# Syntax highlighting for code
text/*)
    # Try to use pygmentize for syntax highlighting
    env COLORTERM=8bit bat --color=always --style=plain "${FILE_PATH}" && exit 5
    pygmentize -f terminal -O style=monokai -g "${FILE_PATH}" && exit 5
    # Fallback to cat if pygmentize is not available
    cat "${FILE_PATH}" && exit 5
    exit 1
    ;;

5. Advanced Customizations

5.1. Custom Preview Size

You can adjust the preview size by modifying your rc.conf:

# Add to ~/.config/ranger/rc.conf
set preview_images true
set preview_images_method kitty  # or use: w3m, iterm2, terminology, urxvt, sixel
set preview_max_size 10485760    # Don't preview files larger than 10MB

5.2. Font Preview

Add font preview capability:

# Add to scope.sh under the case statement
# Note: This requires FontForge to be installed for the fontimage command
font/*|application/font*|application/x-font*)
    preview_png="/tmp/$(basename "${IMAGE_CACHE_PATH%.*}").png"
    if fontimage -o "${preview_png}" \
                 --pixelsize "120" \
                 --fontname \
                 --pixelsize "80" \
                 --text "  ABCDEFGHIJKLMNOPQRSTUVWXYZ  " \
                 --text "  abcdefghijklmnopqrstuvwxyz  " \
                 --text "  0123456789.:,;(*!?')  " \
                 --text "  The quick brown fox jumps over the lazy dog.  " \
                 "${FILE_PATH}";
    then
        convert -- "${preview_png}" "${IMAGE_CACHE_PATH}" \
            && rm "${preview_png}" \
            && exit 6
    else
        exit 1
    fi
    ;;

5.3. Audio File Preview

Add audio file metadata preview:

# Add to scope.sh under the case statement
audio/*)
    # Show audio metadata
    mediainfo "${FILE_PATH}" && exit 5
    exiftool "${FILE_PATH}" && exit 5
    exit 1
    ;;

6. Configuring Image Preview Methods

Ranger supports several methods for displaying image previews in the terminal. You’ll need to configure both scope.sh and rc.conf to use them properly.

6.1. Available Preview Methods

Add this to your rc.conf:

# Choose one of these methods:
set preview_images true
set preview_images_method kitty  # Options: kitty, ueberzug, w3m, iterm2, terminology, urxvt, sixel

Different methods work with different terminals:

kitty: For the kitty terminal
ueberzug: Works with most terminals (requires python-ueberzug)
w3m: Works with most terminals that support w3m
iterm2: For iTerm2 on macOS
terminology: For the Terminology terminal
urxvt: For urxvt with pixbuf support
sixel: For terminals with sixel support

6.2. Installing UeberzugPP (Recommended)

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:

# For Arch Linux (via AUR)
yay -S ueberzugpp

# For other distributions (compile from source)
git clone https://github.com/jstkdng/ueberzugpp.git
cd ueberzugpp
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make
sudo make install

# Alternative: Install via pip (if available)
pip install ueberzugpp

Then set in rc.conf:

set preview_images true
set preview_images_method ueberzug

Note: Even though we’re using UeberzugPP, the method name in ranger’s configuration remains ueberzug for compatibility.

7. Testing Your Configuration

After making changes to scope.sh, restart ranger and test the preview functionality:

Navigate to different file types
Check if the previews are displayed correctly
Adjust the configuration as needed

7.1. Debugging Preview Issues

If previews aren’t working as expected:

Run ranger with the --debug flag:
```
ranger --debug
```
Check the output for errors related to the preview script
Make sure all required dependencies are installed
Verify that scope.sh is executable

8. Practical Examples

8.1. Image Gallery Browsing

With proper image preview configuration, you can use ranger as an image browser:

Navigate to a directory with images
Use arrow keys to browse through images
See high-quality previews directly in the terminal

8.2. Code Review

With syntax highlighting enabled:

Navigate to source code files
See syntax-highlighted code in the preview pane
Quickly scan through multiple files

8.3. Document Management

With document preview support:

Browse through PDF documents
See previews of the first page
View plain text content of office documents

9. Troubleshooting

9.1. Missing Dependencies

If certain file types don’t preview correctly, you might be missing dependencies:

# Check if a command is available
which ffmpegthumbnailer
which convert
which pdftoppm

Install any missing tools using your package manager.

9.2. Terminal Compatibility

Not all terminals support all preview methods:

If images don’t display, try a different preview_images_method in rc.conf
For kitty terminal, make sure you’re using the kitty method
For other terminals, try ueberzug or w3m

9.3. Large Files

If ranger becomes slow when previewing large files:

# Add to rc.conf
set preview_max_size 5242880  # Don't preview files larger than 5MB

Summary

With these customizations to ranger’s preview system, you’ve enhanced your terminal file manager with rich media preview capabilities:

✅ High-quality image previews ✅ Video thumbnails ✅ PDF document previews ✅ Office document text extraction ✅ Syntax highlighting for code ✅ Archive content listing ✅ Font previews

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.

🖼️RANGER IMAGE PREVIEWS 🔧RANGER CUSTOM COMMANDS 📚UEBERZUG DOCUMENTATION

The Ultimate Guide to Email Encryption with OpenPGP

Unknown — Tue, 15 Jul 2025 00:00:00 +0000

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.

Changelog

Date	Change
2025-07-15	Major Restructure (Terminal-First): The entire guide was rewritten to prioritize key creation in the terminal (`gpg`), making it more robust, universal, and secure. This resolves platform-specific client issues.
2025-07-15	Initial Version: Article created.

1. Pre-Flight Check – Your System’s Foundation

Before we create any keys, we must ensure your system is correctly configured.

1.1. Install GnuPG

This is the core encryption engine.

Debian/Ubuntu: sudo apt update && sudo apt install gnupg
Arch Linux: sudo pacman -Syu gnupg

1.2. Install and Configure `pinentry`

When a program needs your key’s passphrase, GPG uses a helper application called pinentry to display a secure prompt. You must choose the right one for your environment.

Step 1: Choose and Install the Right pinentry for Your Environment

For standard Desktop Environments (GNOME, KDE, XFCE, etc.): A graphical pop-up is the default. Install the appropriate package:
- GNOME: sudo apt install pinentry-gnome3
- KDE Plasma: sudo apt install pinentry-qt
- Arch Linux (most desktops): sudo pacman -S pinentry
For Tiling Window Managers (i3wm, sway, etc.) or Terminal-Enthusiasts (Recommended): A graphical pinentry can “grab” focus and freeze your desktop. The terminal-based pinentry-curses is a much better solution as it runs directly in your terminal, allowing you to switch windows normally.
- Debian/Ubuntu: sudo apt install pinentry-curses
- Arch Linux: pinentry is already included in the pinentry package.

Step 2: Tell the GPG Agent Which Program to Use We will now edit the GPG Agent configuration file.

Open the file with a terminal editor:
```
nano ~/.gnupg/gpg-agent.conf
```

Inside the nano editor, add ONE of the following lines, depending on your choice in Step 1. Ensure the other line is deleted or commented out with a #.

# For a terminal-based prompt (i3wm, sway - HIGHLY RECOMMENDED for this setup)
pinentry-program /usr/bin/pinentry-curses

# For a graphical prompt (GNOME, KDE, etc.)
# pinentry-program /usr/bin/pinentry-gnome3
    
default-cache-ttl 600
max-cache-ttl 7200

Note: Verify the correct path with which pinentry-gnome3 or which pinentry-curses if needed.

Save the file and exit nano (Ctrl+X, then Y, then Enter).
Reload the agent to apply the new configuration:
```
gpg-connect-agent reloadagent /bye
```

2. Creating Your Master Key in the Terminal

We will now create your OpenPGP key using the recommended interactive process.

Start the key generation process:
```
gpg --full-generate-key
```
Follow the prompts. The recommended choices are secure and robust:
- Key Type: Select (1) RSA and RSA.
- Key Size: Enter 4096 bits.
- Expiration Date: Enter 2y (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.
- Confirm that the expiration date is correct by typing y.
Provide Your User ID:
- Real name: Enter your full name.
- Email address: Enter the email address for this key.
- Comment: You can leave this blank.
- Confirm your details by typing O (for Okay).
Set Your Passphrase: A secure prompt will now appear (thanks to pinentry!). This will be the master password for your new private key.

⚠️ PASSPHRASE QUALITY IS CRITICAL

A weak passphrase makes your encrypted data vulnerable. Consider using a method like **Diceware** to generate a sequence of random words. If you lose this passphrase, you lose access to all data encrypted with this key permanently.

Congratulations, you have successfully created a secure, command-line-native OpenPGP key!

3. Essential Security Practices (Don’t Skip This!)

Immediately after creation, you must secure your new key for long-term use.

3.1. Identifying Your Key: The Key-ID

From this point forward, we will use your key’s unique Key-ID to refer to it. This avoids any confusion if you ever have multiple keys for the same email address.

Find Your Key-ID: Run the following command.

gpg --list-secret-keys --keyid-format LONG

Identify the ID: In the output sec rsa4096/YOUR-KEY-ID ..., the YOUR-KEY-ID is the long string of characters you will use in all subsequent commands.

3.2. Backup Your Private Key

A backup is not a backup until it’s tested. Use your newly found Key-ID here.

Create the Backup:

umask 077 && gpg --export-secret-keys --armor YOUR-KEY-ID > private-key-backup.asc

Verify the Backup:
```
gpg --dry-run --import private-key-backup.asc
```
If this command runs without errors, your backup is valid. Now, store the .asc file in one or more extremely secure, offline locations.

3.3. Create a Revocation Certificate

This is your emergency button. Use your Key-ID to specify which key to revoke.

umask 077 && gpg --gen-revoke --armor YOUR-KEY-ID > revocation-cert.asc

Store this file as securely as your private key backup.

3.4. Verify Keys and Build Your Web of Trust: The Core of PGP’s Security

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.

What is the Fingerprint?

When you run the command gpg --fingerprint YOUR-KEY-ID, you get an output like this:

$ gpg --fingerprint 8A738464A2144E4C
pub   rsa4096 2025-07-29 [SC] [expires: 2027-07-29]
      4A9E 9A72 85F5 F569 C17C  299B 8A73 8464 A214 4E4C
uid        [ultimate] Delightful Dude <delightfuldude@criticalbasics.xyz>
sub   rsa4096 2025-07-29 [E] [expires: 2027-07-29]

The Fingerprint 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.”

The Verification Process: A Practical Example

Imagine you want to communicate securely with your friend, Anna.

Step 1: You acquire Anna’s public key. Anna has published her key on her website (Method 4.1) or a keyserver (Method 4.2). You import it.

# Example: You import Anna's key from her website
curl -sL https://anna.example.com/public.asc | gpg --import

Step 2: You check the key’s status. Now, you view the fingerprint of Anna’s key in your keyring.

gpg --fingerprint anna@example.com

The output will contain a line that looks like this: uid [ unknown ] Anna Miller <anna@example.com>

The [ unknown ] 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.”

Step 3: The actual verification (the human part). To be sure, you must compare the fingerprint with Anna over a different, trusted channel. This is the most important step to prevent man-in-the-middle attacks.

You meet Anna in person.
You call Anna or have a video call (with someone whose voice or face you recognize).

During the conversation, the following happens:

You say: “Anna, I’m going to read you the fingerprint I have for your key. Does it start with 1234 ABCD…?”
Anna says: “Yes, that’s correct. And does yours start with 0FDA EF41…?”
You say: “Yes, it does.”

Now you both have certainty that you possess each other’s authentic key.

Step 4: Sign the key (digitally record your trust). 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.

gpg --sign-key anna@example.com

GPG will show you Anna’s fingerprint again and ask if you are really sure. Confirm with y. You will need to enter your passphrase to authorize the signature with your private key.

Step 5: Check the result. Run the fingerprint command again:

gpg --fingerprint anna@example.com

The output has now changed: uid [ full ] Anna Miller <anna@example.com>

The [ full ] is your personal note: “I have personally verified this key. It’s authentic. I trust it completely.”

Through this process, you build your personal “Web of Trust”. 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.

3.5. Extending Your Key’s Validity (Key Renewal)

An expiring key is a feature, not a problem. You do NOT need to start over. You can easily extend its life before it expires.

Start the Key-Editing Process:
```
gpg --edit-key YOUR-KEY-ID
```
Extend the Expiration Date: Inside the GPG prompt, type expire, enter a new duration (e.g., 2y), and confirm.
Save Your Changes:
```
gpg> save
```
Distribute Your Updated Key: You must re-publish your updated public key.
```
gpg --keyserver hkps://keys.openpgp.org --send-keys YOUR-KEY-ID
```
Also, send a newly signed email with your updated public key attached to your most important contacts.

4. Making Your Key Discoverable (Optional)

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.

4.1. Method 1: The Gold Standard - Your Personal Website

This is the most secure and authoritative method. You establish a “source of truth” that you control, avoiding issues with public servers.

Export your public key:

gpg --export --armor YOUR-KEY-ID > public.asc

Upload the public.asc file to your website, for example, to https://your-website.com/public.asc.

4.2. Method 2: The Convenient Way - Public Keyservers

This method is more convenient but involves a trade-off with privacy.

Security Risk: NO. You only upload your public key.
Privacy Risk: YES. This publicly associates your email with PGP usage.

The Solution: Use a Modern, Privacy-Respecting Keyserver. This is why we exclusively recommend keys.openpgp.org. It requires your consent via email verification to publish your key.

Send Your Key to the Server:

gpg --keyserver hkps://keys.openpgp.org --send-keys YOUR-KEY-ID

Check Your Email: The keyserver will send you a verification email. You must click the link to finalize the publication.

5. Going Public: Your Contact Page and Email Signature

Now that you have ways to distribute your key, you need to tell people about them.

5.1. On Your Website’s Contact Page

Add a section like this to your contact page. It provides clear instructions for everyone.

<h3>Digital Contact & Verification</h3>
<p><strong>E-Mail:</strong> your.name@example.com</p>
<p>
    <strong>OpenPGP Key:</strong> For encrypted communication, you can get my public key here:
    <ul>
        <li><a href="/public.asc" download>Download Public Key</a></li>
        <li><strong>Or import via command line:</strong><br>
            <code>curl -sL https://your-website.com/public.asc | gpg --import</code>
        </li>
    </ul>
    <strong>Fingerprint for Verification:</strong><br>
    <code>YOUR FINGERPRINT IN 4-DIGIT BLOCKS</code>
</p>
<p><em>Policy: All legitimate emails from me will be digitally signed with this key.</em></p>

5.2. In Your Email Signature

A compact, professional signature in every email reinforces trust and makes verification easy.

-- 
Your Name

Website & PGP Key: https://your-website.com/contact
GPG Fingerprint: YOUR FINGERPRINT IN 4-DIGIT BLOCKS

This signature doesn’t overload the email but provides everything a recipient needs to verify your identity and find your key.

6. Integration with Thunderbird

Once your key is created via the terminal, you need to tell Thunderbird to use it for your email account.

In Thunderbird, open the Account Settings (via the “Hamburger” menu or Tools -> Account Settings).
In the left-hand sidebar, select the email account you want to secure (e.g., delightfuldude@criticalbasics.xyz).
Click on the End-To-End Encryption sub-menu for that account.

Now, you have two possible scenarios:

Scenario A: Thunderbird Automatically Finds Your Key

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!

Scenario B: The Key is Not Listed (Manual Import)

More often, Thunderbird doesn’t immediately find externally created keys. If your key is not in the list, you must import it manually.

In the same settings window, click the OpenPGP Key Manager… button.
A new “OpenPGP Key Manager” window will open. In its menu, go to File -> Import Secret Key(s) From File….
A file dialog will open. Navigate to and select the private.asc file you exported in Part 4.
You will be prompted for the passphrase you created for your key. Enter it to complete the import.
After a successful import, your new key will appear in the Key Manager list. You can now close this window.
Back in the Account Settings, your newly imported key should now be available in the dropdown menu. Select it to finalize the setup.

ℹ️ FURTHER HELP
For more detailed questions or troubleshooting, Mozilla provides an extensive FAQ page that is highly recommended: Official Thunderbird Help: OpenPGP HOWTO and FAQ

7. Integration with Neomutt

7.1. Neomutt Configuration

Add these settings to ~/.config/neomutt/muttrc, using your unique Key-ID.

# --- GPG/PGP Settings for Neomutt ---
set pgp_verify_sig = yes
set pgp_good_sign = "✅ Good OpenPGP signature from"
set pgp_autosign = yes
set pgp_replyencrypt = yes
set pgp_replysign = yes
# Für neuere Neomutt-Versionen:
set pgp_replysign_encrypted = yes
# Für ältere Neomutt-Versionen (falls obige Option einen Fehler verursacht):
# set crypt_replysign = yes
# Use the Key-ID followed by an exclamation mark!
# This tells GPG to use *exactly* this key.
set pgp_sign_as = "YOUR-KEY-ID!"
set pgp_timeout = 300
set pgp_show_unusable = no

8. Advanced Topic: Handling Multiple Accounts

For maximum security, use separate OpenPGP keys for each email account. This provides strong separation between your digital identities. This section covers the setup for Thunderbird and two common approaches for Neomutt.

Create Keys: For each identity (e.g., private, work), repeat the process in Part 2 to generate a new, dedicated key. Make sure to use the correct name and email address for each.

8.1. Thunderbird Integration

For each account you have set up in Thunderbird, follow Part 6 to assign the correct existing key to the corresponding email address. Thunderbird handles the mapping automatically.

8.2. Neomutt Integration: Two Approaches

For Neomutt, you can either switch accounts automatically based on the folder you are in, or manually via keyboard shortcuts.

Method A: Automatic Switching with Folder-Hooks

This method uses folder-hook to automatically load the correct account configuration (including the PGP key) when you enter a specific mailbox.

Step 1: Create the Directory Structure First, organize your account configurations in a dedicated directory.

mkdir -p ~/.config/neomutt/accounts

Step 2: Configure the Main muttrc for Hooks Your main ~/.config/neomutt/muttrc will now act as a loader. Add the PGP defaults (if not already present) and the hooks.

# --- PGP Defaults (add to your main muttrc) ---
set pgp_timeout = 300
set pgp_verify_sig = yes
set pgp_good_sign = "✅ Good OpenPGP signature from"
set pgp_show_unusable = no
# Für neuere Neomutt-Versionen:
set pgp_replysign_encrypted = yes
# Für ältere Neomutt-Versionen (falls obige Option einen Fehler verursacht):
# set crypt_replysign = yes

# --- Account Hooks ---
# Load a specific config file when you enter a folder.
# Replace the imap paths with your actual server paths.
folder-hook 'imaps://private@mail.com/' 'source ~/.config/neomutt/accounts/private.muttrc'
folder-hook 'imaps://work@company.com/'   'source ~/.config/neomutt/accounts/work.muttrc'

# Load a default account when Neomutt starts
source ~/.config/neomutt/accounts/private.muttrc

Step 3: Create Per-Account Configuration Files Create a separate file for each account inside ~/.config/neomutt/accounts/. This is where you set the PGP key for each identity.

Example: ~/.config/neomutt/accounts/private.muttrc

# --- Account: Private ---
set from = "private@mail.com"
set realname = "Your Name (Private)"
set pgp_sign_as = "YOUR-PRIVATE-KEY-ID!" # Get ID from Part 3
set pgp_autosign = yes
# ... your private imap_user, imap_pass, smtp_url, etc. go here

Method B: Manual Switching (for `mutt-wizard` users)

Many users rely on the popular mutt-wizard script, which favors manual account switching via macros. If your muttrc contains lines like macro index,pager i1 'source ...', this method is for you.

Step 1: Locate Your Account Files mutt-wizard creates a separate configuration file for each of your accounts, typically located in ~/.config/mutt/accounts/.

Step 2: Add pgp_sign_as to Each Account File For each account, edit its corresponding file and add the pgp_sign_as line to tell Neomutt which PGP key to use.

Get the Key-ID for the key you want to use with this account (as described in Part 3).
Open the account’s configuration file (e.g., ~/.config/mutt/accounts/delightfuldude@criticalbasics.xyz.muttrc).

Add the following line, replacing YOUR-KEY-ID! with the actual ID:

# Inside e.g., ~/.config/mutt/accounts/delightfuldude@criticalbasics.xyz.muttrc

# ... existing settings like 'set from', 'set realname', etc.

# Add this line to set the default PGP signing key for this account
set pgp_sign_as = YOUR-CRITICALBASICS-KEY-ID!

Result: Now, when you use your keyboard macros (e.g., i1, i2) 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.

9. Transferring Your Configuration Between Computers

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.

9.1. What Files to Transfer

The most important directory is ~/.gnupg/, which contains:

Your private and public keys
GPG Agent configuration
Trust database (Web of Trust)

Additionally, depending on your email client:

Thunderbird: Thunderbird accesses the GnuPG keyring directly, so transferring the .gnupg directory is sufficient.
Neomutt: You’ll also need to copy your configuration files:
- ~/.config/neomutt/muttrc
- ~/.config/neomutt/accounts/ (if you have multiple accounts)

9.2. Transfer Process

Secure Transfer: Use a secure channel for transferring these files (encrypted USB drive, encrypted file transfer).

Copy the Directory: Copy the entire .gnupg directory to the same location on the target computer.

# On the source computer, create a secure backup
tar -czf gnupg-backup.tar.gz -C ~ .gnupg

# Transfer securely to the target computer and extract
# On the target computer:
tar -xzf gnupg-backup.tar.gz -C ~

Fix Permissions: After transferring, ensure proper permissions:
```
chmod 700 ~/.gnupg
chmod 600 ~/.gnupg/*
```
Adjust Pinentry Configuration: If the target system has a different desktop environment, you may need to modify the pinentry-program path in ~/.gnupg/gpg-agent.conf.
Reload GPG Agent: After transferring, reload the GPG agent:
```
gpg-connect-agent reloadagent /bye
```
Verify the Setup: Test that your keys are available:
```
gpg --list-secret-keys
```

By following these steps, you can efficiently use your OpenPGP setup across multiple computers without repeating the entire configuration process.

10. Quick Troubleshooting

  <colgroup>
    
      <col width="40%">
    
      <col width="60%">
    
  </colgroup>


<thead><tr><th>Problem</th><th>Solution</th></tr></thead><tbody>

“gpg: signing failed: Ambiguous specification”	You have multiple keys for one email. Use the unique Key-ID instead of the email address in your configuration (e.g., `pgp_sign_as` in Neomutt).
No password prompt appears	Your `pinentry` program is missing or misconfigured. Go back to Part 1.2 and ensure it is installed and configured correctly.
GPG Agent Issues (Passphrase not requested)	The GPG agent might have a stale cache. Force a reload with: `gpg-connect-agent reloadagent /bye`
“Key not found” error	You don’t have the recipient’s public key. Ask them for it or search a keyserver.
“gpg: signing failed: No secret key”	Your key might be expired, or GPG cannot find the correct secret key. Check `gpg --list-secret-keys` to ensure it’s present and valid.
Message shows “untrusted signature”	You have the sender’s public key, but you haven’t marked it as trusted. Verify the fingerprint and then sign it.

11. Conclusion

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.

📚OPENPGP DOCUMENTATION 🛡️GNUPG DOCUMENTATION

Tutorial: Integrating ranger and sxiv with Advanced Features

Unknown — Sun, 06 Jul 2025 00:00:00 +0000

This tutorial combines all the necessary steps to seamlessly integrate sxiv and ranger, including:

Launching a gallery view from ranger
Configuring keybindings in ranger
Creating an interactive “Open with…” menu in sxiv
Opening ranger from within sxiv
Navigating and using shortcuts in sxiv
Increasing thumbnail sizes by recompiling sxiv

Prerequisites

Arch Linux (or a similar distro; this guide refers to pacman and the AUR)
sxiv and ranger installed
A terminal emulator (e.g., xterm, urxvt, alacritty, kitty)
Standard command-line tools (file, grep, sed, etc.)
gtk-launch (usually available via xdg-utils or a similar package)

1. Set Up the ranger Keybinding (Launch Gallery)

Open your ranger configuration file: ~/.config/ranger/rc.conf.
Add a line to open sxiv in thumbnail mode recursively using a key combination. For example, gG:
```
# Open sxiv in thumbnail mode (-t) recursively (-r) in the current directory (%d)
map gG shell sxiv -tr %d &
```
- -t enables thumbnail mode.
- -r searches subdirectories recursively.
- The trailing & ensures that ranger does not wait for sxiv to close.
Save the file and reload the configuration in ranger with:
```
:reload_config
```
or simply restart ranger.

2. Navigating in sxiv

Open Gallery View: Use sxiv -tr /path/to/your/folder to start directly in thumbnail mode.
Open a Single Image: Highlight an image in the gallery and press Enter.
Switch Between Images (Single-Image Mode):
- n or Space: Next image
- p or Backspace: Previous image
- ]: 10 images forward
- [: 10 images backward
- g: First image, G: Last image
- Right mouse click: Next image, Left mouse click: Previous image
Zoom in the Gallery:
- +: Zoom in
- -: Zoom out
To increase the maximum zoom level, you need to recompile sxiv (see Section 4).

3. Interactive “Open with…” and Ranger Integration in sxiv

We will create a key-handler script that allows the following:

Ctrl-x r: Opens ranger in a new terminal, selecting the current file.
Ctrl-x o (or any other key): Displays an interactive menu of all suitable applications and opens the image with the selected one.

3.1. Create the Script

Create the directory:
```
mkdir -p ~/.config/sxiv/exec
```

Create the file ~/.config/sxiv/exec/key-handler and paste the following content in its entirety:

#!/usr/bin/env sh
#
# ~/.config/sxiv/exec/key-handler
# Interactive script for sxiv:
# - Ctrl-x r → opens ranger in a new terminal with the current file selected
# - Ctrl-x o (and others) → opens an "Open with…" menu to choose an application
# Robust handling of spaces, logging, and i3-compatible terminals

# Logfile for debugging and tracking
LOG=/tmp/sxiv-open.log
echo "=== key-handler started $(date) ===" >>"$LOG"

# Terminal emulator used to open the selection menu
# Possible options: xterm, urxvt, alacritty, kitty …
TERMWIN=${TERMWIN:-urxvt}
echo "TERMWIN set to: $TERMWIN" >>"$LOG"

# $1 contains the key pressed after Ctrl-x
cmd="$1"
echo "Command argument: $cmd" >>"$LOG"

# Remove the prefix argument; all image paths follow via stdin
shift

# Process each file individually (handles paths with spaces)
while IFS= read -r img; do
  echo "Processing file: '$img'" >>"$LOG"

  # === Ranger Integration (Ctrl-x r) ===
  if [ "$cmd" = "r" ]; then
    echo "Ranger Integration: Opening ranger in terminal for '$img'" >>"$LOG"
    # Ranger needs a terminal, so launch it via a terminal emulator
    "$TERMWIN" -e ranger --selectfile="$img" &
    continue
  fi

  # === Default Open-with… Menu (Ctrl-x o or other keys) ===
  # 1) Determine the MIME type of the file
  mime=$(file --mime-type -b "$img")
  echo " MIME-Type: $mime" >>"$LOG"

  # 2) Find matching .desktop files for this MIME type
  mapfile -t apps < <(
    grep -Rl "MimeType=.*$mime" \
      /usr/share/applications ~/.local/share/applications 2>/dev/null \
    | xargs -r -n1 basename \
    | sort -u
  )
  if [ ${#apps[@]} -eq 0 ]; then
    echo " No matching applications found for MIME '$mime'" >>"$LOG"
    continue
  fi
  echo " Found applications: ${apps[*]}" >>"$LOG"

  # 3) Create temporary files for the list and the choice
  list_file=$(mktemp)
  tmp_choice=$(mktemp)
  printf "%s\n" "${apps[@]}" >"$list_file"
  echo " List file: $list_file" >>"$LOG"
  echo " Choice file: $tmp_choice" >>"$LOG"

  # 4) Open the terminal selection menu
  "$TERMWIN" -e bash -lc '
    PS3="Open with: "
    # Read all entries into an array
    IFS=$'\''\n'\'' read -rd "" -r -a options < "'"$list_file"'"
    select opt in "${options[@]}"; do
      # Write the choice to the temp file
      echo "$opt" > "'"$tmp_choice"'"
      break
    done
  '

  # 5) Read the choice and clean up
  choice=$(<"$tmp_choice")
  rm -f "$list_file" "$tmp_choice"
  echo " Selected: $choice" >>"$LOG"
  [ -n "$choice" ] || continue

  # 6) Find the full .desktop file path
  desktop=""
  for d in /usr/share/applications ~/.local/share/applications; do
    if [ -f "$d/$choice" ]; then
      desktop="$d/$choice"
      break
    fi
  done
  echo " Desktop entry: $desktop" >>"$LOG"

  # 7) Read the Exec line and remove placeholders
  exec_cmd=$(grep -m1 '^Exec=' "$desktop" \
             | cut -d= -f2- \
             | sed -E 's/ %[fFuUdDnNickvm]//g')
  echo " Exec command: $exec_cmd" >>"$LOG"

  # 8) Execute the program with the image path
  eval "$exec_cmd \"$img\"" &
  echo " Application started for '$img'" >>"$LOG"
done

# End of log
echo "=== key-handler finished ===" >>"$LOG"

Make the script executable:

chmod +x ~/.config/sxiv/exec/key-handler

TERMWIN variable (optional): If you want to use a terminal other than urxvt, like alacritty, add this to your ~/.bashrc / ~/.profile:
```
export TERMWIN=alacritty
```

4. Thumbnail Sizes (Optional: Recompiling sxiv)

By default, the available thumbnail sizes in sxiv are limited to { 32, 64, 96, 128, 160 } px. If 160px is too small, you can increase them as follows:

Get the sources from the AUR (example using sxiv-git):

git clone https://aur.archlinux.org/sxiv-git.git
cd sxiv-git

Generate config.h:
```
make config.h
```

Adjust Thumbnail Sizes: Open the config.h file and find the _THUMBS_CONFIG section. Change the block to something like this:

#ifdef _THUMBS_CONFIG

/* thumbnail sizes in pixels (width == height): */
static const int thumb_sizes[] = { 32, 64, 96, 128, 160, 256, 320, 400 };

/* default thumbnail size on startup (index in thumb_sizes[]): */
static const int THUMB_SIZE = 5;  // starts at 256 px
#endif

Compile and install:
```
make
sudo make install
```
Use the New Thumbnail Sizes: In sxiv, sizes up to 400px are now available. Use + to increase and - to decrease the size.

5. Summary of Keybindings

5.1 Ranger Shortcuts

Action	Command
Start sxiv gallery in current directory	`gG`

5.2 sxiv Gallery Mode Shortcuts

Action	Command
Open single-image view	`Enter`
Mark an image (for multi-selection)	`m`
Zoom in	`+`
Zoom out	`-`
“Open with…” menu (interactive)	`Ctrl-x o`
Open ranger in a new terminal with file selected	`Ctrl-x r`

5.3 sxiv Single-Image Mode Shortcuts

Action	Command
Next image	`n` or `Space`
Previous image	`p` or `Backspace`
10 images forward	`]`
10 images backward	`[`
First image	`g`
Last image	`G`
Play/stop GIF animation	`Ctrl-Space`

6. Debugging & Logs

All actions from the key-handler script are logged to /tmp/sxiv-open.log. There you can see:

The key that was used (ctrl-x r or ctrl-x o).
The detected MIME type.
The found .desktop entries.
The chosen application and the executed command.
The ranger call.

Example:

=== key-handler started Mon Apr 28 18:01:20 CEST 2025 ===
TERMWIN set to: xterm
Command argument: o
Processing file: '/home/.../Example.png'
 MIME-Type: image/png
Found applications: gimp.desktop firefox.desktop ...
List file: /tmp/tmp.XXXXXX
Choice file: /tmp/tmp.YYYYYY
Selected: gimp.desktop
Desktop entry: /usr/share/applications/gimp.desktop
Exec command: gimp-3.0
Application started for '/home/.../Example.png'
=== key-handler finished ===

If something goes wrong, you can check the log:

less /tmp/sxiv-open.log

Vim Tip: How to Insert the Current Time with a Shortcut

Unknown — Thu, 03 Jul 2025 00:00:00 +0000

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.

In this short guide, you’ll learn how to use a single, clever line in your .vimrc to create a shortcut that lets you insert the current time instantly and effortlessly at any position.

The Solution: A Shortcut for Insert Mode

This method is ideal when you’re in the middle of writing and want to insert a timestamp directly into the text, for example:

14:32 – Call from the project manager

To do this, simply add the following line to your ~/.vimrc:

" Insert the current time (HH:MM) in insert mode with <leader>t
inoremap <leader>t <C-R>=strftime('%H:%M')<CR>

How It Works

This single line is a perfect example of Vim’s power:

inoremap <leader>t: Defines a key mapping (by default \t) exclusively for insert mode.
<C-R>=: This is the magic part. In insert mode, Ctrl-R normally inserts the content of a register. When you add an equals sign (=), Vim opens a mini-command line and evaluates the following expression.
strftime('%H:%M'): This is a built-in Vim function that returns the current time, formatted. %H stands for the hour (24h) and %M for the minute.
<CR>: Confirms the function, inserts its result (the time) at the cursor’s position, and seamlessly returns you to insert mode.

How to use it: The next time you’re typing in a note, just press \ followed by t, and the current timestamp will appear instantly in the text.

Customize It to Your Needs

The best part of this method is its flexibility. You can customize the timestamp format however you like by changing the string inside the strftime() function.

Here are a few popular alternatives for your .vimrc:

" -- EXAMPLE 1: Time with seconds --
inoremap <leader>ts <C-R>=strftime('%H:%M:%S')<CR>

" -- EXAMPLE 2: Full date and time (ISO standard) --
inoremap <leader>dt <C-R>=strftime('%Y-%m-%d %H:%M')<CR>

" -- EXAMPLE 3: US Date Format --
inoremap <leader>us <C-R>=strftime('%m/%d/%Y %I:%M %p')<CR>

Bonus: Inserting a Timestamp in Normal Mode

Sometimes you might want to insert a timestamp on its own new line. For that, a normal mode shortcut is better suited.

" Insert the current time on a new line below the current one
nnoremap <leader>T :put =strftime('%H:%M')<CR>

With this mapping, you can press \T in normal mode, and the time will be placed cleanly on the next line.

Summary

With this simple trick, you’ve further optimized your workflow:

✅ 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.

📂EXPLORE ALL STRFTIME() OPTIONS

ℹ️ WHAT'S NEXT?
Now that you’ve mastered timestamps, discover how to perfect links, navigation, and task management in our Vimwiki Workflow Guide.

A Guide to Zathura: The Minimalist PDF Viewer

Unknown — Thu, 03 Jul 2025 00:00:00 +0000

This tutorial will guide you through installing, configuring, and using Zathura with the MuPDF backend on Arch Linux, specifically tailored for an i3wm environment. It covers installation, configuration, printing, and a comprehensive overview of the most important shortcuts.

1. Introduction

Zathura is a lightweight yet powerful PDF viewer that features a minimalist user interface, making it an excellent fit for lightweight window managers like i3wm. By using plugin backends like MuPDF or Poppler, you can maintain a minimal setup without sacrificing essential features such as search, bookmarks, or printing.

Advantages of Zathura:

Very few dependencies (only Girara/GTK, and a backend like MuPDF or Poppler)
Keyboard-centric control (ideal for i3wm)
Extensible via plugins (e.g., for Synctex or annotations)
Highly configurable through a simple text file

2. Installation

Install Zathura & the MuPDF Backend Open a terminal and execute the following command:
```
sudo pacman -S zathura zathura-pdf-mupdf
```
Launch Zathura After installation, you can open a PDF file like this:
```
zathura document.pdf
```

3. Setting Zathura as the Default PDF Viewer

If you were previously using a different viewer like Evince (e.g., in mimeapps.list), your configuration might look like this:

application/pdf=org.gnome.Evince.desktop

To make Zathura the new default for PDF files, you need to add or edit the following line in your ~/.config/mimeapps.list (or ~/.local/share/applications/mimeapps.list):

[Default Applications]
application/pdf=org.pwmt.zathura.desktop

This sets Zathura as the default application for the application/pdf MIME type.

4. Configuring Zathura

Zathura reads its configuration from ~/.config/zathura/zathurarc. Here is an example of a minimal configuration:

# ~/.config/zathura/zathurarc

# 1. Set the default backend to MuPDF
set pdf-mupdf true

# 2. Adjust page to fit width on open
set adjust-open "fit-width"

# 3. Set default zoom level (100%)
set zoom 1.0

# 4. Remap keys (optional)
map <C-f> search-forward
map <C-b> search-backward

# 5. Set bookmark file path
set bookmark-path "~/.config/zathura/bookmarks"

Explanation of Key Options

set pdf-mupdf true: Specifies that Zathura should use the MuPDF backend instead of Poppler.
set adjust-open "fit-width": Automatically fits the page to the window’s width when opening a document.
set zoom 1.0: Sets the default zoom level to 100%.
map <C-f> search-forward: Remaps Ctrl+f for searching forward.
map <C-b> search-backward: Remaps Ctrl+b for searching backward.
set bookmark-path "...": Defines the directory where bookmark files are stored.

5. Printing Functionality

Zathura supports printing directly via GTK. To print a PDF:

Open the PDF in Zathura:
```
zathura document.pdf
```
In the viewer, simply press P or enter the command:
```
:print
```
The standard GTK print dialog will open, allowing you to select a printer, page range, scaling, and other options.

Internally, GTK generates a temporary PDF (using Cairo) and sends it to CUPS, so no additional plugins are usually necessary.

Tip: If you prefer to print directly from the shell, you can always use:
lp document.pdf
This works independently of your chosen PDF viewer.

6. Overview of Essential Keyboard Shortcuts

Zathura is heavily designed for keyboard control. Below are the most useful shortcuts organized by category.

Action	Command
Next Page	`j` or `↓`
Previous Page	`k` or `↑`
First Page	`gg`
Last Page	`G`
Go to Specific Page	`:page <number>` (e.g., `:page 10`)

6.2 Zoom & View

Action	Command
Zoom In	`zi` or `+`
Zoom Out	`zo` or `-`
Original Size	`zr`
Fit to Width	`zb`
Fit to Height	`zh`
Toggle Fullscreen	`f`

6.3 Search & Bookmarks

Action	Command
Search Forward	`/` followed by search term
Search Backward	`?` followed by search term
Next Search Result	`n`
Previous Search Result	`N`
Add Bookmark	`m` (then choose a letter)
Open Bookmark List	`:bookmarks`
Jump to Bookmark	` followed by the letter

6.4 Document Operations

Action	Command
Print	`P` or `:print`
Reload Document	`R`
Open Console (Command line in viewer)	`:`

6.5 General Commands

Action	Command
Show Help	`H`
Reload Configuration	`:config-reload`
Quit	`q`

Note: Many of these commands can be remapped in ~/.config/zathura/zathurarc. See Section 4 for examples.

7. Summary

Installation:

sudo pacman -S zathura zathura-pdf-mupdf
```-   **Set as Default PDF Viewer:**
In `~/.config/mimeapps.list`:
```ini
[Default Applications]
application/pdf=org.pwmt.zathura.desktop

Configuration: Via ~/.config/zathura/zathurarc (see example file).
Usage: Keyboard-centric, with quick access to search, zoom, bookmarks, and printing (P / :print).
Printing: Opens the GTK print dialog, using CUPS via Cairo.

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.

Enjoy reading with Zathura on i3wm

Dual Journaling with Vimwiki: How to Separate Personal and Business Notes

Unknown — Wed, 02 Jul 2025 00:00:00 +0000

In the previous post, 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.

Changelog

Date	Change
2025-07-02	Created a direct workflow for general notes: Added a new custom function (`CreateGeneralNote`) and corresponding shortcuts (`\nb`, `\np`) to directly create topic-based notes with a filename prompt, addressing a major workflow flaw.
2025-06-20	Major Revision: Clarified Wiki vs. Journal distinction, improved naming consistency for directories, and created more intuitive shortcuts.
2025-06-19	Initial version of the article.

This guide will show you how to build a dual-wiki system to cleanly separate your personal and business notes. We will cover how to create both daily Journal Entries and topic-based General Notes in their correct contexts.

Step 1: Understanding the Structure

Before we configure anything, let’s understand the hierarchy we are building. A Wiki is the main container for a context (e.g., “Business”). Within that wiki, there are two types of notes:

General Notes: Topic-based pages like “Project Alpha Ideas” or “Meeting Checklists”. They live in the root of the wiki.
Journal Entries: Date-based, daily logs. They live in the diary/ subdirectory.

This is the structure we will create:

~/Nextcloud/Notes/
├── wiki-business/
│   ├── diary/
│   │   └── 2025-07-04.md
│   ├── Project Alpha.md
│   └── index.md
│   └── template-business-journal.md
│
└── wiki-personal/
    ├── diary/
    │   └── 2025-07-04.md
    ├── Holiday Plans.md
    └── index.md
    └── template-personal-journal.md

This clean separation is the key to an organized system.

Step 2: Update Your Vimwiki Configuration

First, configure your ~/.vimrc to define the two wikis. Using expand('~') makes the configuration robust.

" Vimwiki Configuration for multiple wikis
let g:vimwiki_list = [
  \ {
    \ 'path': expand('~') . '/Nextcloud/Notes/wiki-business/',
    \ 'diary_template': 'template-business-journal.md',
    \ 'syntax': 'markdown', 'ext': '.md'
  \ },
  \ {
    \ 'path': expand('~') . '/Nextcloud/Notes/wiki-personal/',
    \ 'diary_template': 'template-personal-journal.md',
    \ 'syntax': 'markdown', 'ext': '.md'
  \ }
\]

" Optional: Set a default wiki (1=first, 2=second).
let g:vimwiki_start_wiki = 2 " Make the personal wiki the default

" These settings apply to all wikis in the list
let g:vimwiki_markdown_link_ext = 1
let g:vimwiki_auto_diary_index = 1

Next, create the necessary directories in your terminal:

mkdir -p ~/Nextcloud/Notes/wiki-business/diary
mkdir -p ~/Nextcloud/Notes/wiki-personal/diary

Step 3: Create Context-Specific Journal Templates

Create a unique template for each journal. Each template file must be placed in the root directory of its corresponding wiki.

Business Journal Template

Create the file ~/Nextcloud/Notes/wiki-business/template-business-journal.md:

# %Y-%m-%d — Business Journal

## 🎯 Today's Top 3 Priorities
- [ ] 
- [ ] 
- [ ]

Personal Journal Template

Create the file ~/Nextcloud/Notes/wiki-personal/template-personal-journal.md:

# %Y-%m-%d — Personal Journal

## 🙏 Gratitude
- 

## 💡 Ideas & Thoughts
-

Step 4: The Core Solution: Custom Vim Functions

A standard Vimwiki installation has two limitations for our workflow:

:VimwikiMakeDiaryNote does not automatically apply templates.
There is no direct command to create a new, named topic note.

We will solve both issues with two dedicated functions in our ~/.vimrc.

In Your `.vimrc`

Add these two functions and their corresponding shortcuts to your Vim configuration.

" ----- FUNCTION 1: FOR DAILY JOURNAL ENTRIES -----
function! OpenJournalWithTemplate(wiki_index)
  " Switch to the correct wiki context
  execute 'VimwikiTabIndex ' . a:wiki_index
  " Create or open today's diary note
  VimwikiMakeDiaryNote
  " CRITICAL: Force Vim to update its state before we check the file
  redraw
  " Check if the file is new and empty
  if line('$') == 1 && getline(1) == ''
    let l:wiki_config = g:vimwiki_list[a:wiki_index - 1]
    let l:template_path = l:wiki_config.path . l:wiki_config.diary_template
    " If the template file exists, read its content into our new file
    if filereadable(l:template_path)
      execute '0read ' . l:template_path
      1delete " Delete the initial empty line
      normal! gg " Go to the top
    endif
  endif
endfunction

" ----- FUNCTION 2: FOR GENERAL TOPIC NOTES -----
function! CreateGeneralNote(wiki_index)
  " Switch to the correct wiki context
  execute 'VimwikiTabIndex ' . a:wiki_index
  " Open the index page of that wiki
  VimwikiIndex
  " Prompt the user for the name of the new note
  let l:note_name = input('Enter name for new note: ')
  " Proceed only if a name was entered
  if !empty(l:note_name)
    " Go to the end of the index file and add a new link
    call append(line('$'), '* [[' . l:note_name . ']]')
    " Move the cursor to the newly created line
    call cursor(line('$'), 1)
    " 'Press Enter' on the link to create and open the new file
    VimwikiFollowLink
  endif
endfunction

" ----- KEYBOARD SHORTCUTS -----
" For Journals (e.g., \jb for Journal-Business)
nnoremap <leader>jb :call OpenJournalWithTemplate(1)<CR>
nnoremap <leader>jp :call OpenJournalWithTemplate(2)<CR>

" For General Notes (e.g., \nb for Note-Business)
nnoremap <leader>nb :call CreateGeneralNote(1)<CR>
nnoremap <leader>np :call CreateGeneralNote(2)<CR>

In Your Shell (`.bashrc` or `.zshrc`)

Create a full set of aliases in your shell configuration to call these functions directly.

# Aliases for Journal Entries
alias journalb='vim -c "call OpenJournalWithTemplate(1)"'
alias journalp='vim -c "call OpenJournalWithTemplate(2)"'

# Aliases for General Topic Notes
alias noteb='vim -c "call CreateGeneralNote(1)"'
alias notep='vim -c "call CreateGeneralNote(2)"'

# Optional: Shorter aliases
alias jb='journalb'
alias jp='journalp'
alias nb='noteb'
alias np='notep'

Reload your shell (source ~/.bashrc or source ~/.zshrc) to activate them.

Step 5: How to Use Your Dual System

Your workflow is now clean, logical, and direct for both use cases.

Workflow 1: Create a Daily Journal Entry

Use this for date-based, chronological logs.

From inside Vim: Press \jb (Business) or \jp (Personal).
From your terminal: Run journalb or jb (Business) / journalp or jp (Personal).

Result: Today’s journal file is created in the diary/ folder, and the correct template is applied.

Workflow 2: Create a General Topic Note

Use this for any non-daily, topic-based note like a project plan, a checklist, or meeting notes.

From inside Vim: Press \nb (Business) or \np (Personal).
From your terminal: Run noteb or nb (Business) / notep or np (Personal).

Result: You will be prompted in Vim to enter a name for the new note. 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 index.md.

Step 6: Linking Between Wikis

The concept of linking between wikis is now much clearer. Imagine you’re in your personal journal and have an idea for a business project.

In your personal journal file, you can write:

## 💡 Ideas & Thoughts
- I just had an idea for work, I'll start a new note for it in my business wiki.
- To create it, I can just write the link here and press Enter: [[wiki1:My New Business Idea]]

wiki1: tells Vimwiki to use the first wiki in your list (your business-wiki).

When you press Enter, Vimwiki creates the file My New Business Idea.md in the root of your wiki-business/ and opens it.

Summary

By creating two dedicated functions, you have built a powerful, intuitive, and robust system:

✅ A clean separation between your wiki-business and wiki-personal. ✅ A clear, direct workflow for creating both daily Journals and topic-based General Notes. ✅ Custom journal templates that are correctly and automatically applied. ✅ Lightning-fast, unambiguous shortcuts (jb, jp, nb, np) for both Vim and your shell. ✅ The power to intelligently link between worlds when needed.

This setup transforms a simple note-taking tool into a comprehensive life management system.

Explore Vimwiki Further 📂

ℹ️ WHAT'S NEXT?
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.

Mastering the Vimwiki Workflow: A Guide to Links, Navigation, and Tasks

Unknown — Wed, 02 Jul 2025 00:00:00 +0000

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?

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.

The Heart of Your Wiki: The `index.md`

Each of your Vim wikis has a central homepage: the index.md file located in the root directory. Think of it as your personal dashboard or table of contents for that wiki.

From here, you should link to all of your important, topic-based notes.

How to open the index page: From anywhere in Vim, press <leader>ww (usually \ww) to instantly jump to the index page of the current wiki.

A well-maintained index might look like this:

# Business Wiki Index

## Projects
* [[Project Alpha]]
* [[Q4 Strategy Planning]]

## Processes & Checklists
* [[Meeting Checklist]]
* [[New Employee Onboarding]]

## References
* [[Important Contacts]]

The Magic of Linking

Creating notes and linking ideas is the core of Vimwiki. The process is brilliantly simple.

Write a Link: Anywhere in a wiki file, write the name of a new or existing note in double square brackets.
```
I had an idea for [[Project Alpha]].
```
Follow the Link: Move your cursor over the link and press Enter.

What happens?

If the file Project Alpha.md already exists, Vimwiki opens it.
If the file does not exist, Vimwiki automatically creates it for you and opens the new, empty file.

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.

Pro-Tip: You can also create subdirectories by using a forward slash: [[projects/New Project]] will create the file New Project.md inside the projects/ folder.

Switching between notes quickly is crucial. Vimwiki primarily uses Vim’s brilliant, built-in commands for this.

Jump back to the previous note: Press Ctrl-O. This is the most important navigation command. It takes you right back to where you came from after following a link.
Jump forward again: Press Ctrl-I to reverse the jump.
Go back to the index page: <leader>ww is your “home button,” always taking you back to the main index of the current wiki.
Go back to today’s journal: <leader>w<leader>w (or your custom mappings like \jb/\jp) will instantly take you to your daily journal entry.

More Than Just Notes: Practical Task Management

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.

Write a list like this:

- [ ] Open task
- [ ] Another task that needs to be done

Now, move your cursor onto one of these lines and press g<Space> (that’s g followed by the spacebar).

Vimwiki will cycle through the task’s status:

[ ] → Open
[.] → Started / In Progress (optional)
[X] → Completed
[-] → Canceled / Irrelevant

This is an incredibly fast and satisfying way to manage tasks without ever leaving Vim.

Important Tips and Tricks for Daily Use

Rename Files (and update all links!): Move your cursor onto a link to a file and run :VimwikiRenameLink. Enter the new name, and Vimwiki will not only rename the file but also automatically update all other files that link to that note.
Format Tables: Create a simple table using pipes (|):
```
| Column 1 | Column 2 |
|---|---|
| a | b |
| longer text | c |
```
Then, with your cursor inside the table, run the command :VimwikiTable. Vimwiki will format it perfectly for you.
Find Anything: Use :VimwikiSearch [keyword] to search your entire current wiki. The results are displayed in a handy quickfix list that you can navigate through quickly.

Summary

You now have the tools to not just own Vimwiki, but to truly master it:

✅ You use the index.md as your central dashboard. ✅ You seamlessly create and connect notes with the [[Link]] syntax. ✅ You navigate at lightning speed with Ctrl-O and <leader>ww. ✅ You manage tasks directly in your notes with g<Space>.

This fluid workflow transforms Vimwiki from a simple note-taking tool into a powerful “second brain.”

📂EXPLORE VIMWIKI ON GITHUB

ℹ️ WHAT'S NEXT?
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 dual-journaling system.

Getting Started with Vim Plugins: A Beginner's Guide to vim-plug

Unknown — Thu, 26 Jun 2025 00:00:00 +0000

So you’ve found an exciting Vim plugin—perhaps for journaling with Vimwiki—and you’re ready to supercharge your editor. This guide will walk you through setting up vim-plug, 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.

What is a Plugin Manager and Why `vim-plug`?

A plugin manager automates the tedious process of:

Downloading plugin files from sources like GitHub.
Placing them in the correct directories.
Loading them when Vim starts.
Updating and removing them easily.

I recommend vim-plug because it is:

Minimalist: It’s just a single file, making installation trivial.
Fast: It can install and update plugins in parallel.
Easy to Use: The commands are simple and memorable.

Step 1: Install `vim-plug`

vim-plug itself needs to be downloaded first. The official and easiest way is to run a single command in your terminal. This command downloads the plug.vim file and places it in Vim’s autoload directory, which ensures it’s loaded automatically when Vim starts.

Open your terminal and execute:

curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
    https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim

That’s it. The plugin manager is now “installed.”

Step 2: Structure Your `.vimrc` for Plugins

Next, you need to tell Vim which plugins you want to use. This is done in your ~/.vimrc file inside a special block.

Open your ~/.vimrc.
Add the following structure. All your plugin declarations must go between the call plug#begin() and call plug#end() lines.

" 1. VIM-PLUG SECTION
" This block must be at the top of your .vimrc
call plug#begin('~/.vim/plugged')

" List your plugins here
" Example:
Plug 'vimwiki/vimwiki'
Plug 'dracula/vim', { 'as': 'dracula' } " A popular theme

call plug#end()


" 2. YOUR CONFIGURATIONS
" All other settings go AFTER the vim-plug block
syntax enable
colorscheme dracula

let g:vimwiki_list = [{ 'path': '~/vimwiki/' }]
" ... and so on

plug#begin(): Initializes the plugin manager. The argument ('~/.vim/plugged') is the directory where vim-plug will download and store all your plugins.
Plug 'author/repository': This is the command to declare a plugin.
plug#end(): Finalizes the list and loads the plugins.

Step 3: Install the Plugins with `:PlugInstall`

Now that your .vimrc is configured, you can tell vim-plug to fetch and install the plugins you’ve listed.

Save your ~/.vimrc file and restart Vim, or source the file with :so ~/.vimrc.
Run the vim-plug installation command inside Vim:
```
:PlugInstall
```
A new window will open, showing the installation progress for each plugin. Once you see “Finished!”, you can close the status window (:q) and start using your new plugins.

Your Plugin Management Cheat Sheet

Managing plugins is now simple. Here are the essential commands you’ll use:

:PlugInstall: Install any new plugins you’ve added to your .vimrc.
:PlugUpdate: Update all installed plugins to their latest versions.
:PlugClean: Remove any plugins that are in your plugged directory but no longer listed in your .vimrc.
:PlugStatus: Show the status of all your plugins.

Summary: Your Foundation is Ready

Congratulations! You have successfully set up a robust system for managing Vim plugins. You now understand:

How to install vim-plug.
How to structure your .vimrc to declare plugins.
How to install, update, and manage them with simple commands.

You are now fully equipped to customize Vim to your heart’s content and can confidently follow tutorials like our guides to setting up a Vimwiki journal or creating a dual-journaling system.

ℹ️ A NOTE ON THE KEY
Many Vim tutorials (including ours) use shortcuts like `<leader>wp`. The `<leader>` 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 (`\`). You can set it to a more convenient key, like the comma, by adding this to your `.vimrc`: `let mapleader = ","` Now, `<leader>wp` would be typed as `,wp`.

Spell Checking in Vim: A Comprehensive Guide

Unknown — Wed, 25 Jun 2025 00:00:00 +0000

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.

Changelog

Date	Change
2025-06-25	Added QWERTZ key mappings and `.sug` file clarification.
2025-06-25	Initial version of the guide.

Enabling Spell Checking

To enable Vim’s spell checker, use the :set spell command. You can type this directly into Vim for the current session, or add it to your ~/.vimrc file for permanent activation.

:set spell            " Turn on spell checking
:set spelllang=en_us  " Set the default language (e.g., US English)

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.

For German, switch to:

:set spelllang=de_de  " Set German dictionary

You can list multiple languages, and Vim will check against all of them:

:set spelllang=de_de,en_us

Pro-tip: Vim supports regional variants like en_gb (British), en_ca (Canadian), and en_au (Australian).

Managing Spell Files

Vim uses two main types of files for spell checking:

The main dictionary (.spl file), a compressed word list used for all checks.
A supplementary suggestions file (.sug file), which pre-computes lists of similar words to provide fast suggestions.

Benefits and Trade-offs of the `.sug` file

With .sug downloaded: z= suggestion requests are fast and comprehensive, as Vim doesn’t need to calculate similarities on the fly.
Without .sug: Vim computes suggestions at runtime, saving disk space and RAM until a suggestion is needed.

On-Demand Loading

Vim only loads the .sug file into memory when you invoke suggestions (e.g., by pressing z=). Simply enabling spell check and navigating errors with ]s/[s won’t load the larger .sug file, keeping your memory footprint minimal until you request corrections.

]s : Jump to the next misspelled word
[s : Jump to the previous misspelled word
z= : On a highlighted word, opens the suggestion list
zg : Add word to good list (your personal dictionary)
zw : Mark word as wrong

" Example vimrc settings:
set spell
set spelllang=de_de,en_us
" Optional: Define a custom file for your personal dictionary
set spellfile=~/.vim/spell/en.utf-8.add

Keyboard Layouts and Key Mappings

Vim’s navigation commands rely on specific characters (], [, s), not on physical keys. Below we cover the standard QWERTY layout and the German QWERTZ variant.

International QWERTY (Default Mapping)

Press ] then s to go to the next misspelling.
Press [ then s to go to the previous misspelling.

No special configuration is needed on US/UK keyboards, where [ and ] are directly accessible.

German QWERTZ Layout

On German keyboards, the square brackets require AltGr:

[: AltGr + 8
]: AltGr + 9

Thus, to navigate spelling corrections:

AltGr + 9, then s → ]s (next error)
AltGr + 8, then s → [s (previous error)

💡 QUICK KEY MAPPINGS ON QWERTZ
To simplify this, add these mappings to your `~/.vimrc`: `" F7: Next misspelling nnoremap <F7> ]s " F6: Previous misspelling nnoremap <F6> [s` We use `nnoremap` to create a non-recursive mapping in Normal mode, which is the safest way to define custom shortcuts. Now a single press of `F7` or `F6` navigates errors without needing `AltGr`.

Conclusion

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.

ℹ️ KEY COMMANDS AT A GLANCE
Quick reference: Navigate Errors with `]s` (next) and `[s` (previous); get suggestions with `z=`; add to dictionary with `zg`; mark as wrong with `zw`.

For a deeper dive into all available options, the official documentation is an excellent resource.

📖READ THE OFFICIAL DOCS

How to Keep a Structured Markdown Journal Using Vimwiki

Unknown — Thu, 19 Jun 2025 00:00:00 +0000

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 lightweight, private, and highly productive journaling system using vimwiki, all in plain text files synced via Nextcloud.

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.

Changelog

Date	Change
2025-06-19	Restructured article to move quick access methods into Step 3 for better visibility.
2025-06-18	Major revision: Added to-do lists, improved configuration, and corrected template/alias usage.
2025-06-17	Initial version of this article.

Why Use Vimwiki for Journaling?

vimwiki is a Vim plugin that transforms your editor into a personal wiki. It’s lightweight, fast, and supports:

Daily journal entries (diary mode)
Linked notes for projects or topics
To-do lists and simple task tracking
Markdown syntax for compatibility
Full offline access — works with Nextcloud or any sync service

If you’re already storing notes in Markdown, this is a perfect upgrade.

Step 1: Install `vimwiki`

Using vim-plug (or your plugin manager of choice), add this to your .vimrc:

Plug 'vimwiki/vimwiki'

Then launch Vim and run:

:PlugInstall

If you’re not using vim-plug, check the installation instructions here.

Step 2: Configure Vimwiki to Use Markdown

In your ~/.vimrc, configure vimwiki to store files in a Markdown format inside your Nextcloud folder. This configuration is cleaner and easier to maintain.

" Vimwiki Configuration
let g:vimwiki_list = [{
  \ 'path': '~/Nextcloud/Notes/wiki/', " Path to your wiki's root folder
  \ 'syntax': 'markdown',             " Use Markdown syntax
  \ 'ext': '.md'                      " Use .md as the file extension
\}]

" Ensures that created links include the .md extension for better compatibility
let g:vimwiki_markdown_link_ext = 1

" Automatically creates an index of all diary entries
let g:vimwiki_auto_diary_index = 1

Create the necessary folders manually if they don’t exist:

mkdir -p ~/Nextcloud/Notes/wiki/diary

Step 3: Creating and Accessing Your Daily Journal

The core of your journaling workflow is creating or opening the note for the current day. Here are the best ways to do it.

The Basic Command

The fundamental command to create or open today’s journal entry is:

:VimwikiMakeDiaryNote

This command will create a file like ~/Nextcloud/Notes/wiki/diary/2025-06-21.md if it doesn’t exist, and open it otherwise.

Recommended Methods for Quick Access

While the basic command works, typing it every time is impractical. For a fast and efficient workflow, use these shortcuts instead.

Method 1: From Inside Vim (The Fastest Way)

vimwiki comes with a built-in keyboard shortcut that is perfect for daily use. While in Vim’s normal mode, simply press:

<leader>w<leader>w

This is the most efficient way to open your journal when you are already working in Vim. The <leader> key is typically the backslash (\) by default.

Method 2: From Your Terminal

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 .bashrc or .zshrc file:

alias journal='vim -c "VimwikiMakeDiaryNote"'

After reloading your shell, you can now simply type journal in your terminal. This will launch Vim and immediately open today’s diary entry, applying your template if it’s a new day.

Example Entry

Regardless of which method you use to open it, your daily note will look something like this:

# 2025-06-21

## 09:02 – Call with Sarah
Discussed the project milestones. Need to follow up next Tuesday.

## 13:45 – Idea
Use `jrnl` CLI for quick journal entries via terminal.

## 20:15 – Reflection
Today was productive. Really enjoying the new Vim-based workflow.

Step 4: Create and Follow Internal Links

Link to another page in your wiki using vimwiki’s native syntax:

[[Project Alpha]]

Pressing Enter on this link will create and navigate to Project Alpha.md.

For universal compatibility with other Markdown editors (like Obsidian or QOwnNotes), you can use a standard Markdown link. vimwiki will still follow it if you press Enter.

[Project Alpha](Project%20Alpha.md)

The key difference is that [[Project Alpha]] is deeply integrated into vimwiki’s features (like backlinking), while the standard link is more portable across different applications.

Step 5: Create a Diary Template (Optional)

Add a default template for your daily entries. It’s best practice to store the template in your wiki’s root directory.

Create the template file: ~/Nextcloud/Notes/wiki/template.md

Important: vimwiki uses strftime format codes, not {{placeholders}}.
```
# %Y-%m-%d

## ☎️ Calls

## 💡 Ideas

## ✅ Tasks

## 📌 Notes

## 🔁 Reflection
```
Add this line to your .vimrc. Using a relative path makes your config more robust.
```
let g:vimwiki_diary_template = 'template.md'
```

Every new diary file created with :VimwikiMakeDiaryNote (or the shortcuts) will now use this layout.

Bonus Tips

Manage To-Do Lists: vimwiki has excellent support for task lists. Use g<Space> on a list item in Vim to cycle through states.
```
- [ ] An open task
- [.] A task in progress
- [X] A completed task
```
Quick Navigation: After following a link, press Ctrl-O to go back to the previous location and Ctrl-I to go forward.
Diary Index: Use :VimwikiDiaryIndex to open the diary/index.md — a central view of all your entries.
Search: Use :VimwikiSearch KEYWORD to find entries across your entire wiki.
Syncing: Sync your wiki/ folder with Nextcloud, and view or edit it from mobile apps like Markor (Android) or 1Writer (iOS).

Summary

With vimwiki, you can build a minimal yet powerful journaling system:

✅ Fully Markdown-compatible ✅ Terminal- and Vim-native ✅ Works offline and syncs via Nextcloud ✅ Extendable with links, to-do lists, templates, and more

No bloated app, no subscription, no cloud lock-in.

📂TRY VIMWIKI NOW

ℹ️ LOOKING FOR MORE VIM TIPS?
In a future post, we’ll explore how to integrate `jrnl` CLI with `vimwiki`, add backlinks support, and create a task dashboard — all using plain Markdown.

Retro-Compatible Zola Theme Showcase

Unknown — Mon, 16 Jun 2025 00:00:00 +0000

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.

Changelog

Date	Change
2026-09-08	Added optional individual article images, a cookie-free page-load counter, and JavaScript-calculated system uptime.
2025-07-11	Improved accessibility with skip links, focus indicators, and screenreader support
2025-06-16	Initial version of the theme showcase
2025-06-16	Added code block styling with retro terminal look
2025-06-16	Integration of additional fonts (Visitor, PixelOperator, Petiote, Virtual DJ, 5x5, Ambitsek, AddStandardBitmap)
2025-06-16	Headings highlighted with color (Purple)
2025-06-16	Added changelog table

What is Zola?

Zola 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:

Speed: Built with Rust for exceptional performance
Simplicity: Easy to use with a single binary
Flexibility: Powerful templating with Tera
Built-in Features: Syntax highlighting, search, and more
Live Reload: Instant preview of changes during development

About This Theme

The Retro-Compatible Zola Theme combines nostalgic aesthetics with modern functionality, offering:

Maximum Backward Compatibility: Support for browsers dating back to the 90s
Responsive Design: Optimized for desktop, tablet, and mobile devices
Retro Shortcodes: Special retro-style formatting elements
Pixel Fonts: VT323 and Perfect DOS VGA 437 for the authentic look
Three-Column Layout: Classic web design with modern responsiveness

ℹ️ THEME PURPOSE
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.

Compatibility Features

Browser Compatibility

This theme is designed to work with browsers dating back to the 90s, including:

Netscape Navigator 3.0 and earlier
Internet Explorer 3.0 and earlier
Opera 3.0 and earlier
Early WebTV browsers
Text-based browsers like Lynx

Technical Compatibility Features

HTML 4.01 Strict Doctype: For maximum compatibility
Table-based layouts: Instead of Flexbox or Grid
Simple color definitions: Using hexadecimal color codes
Progressive JavaScript: Core content works without JavaScript; the visitor counter and uptime display enhance themselves when it is available
Email-based forms: For guestbook and contact functionality

Font Showcase

This theme uses special pixel fonts to create an authentic retro look. Here’s a showcase of the main fonts used:

Main Fonts

VT323: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*()

Perfect DOS VGA 437: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*()

Commodore 64: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*()

Consolas: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*()

Courier New: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*()

Visitor: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*()

PixelOperator: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*()

Petiote: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*()

Virtual DJ: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*()

5x5: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*()

Ambitsek: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*()

AddStandardBitmap: The quick brown fox jumps over the lazy dog. 1234567890 !@#$%^&*()

Special Font: SerenityOS-Emoji

😀 😃 😄 😁 😆 😅 😂 🤣 🥲 ☺️ 😊 😇 🙂 🙃 😉 😌 😍 🥰 😘 😗 😙 😚 😋 😛 😝 😜

Font Combinations

Header Style (VT323, Perfect DOS VGA 437)

This is a paragraph in VT323 font. It's designed to look like old terminal text but with better readability for longer content blocks.

This is code text in Perfect DOS VGA 437 font.

Font Sizes Comparison

Heading 1 (26px)

Heading 2 (22px)

Heading 3 (20px)

Regular paragraph text (20px)

Small text (16px)

Extra small text (14px)

Shortcodes

The theme includes various shortcodes to enhance your content with retro-style elements.

Infoboxes

Infoboxes are used to highlight important information in different styles:

Information Box

ℹ️ INFORMATION
This is a standard information box for general notices and information.

Warning Box

⚠️ WARNING
This is a warning box for important notices and potential issues.

Tip Box

💡 TIP
This is a helpful tip to improve your experience with the theme.

Retro Dividers

Dividers help separate content sections with retro-style lines:

Single Line Divider

Double Line Divider

Dashed Line Divider

ASCII Art

The theme supports ASCII art through a dedicated shortcode:

  ____      _             ____            _          
 / ___|_ __(_) |_ _   _  | __ )  __ _ ___(_) ___ ___ 
| |   | '__| | __| | | | |  _ \ / _` / __| |/ __/ __|
| |___| |  | | |_| |_| | | |_) | (_| \__ \ | (__\__ \
 \____|_|  |_|\__|\__, | |____/ \__,_|___/_|\___|___/
                  |___/

 _____  _____  _____  _____  _____  _____  _____  _____  _____  _____ 
|_____||_____||_____||_____||_____||_____||_____||_____||_____||_____|
                                                                      
 _____                                                         _____ 
|_____|  _____ _____ _____ _____ _____ _____ _____ _____      |_____|
        |_____||_____||_____||_____||_____||_____||_____|            
 _____                                                         _____ 
|_____|  _____ _____ _____ _____ _____ _____ _____ _____      |_____|
        |_____||_____||_____||_____||_____||_____||_____|            
 _____                                                         _____ 
|_____||_____||_____||_____||_____||_____||_____||_____||_____||_____|

  _______ _    _ ______  __  __  ______      _______ _    _ _____  ______          _______ ______ 
 |__   __| |  | |  ____|/_ |/_ |/ __ \ \    / / ____| |  | |  __ \|  ____|   /\   |__   __|  ____|
    | |  | |__| | |__    | | | | |  | \ \  / / (___ | |__| | |  | | |__     /  \     | |  | |__   
    | |  |  __  |  __|   | | | | |  | |\ \/ / \___ \|  __  | |  | |  __|   / /\ \    | |  |  __|  
    | |  | |  | | |____  | | | | |__| | \  /  ____) | |  | | |__| | |____ / ____ \   | |  | |____ 
    |_|  |_|  |_|______| |_| |_|\____/   \/  |_____/|_|  |_|_____/|______/_/    \_\  |_|  |______|
                                                                                                  
  _______ _    _ ______  __  __  ______      _______ _    _ _____  ______          _______ ______ 
 |__   __| |  | |  ____|/_ |/_ |/ __ \ \    / / ____| |  | |  __ \|  ____|   /\   |__   __|  ____|
    | |  | |__| | |__    | | | | |  | \ \  / / (___ | |__| | |  | | |__     /  \     | |  | |__   
    | |  |  __  |  __|   | | | | |  | |\ \/ / \___ \|  __  | |  | |  __|   / /\ \    | |  |  __|  
    | |  | |  | | |____  | | | | |__| | \  /  ____) | |  | | |__| | |____ / ____ \   | |  | |____ 
    |_|  |_|  |_|______| |_| |_|\____/   \/  |_____/|_|  |_|_____/|______/_/    \_\  |_|  |______|
                                                                                                  
  _______ _    _ ______  __  __  ______      _______ _    _ _____  ______          _______ ______ 
 |__   __| |  | |  ____|/_ |/_ |/ __ \ \    / / ____| |  | |  __ \|  ____|   /\   |__   __|  ____|
    | |  | |__| | |__    | | | | |  | \ \  / / (___ | |__| | |  | | |__     /  \     | |  | |__   
    | |  |  __  |  __|   | | | | |  | |\ \/ / \___ \|  __  | |  | |  __|   / /\ \    | |  |  __|  
    | |  | |  | | |____  | | | | |__| | \  /  ____) | |  | | |__| | |____ / ____ \   | |  | |____ 
    |_|  |_|  |_|______| |_| |_|\____/   \/  |_____/|_|  |_|_____/|______/_/    \_\  |_|  |______|

Additional Code Examples

Rust Example (Zola is written in Rust!)

use std::collections::HashMap;

fn main() {
    // Create a new HashMap to store user scores
    let mut scores = HashMap::new();
    
    // Insert some values
    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);
    scores.insert(String::from("Red"), 25);
    
    // Access a value
    let team_name = String::from("Blue");
    let score = scores.get(&team_name).unwrap_or(&0);
    
    println!("Team {} score: {}", team_name, score);
    
    // Iterate over all key-value pairs
    for (key, value) in &scores {
        println!("{}: {}", key, value);
    }
}

HTML Example

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
    <title>Retro Web Page</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <style type="text/css">
        body {
            background-color: #000000;
            color: #33ff33;
            font-family: "Courier New", monospace;
        }
        table {
            border-collapse: collapse;
            width: 100%;
        }
        td {
            border: 1px solid #444444;
            padding: 8px;
        }
    </style>
</head>
<body>
    <h1>Welcome to My Retro Website</h1>
    <p>This is a simple example of HTML 4.01 Strict.</p>
    <table>
        <tr>
            <td>Row 1, Cell 1</td>
            <td>Row 1, Cell 2</td>
        </tr>
        <tr>
            <td>Row 2, Cell 1</td>
            <td>Row 2, Cell 2</td>
        </tr>
    </table>
</body>
</html>

Layout Features

The theme uses a three-column layout:

Left Sidebar: Navigation, search, and status panels
Main Content: Articles and primary content
Right Sidebar: Additional links, visitor counter, and GIF panels

The layout automatically collapses on mobile devices for better readability.

Retro Panels

The theme includes various retro-style panels:

Status Panel: Displays an animated GIF showing the current status
Links Panel: List of useful web links with matching emojis
Obligatory GIFs Panel: Display of animated GIFs in retro style
Visitor Counter: Cookie-free page-load counter with a digital display

Visitor Counter and System Uptime

The visitor panel is intentionally small and old-web styled, but it uses two different mechanisms:

System uptime is calculated in the browser from the configured site_launch_date. It needs no cookies or network request.
Visitors is a page-load counter. The browser requests an invisible static pixel once per page load. A systemd timer on the host reads only these Nginx log entries every minute and writes the accumulated total to visitor-count.json.

The counter does not set cookies and its counter script does not store IP addresses, user agents, referrers, or other visitor profiles. It measures page loads since the counter was activated, rather than unique people.

The supporting host files live in visitor-counter/: count-visits.sh, criticalbasics-visitor-counter.service, and criticalbasics-visitor-counter.timer. They are infrastructure for the deployed static site, not files interpreted by Zola.

Featured Article Images

Posts may opt into a featured image with three optional values in their [extra] front matter. When no featured_image is supplied, no image is rendered.

[extra]
featured_image = "pics/posts/my-image.png"
featured_image_alt = "Concise description of the image"
featured_image_caption = "Optional caption"

Featured images appear below the article metadata and open at full size when clicked. On the homepage, an explicitly configured image becomes the right-hand thumbnail beside the article excerpt.

Improved Accessibility

The theme has been equipped with numerous accessibility improvements:

Skip Links: Allow skipping the navigation to get directly to the main content.
Focus Indicators: Clearly visible focus styles for all interactive elements.
Screen Reader Support: Use of ARIA attributes and semantic HTML.
High Contrast: High-contrast color scheme for better readability.

Customization Options

The theme offers extensive customization options:

Central configuration in sass/partials/_variables.scss
Customizable header with background image
Adjustable logo sizes for desktop and mobile
Configurable GIF panels in different areas of the page
Button styling and appearance settings

💡 CUSTOMIZATION TIP
All design elements can be configured centrally in the file `sass/partials/_variables.scss`, making it easy to maintain a consistent look throughout your site.

Form Elements

The theme includes retro-styled form elements:

Tables

The Retro-Compatible Zola Theme offers three different table shortcodes, each optimized for different use cases.

Table with Custom Column Widths

The table shortcode allows you to set the width of each column individually. The column widths are specified as percentages and must add up to 100%.

Syntax:

{% table(cols="30%,70%") %}
| Property | Description |
|----------|-------------|
| Name     | The name of the property |
| Value    | A longer description that needs more space |
{% end %}

Example:

  <colgroup>
    
      <col width="30%">
    
      <col width="70%">
    
  </colgroup>


<thead><tr><th>Property</th><th>Description</th></tr></thead><tbody>

Name	The name of the property
Value	A longer description that needs more space

Example with 4 Columns of Different Sizes

You can define any number of columns with different widths:

{% table(cols="15%,25%,20%,40%") %}
| ID | Category | Priority | Description |
|----|----------|----------|-------------|
| 001 | Hardware | High | New graphics card for workstation |
| 002 | Software | Medium | Operating system update |
| 003 | Network  | Low      | Office Wi-Fi optimization |
{% end %}

The result looks like this:

  <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>

001	Hardware	High	New graphics card for workstation
002	Software	Medium	Operating system update
003	Network	Low	Office Wi-Fi optimization

Shortcut Table

The shortcut_table 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.

Syntax:

{% shortcut_table() %}
| Action | Shortcut |
|--------|----------|
| Copy | Ctrl+C |
| Paste | Ctrl+V |
{% end %}

Example:

Action	Shortcut
Copy	Ctrl+C
Paste	Ctrl+V
Save	Ctrl+S
Open	Ctrl+O

Changelog Table

The changelog_table shortcode is optimized for changelogs. It gives the date column a fixed width (100px) so that dates are displayed uniformly.

Syntax:

{% changelog_table() %}
| Date | Changes |
|------|--------|
| 2025-01-01 | Initial release |
| 2025-01-15 | Bug fixes |
{% end %}

Example: The changelog table at the beginning of this page uses the changelog_table shortcode.

Note on Displaying Shortcode Examples

To display shortcode examples in the documentation without them being executed, a special trick is used: invisible spaces (Zero-Width Spaces \u200b) 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.

Example: {\u200b% shortcode %\u200b} instead of {% shortcode %} (with an invisible space between { and % and between % and })

Markdown Troubleshooting

Common Layout Issues

When working with this theme (or any Markdown-based system), certain formatting issues can break your layout. Here are some common problems and solutions:

HTML-Like Syntax in Markdown

⚠️ AVOID RAW HTML TAGS IN TEXT
Using angle brackets (`<` and `>`) 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.

Problem Example:

Select **<Yes>** to enable automatic updates.

In this example, <Yes> might be interpreted as an HTML tag named “Yes”, causing layout issues.

Solutions:

Use quotes instead of angle brackets:

Select **"Yes"** to enable automatic updates.

Use backticks to format as code:

Select **`<Yes>`** to enable automatic updates.

Use HTML entities:

Select **&lt;Yes&gt;** to enable automatic updates.

Use escape characters:

Select **\<Yes\>** to enable automatic updates.

Other Common Markdown Issues

Unclosed code blocks: Always ensure your code blocks have opening and closing backticks on their own lines.
Malformed tables: Tables require a specific format with headers and separators.
Nested HTML: Be careful when nesting HTML elements inside Markdown content.

💡 DEBUGGING LAYOUT ISSUES
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.

Getting Started

ℹ️ GETTING STARTED
To get started with this theme: Clone the repository into your Zola `themes` directory Activate the theme in your `config.toml` Run `zola serve` to see a preview For detailed instructions, see the Main Documentation.

Conclusion

The Retro-Compatible Zola Theme offers a unique combination of nostalgic design and modern functionality. It’s perfect for:

Retro computing enthusiasts
Digital preservation projects
Personal websites with a nostalgic touch
Anyone who appreciates the aesthetic of early web design

criticalbasics

Fetch, Review, Accept: Syncing Dotfiles and pass over SSH

Changelog

1. Why Git Fits This Job

2. Shared Configuration, Host Differences, and Stow

First-Time Setup Is Separate from Everyday Sync

3. Set Up SSH and the First Repository

4. One Peer List, One Interactive Script

Updating the Other Device Immediately

More Than Two Devices

5. Use the Same Routine for pass

6. Resolve Conflicts Without Changing Live Files First

7. Optional Remote and Backups

Sources

Duke Nukem II: 5 Handy DOS-Era Tricks for Rigelatin

Five tricks worth remembering

Play it legally

Sources

Micro Machines: Tiny Cars, Giant Kitchen-Table Chaos

The useful stuff the game barely tells you

Play it legally

Sources

Stunts: The DOS Racer That Lets You Build the Impossible

Five tricks for better laps and better tracks

Play it legally

Sources

Total Recall (1990): Details Worth a Second Memory

Details worth watching for

Sources

Deploying the Nextcloud Talk AIO Recording Backend as a Standalone Container

Changelog

1. Prerequisites

2. Create the project directory and secrets

3. Create the Docker Compose file

4. Start and verify the recorder

5. Configure the Recording Backend in Nextcloud Talk

6. Make a real recording test

7. Multiple independent Nextcloud instances

8. Maintenance and troubleshooting

Related tutorials

Running the Nextcloud Talk AIO Container as a Standalone High-Performance Backend

Changelog

1. Prerequisites

1.1. Firewall configuration

2. Create the project directory and secrets

3. Create the Docker Compose file

4. Start and verify the backend

5. Configure Nextcloud Talk

5.1. Configure it using occ (optional)

6. Test a real call

7. Maintenance and updates

8. Running multiple independent Nextcloud instances

9. Recording backend scope

10. Troubleshooting

The High-Performance Backend check fails

Calls connect but media does not work

The container cannot contact Nextcloud

Conclusion

Related tutorials

Running Hermes Agent Across Multiple Devices with Forgejo and Matrix

Changelog

1. Reference Architecture

2. Shared and Local Boundaries

3. Prerequisites and Version Discipline

Hermes 0.21 Features Relevant to a Fleet

4. Build the Shared Repository

5. Profile Distributions and Capability Policy

6. Install and Update the Role Profiles

7. Provider Authentication Ownership

Choose the Cross-Host Model Deliberately

8. Guarded Forgejo Synchronization

8.1. Create the Synchronizer

8.2. Create the systemd User Units

8.3. Publish Reviewed Changes Explicitly

9. Knowledge Search and Handoffs

10. Matrix Gateways and E2EE

11. Mail, Calendar, and File Mirrors

11.1. Use Bounded Domain Snapshots for Scheduled Briefings

12. Security Model

13. Backups and Recovery

5.1. Configure it using `occ` (optional)

3.2. Nginx Configuration (`config/nginx.conf`)

`config/custom.conf` (Performance Tuning)

`config/pg_hba.conf` (Authentication Rules)

3.4. Lemmy Configuration (`config/lemmy.hjson`)

3.5. Docker Compose (`docker-compose.yml`)